src/key_reset.h
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Wed, 10 Apr 2019 19:17:42 +0200
branchENGINE-536
changeset 3495 b4d3e47eab14
parent 2950 753276eb09ec
child 3498 9c7f5f60094e
permissions -rw-r--r--
ENGINE-536: newly refactored key_reset with new functions in. Passes current tests, but need to check new functions.
     1 // This file is under GNU General Public License 3.0
     2 // see LICENSE.txt
     3 
     4 #pragma once
     5 
     6 #include "key_reset.h"
     7 
     8 #include "pEpEngine.h"
     9 #include "keymanagement.h"
    10 #include "message.h"
    11 #include "message_api.h"
    12 #include "cryptotech.h"
    13 
    14 #ifdef __cplusplus
    15 extern "C" {
    16 #endif
    17 
    18 // key_reset_identity() - resets trust status for this identity and fpr, and remove
    19 //                        this fpr as a default for all identities and users and from 
    20 //                        the keyring.
    21 //                        
    22 //                        If the fpr is NULL, we will reset the identity default fpr
    23 //                        as above. When that does not exist, then we do it for 
    24 //                        the user default. 
    25 //
    26 //                        For own identities, when the fpr has a private key part,
    27 //                        also revoke the key and communicate the revocation and new key 
    28 //                        to partners we have sent mail to recently from the specific identity 
    29 //                        (i.e. address/user_id) that contacted them. We also in this case 
    30 //                        set up information so that if someone we mail uses the wrong key 
    31 //                        and wasn't yet contacted, we can send them the reset information 
    32 //                        from the right address. 
    33 //
    34 //  parameters:
    35 //      session (in)            session handle
    36 //      fpr (in)                fingerprint of key to reset. If NULL, we reset the default key
    37 //                              this user, if there is one.
    38 //      ident (in)              identity for which the key reset should occur. Must contain 
    39 //                              user_id and address.
    40 //
    41 //                              fpr field will be ignored. Cannot be NULL.
    42 //
    43 //      Note: ident->fpr is always ignored
    44 //
    45 //
    46 DYNAMIC_API PEP_STATUS key_reset_identity(
    47         PEP_SESSION session,
    48         const char* fpr,
    49         pEp_identity* ident
    50     );
    51 
    52 // key_reset_user() - reset the default key database status for each identity 
    53 //                    corresponding to this user and fpr (if present), and remove from 
    54 //                    the keyring. This will also remove the key(s) from all other 
    55 //                    users and identities. If no fpr is present, reset all default keys 
    56 //                    corresponding to this user and its identities.
    57 //           
    58 //                    For own keys, also revoke the key(s) and communicate the 
    59 //                    revocation and new key(s) to partners we have sent mail to 
    60 //                    recently from the specific identities (i.e. address/user_id) 
    61 //                    that contacted them. We also in this case set up information 
    62 //                    so that if someone we mail uses the wrong key and wasn't 
    63 //                    yet contacted, we can send them the reset information 
    64 //                    from the right address.
    65 //
    66 //                    If the user_id is NULL and fpr is NULL, we reset all keys for the own user. 
    67 //
    68 //  parameters:
    69 //      session (in)            session handle
    70 //      fpr (in)                fingerprint of key to reset. If NULL and user_id is NULL,
    71 //                              we reset all keys for the own user. If NULL, we reset all default 
    72 //                              keys for this user and all of its identities.
    73 //      user_id (in)            user_id for which the key reset should occur.
    74 //                              If the user_id is NULL, we reset keys for the own user.
    75 //
    76 DYNAMIC_API PEP_STATUS key_reset_user(
    77         PEP_SESSION session,
    78         const char* fpr,
    79         const char* user_id
    80     );
    81 
    82 // key_reset() - reset the database status for a key, removing all trust information
    83 //               and default database connections. For own keys, also revoke the key
    84 //               and communicate the revocation and new key to partners we have sent
    85 //               mail to recently from the specific identity (i.e. address/user_id)
    86 //               that contacted them. We also in this case set up information so that
    87 //               if someone we mail uses the wrong key and wasn't yet contacted,
    88 //               we can send them the reset information from the right address.
    89 //
    90 //               Can be called manually or through another protocol.
    91 //
    92 //  parameters:
    93 //      session (in)            session handle
    94 //      fpr (in)                fingerprint of key to reset. If NULL and ident is NULL,
    95 //                              we reset all keys for the own user. If NULL and ident is
    96 //                              an own identity, we reset the default key for that
    97 //                              identity. If that own identity has no default key, we
    98 //                              reset the user default.
    99 //                              if it is NULL and there is a non-own identity, we will reset 
   100 //                              the default key for this identity.
   101 //      ident (in)              identity for which the key reset should occur.
   102 //                              if NULL and fpr is non-NULL, we'll reset the key for all
   103 //                              associated identities. If both ident and fpr are NULL, see 
   104 //                              the fpr arg documentation.
   105 //
   106 //      Note: ident->fpr is always ignored
   107 //
   108 // Caveat: this is now used in large part for internal calls.
   109 //         external apps should call key_reset_identity and key_reset_userdata
   110 //         and this function should probably be removed from the dynamic api
   111 PEP_STATUS key_reset(
   112         PEP_SESSION session,
   113         const char* fpr,
   114         pEp_identity* ident
   115     );
   116 
   117 
   118 
   119 PEP_STATUS has_key_reset_been_sent(
   120         PEP_SESSION session, 
   121         const char* user_id, 
   122         const char* revoked_fpr,
   123         bool* contacted);
   124 
   125 PEP_STATUS set_reset_contact_notified(
   126         PEP_SESSION session,
   127         const char* revoke_fpr,
   128         const char* contact_id
   129     );
   130 
   131 PEP_STATUS receive_key_reset(PEP_SESSION session,
   132                              message* reset_msg);
   133 
   134 PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
   135                                                message** dst, 
   136                                                pEp_identity* recip,
   137                                                const char* old_fpr,
   138                                                const char* new_fpr);
   139                                                
   140 PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
   141                                      const char* old_fpr, 
   142                                      const char* new_fpr);
   143     
   144 #ifdef __cplusplus
   145 }
   146 #endif