ENGINE-538: fixed documentation sync
authorKrista 'DarthMama' Bennett <krista@pep.foundation>
Wed, 10 Apr 2019 20:04:53 +0200
branchsync
changeset 34989c7f5f60094e
parent 3497 f0afea7fbc1b
child 3500 03b6c918d0b4
child 3502 703cf9bc3139
ENGINE-538: fixed documentation
src/key_reset.h
     1.1 --- a/src/key_reset.h	Wed Apr 10 19:20:00 2019 +0200
     1.2 +++ b/src/key_reset.h	Wed Apr 10 20:04:53 2019 +0200
     1.3 @@ -15,32 +15,54 @@
     1.4  extern "C" {
     1.5  #endif
     1.6  
     1.7 -// key_reset_identity() - resets trust status for this identity and fpr, and remove
     1.8 -//                        this fpr as a default for all identities and users and from 
     1.9 -//                        the keyring.
    1.10 +// key_reset_identity() - reset the default database status for the identity / keypair
    1.11 +//                        provided. If this corresponds to the own user and a private key,
    1.12 +//                        also revoke the key, generate a new one, and communicate the 
    1.13 +//                        reset to recently contacted pEp partners for this identity.
    1.14 +//                        If it does not, remove the key from the keyring; the key's 
    1.15 +//                        status is completely fresh on next contact from the partner.
    1.16 +//
    1.17 +//                        If ident contains both a user_id and an address, and this is 
    1.18 +//                        not the own_user:
    1.19 +//                        1. If the fpr is non-NULL, we will delete this key from the keyring, 
    1.20 +//                           remove this fpr as the default for all users and all identities,
    1.21 +//                           and remove all key information for this key in the DB
    1.22 +//                        2. If the fpr IS NULL, we will do what is in step 1 for the default 
    1.23 +//                           key for this identity, and if there is not one, we do it for the 
    1.24 +//                           user default key.                             
    1.25  //                        
    1.26 -//                        If the fpr is NULL, we will reset the identity default fpr
    1.27 -//                        as above. When that does not exist, then we do it for 
    1.28 -//                        the user default. 
    1.29 +//                        If ident contains both a user_id and an address, and 
    1.30 +//                        this IS the own_user:
    1.31 +//                        1. If the fpr is non-NULL and the corresponding key has a private part,
    1.32 +//                           we will revoke and mistrust this key, generate a new key for this identity,
    1.33 +//                           and communicate the revocation and new key to partners we have 
    1.34 +//                           sent mail to recently from the specific identity (i.e. address/user_id) 
    1.35 +//                           that contacted them. We also in this case set up information so 
    1.36 +//                           that if someone we mail uses the wrong key and wasn't yet contacted, 
    1.37 +//                           we can send them the reset information from the right address.
    1.38 +//                        2. If the fpr is non-NULL and does NOT correspond to a private key,
    1.39 +//                           this behaves the same way as with a non-own user above.
    1.40 +//                        3. If the fpr is NULL, we perform the steps in 1. of this section for 
    1.41 +//                           the identity default if it exists, and if not, the user default. 
    1.42  //
    1.43 -//                        For own identities, when the fpr has a private key part,
    1.44 -//                        also revoke the key and communicate the revocation and new key 
    1.45 -//                        to partners we have sent mail to recently from the specific identity 
    1.46 -//                        (i.e. address/user_id) that contacted them. We also in this case 
    1.47 -//                        set up information so that if someone we mail uses the wrong key 
    1.48 -//                        and wasn't yet contacted, we can send them the reset information 
    1.49 -//                        from the right address. 
    1.50 +//                        If the ident only contains a user_id, we perform the above for every key 
    1.51 +//                        associated with the user id. In the case of own private keys, we then 
    1.52 +//                        go through each identity associated with the key and reset those identities 
    1.53 +//                        as indicated above. (keys not associated with any identity will not
    1.54 +//                        have replacement information or keys generated)
    1.55 +//
    1.56 +//                        If the identity is NULL, this is the same as calling the function with an
    1.57 +//                        identity containing only the own user_id (and no address).
    1.58  //
    1.59  //  parameters:
    1.60  //      session (in)            session handle
    1.61  //      fpr (in)                fingerprint of key to reset. If NULL, we reset the default key
    1.62 -//                              this user, if there is one.
    1.63 +//                              this identity if there is one, and the user default if not.
    1.64  //      ident (in)              identity for which the key reset should occur. Must contain 
    1.65 -//                              user_id and address.
    1.66 +//                              user_id, at a minimum. If it contains no address, all keys for this user
    1.67 +//                              are reset. If NULL, all keys for the own user will be reset.
    1.68  //
    1.69 -//                              fpr field will be ignored. Cannot be NULL.
    1.70 -//
    1.71 -//      Note: ident->fpr is always ignored
    1.72 +//                              Note: ident->fpr field will be ignored.
    1.73  //
    1.74  //
    1.75  DYNAMIC_API PEP_STATUS key_reset_identity(
    1.76 @@ -49,21 +71,14 @@
    1.77          pEp_identity* ident
    1.78      );
    1.79  
    1.80 -// key_reset_user() - reset the default key database status for each identity 
    1.81 -//                    corresponding to this user and fpr (if present), and remove from 
    1.82 -//                    the keyring. This will also remove the key(s) from all other 
    1.83 -//                    users and identities. If no fpr is present, reset all default keys 
    1.84 -//                    corresponding to this user and its identities.
    1.85 -//           
    1.86 -//                    For own keys, also revoke the key(s) and communicate the 
    1.87 -//                    revocation and new key(s) to partners we have sent mail to 
    1.88 -//                    recently from the specific identities (i.e. address/user_id) 
    1.89 -//                    that contacted them. We also in this case set up information 
    1.90 -//                    so that if someone we mail uses the wrong key and wasn't 
    1.91 -//                    yet contacted, we can send them the reset information 
    1.92 -//                    from the right address.
    1.93 +// key_reset_user() -  reset the default database status for the user / keypair
    1.94 +//                     provided. This will effectively perform key_reset_identity()
    1.95 +//                     each identity associated with the key and user_id, if a key is
    1.96 +//                     provided, and for each key (and all of their identities) if an fpr 
    1.97 +//                     is not.
    1.98  //
    1.99 -//                    If the user_id is NULL and fpr is NULL, we reset all keys for the own user. 
   1.100 +//                     See key_reset_identity() under identities containing only user_id.
   1.101 +//
   1.102  //
   1.103  //  parameters:
   1.104  //      session (in)            session handle
   1.105 @@ -85,7 +100,8 @@
   1.106  //               mail to recently from the specific identity (i.e. address/user_id)
   1.107  //               that contacted them. We also in this case set up information so that
   1.108  //               if someone we mail uses the wrong key and wasn't yet contacted,
   1.109 -//               we can send them the reset information from the right address.
   1.110 +//               we can send them the reset information from the right address. 
   1.111 +//               For non-own keys, also remove key from the keyring.
   1.112  //
   1.113  //               Can be called manually or through another protocol.
   1.114  //
   1.115 @@ -97,7 +113,7 @@
   1.116  //                              identity. If that own identity has no default key, we
   1.117  //                              reset the user default.
   1.118  //                              if it is NULL and there is a non-own identity, we will reset 
   1.119 -//                              the default key for this identity.
   1.120 +//                              the default key for this identity if present, and user if not.
   1.121  //      ident (in)              identity for which the key reset should occur.
   1.122  //                              if NULL and fpr is non-NULL, we'll reset the key for all
   1.123  //                              associated identities. If both ident and fpr are NULL, see