Browse Source

ENGINE-536: updated API functions and docs.

pEpMIME_windows
parent
commit
c38aed88a9
2 changed files with 49 additions and 59 deletions
  1. +17
    -16
      src/key_reset.c
  2. +32
    -43
      src/key_reset.h

+ 17
- 16
src/key_reset.c View File

@ -325,11 +325,11 @@ pEp_free:
DYNAMIC_API PEP_STATUS key_reset_identity(
PEP_SESSION session,
const char* fpr,
pEp_identity* ident
pEp_identity* ident,
const char* fpr
)
{
if (!session || (ident && EMPTYSTR(ident->user_id)))
if (!session || !ident || (ident && (EMPTYSTR(ident->user_id) || EMPTYSTR(ident->address))))
return PEP_ILLEGAL_VALUE;
return key_reset(session, fpr, ident);
@ -337,26 +337,27 @@ DYNAMIC_API PEP_STATUS key_reset_identity(
DYNAMIC_API PEP_STATUS key_reset_user(
PEP_SESSION session,
const char* fpr,
const char* user_id
const char* user_id,
const char* fpr
)
{
if (!session)
if (!session || EMPTYSTR(user_id))
return PEP_ILLEGAL_VALUE;
pEp_identity* input_ident = NULL;
if (!EMPTYSTR(user_id)) {
input_ident = new_identity(NULL, NULL, NULL, user_id);
if (!input_ident)
return PEP_OUT_OF_MEMORY;
}
pEp_identity* input_ident = new_identity(NULL, NULL, user_id, NULL);
if (!input_ident)
return PEP_OUT_OF_MEMORY;
if (is_me(session, input_ident) && EMPTYSTR(fpr))
return PEP_ILLEGAL_VALUE;
PEP_STATUS status = key_reset(session, fpr, input_ident);
free_identity(input_ident);
return status;
return status;
}
DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session) {
return key_reset(session, NULL, NULL);
}
// Notes to integrate into header:


+ 32
- 43
src/key_reset.h View File

@ -16,59 +16,31 @@ extern "C" {
#endif
// key_reset_identity() - reset the default database status for the identity / keypair
// provided. If this corresponds to the own user and a private key,
// provided. If this corresponds to an own identity and a private key,
// also revoke the key, generate a new one, and communicate the
// reset to recently contacted pEp partners for this identity.
//
// If it does not, remove the key from the keyring; the key's
// status is completely fresh on next contact from the partner.
//
// If ident contains both a user_id and an address, and this is
// not the own_user:
// 1. If the fpr is non-NULL, we will delete this key from the keyring,
// remove this fpr as the default for all users and all identities,
// and remove all key information for this key in the DB
// 2. If the fpr IS NULL, we will do what is in step 1 for the default
// key for this identity, and if there is not one, we do it for the
// user default key.
//
// If ident contains both a user_id and an address, and
// this IS the own_user:
// 1. If the fpr is non-NULL and the corresponding key has a private part,
// we will revoke and mistrust this key, generate a new key for this identity,
// and communicate the revocation and new key to partners we have
// sent mail to recently from the specific identity (i.e. address/user_id)
// that contacted them. We also in this case set up information so
// that if someone we mail uses the wrong key and wasn't yet contacted,
// we can send them the reset information from the right address.
// 2. If the fpr is non-NULL and does NOT correspond to a private key,
// this behaves the same way as with a non-own user above.
// 3. If the fpr is NULL, we perform the steps in 1. of this section for
// the identity default if it exists, and if not, the user default.
//
// If the ident only contains a user_id, we perform the above for every key
// associated with the user id. In the case of own private keys, we then
// go through each identity associated with the key and reset those identities
// as indicated above. (keys not associated with any identity will not
// have replacement information or keys generated)
//
// If the identity is NULL, this is the same as calling the function with an
// identity containing only the own user_id (and no address).
// If no key is provided, reset the identity default.
//
// Note that reset keys will be removed as defaults for all users and identities.
//
// parameters:
// session (in) session handle
// fpr (in) fingerprint of key to reset. If NULL, we reset the default key
// this identity if there is one, and the user default if not.
// ident (in) identity for which the key reset should occur. Must contain
// user_id, at a minimum. If it contains no address, all keys for this user
// are reset. If NULL, all keys for the own user will be reset.
// user_id and address. Must not be NULL.
//
// Note: ident->fpr field will be ignored.
//
//
DYNAMIC_API PEP_STATUS key_reset_identity(
PEP_SESSION session,
const char* fpr,
pEp_identity* ident
pEp_identity* ident,
const char* fpr
);
// key_reset_user() - reset the default database status for the user / keypair
@ -77,23 +49,40 @@ DYNAMIC_API PEP_STATUS key_reset_identity(
// provided, and for each key (and all of their identities) if an fpr
// is not.
//
// See key_reset_identity() under identities containing only user_id.
// If the user_id is the own user_id, an fpr MUST be provided.
// For a reset of all own user keys, call key_reset_all_own_keys() instead.
//
// Note that reset keys will be removed as defaults for all users and identities.
//
// parameters:
// session (in) session handle
// fpr (in) fingerprint of key to reset. If NULL and user_id is NULL,
// we reset all keys for the own user. If NULL, we reset all default
// user_id (in) user_id for which the key reset should occur. If this
// is the own user_id, for MUST NOT be NULL.
// fpr (in) fingerprint of key to reset.
// If NULL, we reset all default
// keys for this user and all of its identities.
// user_id (in) user_id for which the key reset should occur.
// If the user_id is NULL, we reset keys for the own user.
// *** However, it is forbidden to use the own user_id
// here when the fpr is NULL. For this functionality,
// call key_reset_all_own_keys ***
//
DYNAMIC_API PEP_STATUS key_reset_user(
PEP_SESSION session,
const char* fpr,
const char* user_id
const char* user_id,
const char* fpr
);
// key_reset_all_own_keys() - revoke and mistrust all own keys, generate new keys for all
// own identities, and opportunistically communicate
// key reset information to people we have recently
// contacted.
//
// parameters:
// session (in) session handle
//
DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session);
// key_reset() - reset the database status for a key, removing all trust information
// and default database connections. For own keys, also revoke the key
// and communicate the revocation and new key to partners we have sent


Loading…
Cancel
Save