src/key_reset.h
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Tue, 16 Apr 2019 13:09:07 +0200
branchdelete_key
changeset 3529 134adf5bd9b7
parent 3503 2bfea9b0d0fd
child 3967 e4365dde0495
permissions -rw-r--r--
Rest of key_reset tests
     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() - reset the default database status for the identity / keypair
    19 //                        provided. If this corresponds to an own identity and a private key,
    20 //                        also revoke the key, generate a new one, and communicate the 
    21 //                        reset to recently contacted pEp partners for this identity.
    22 //
    23 //                        If it does not, remove the key from the keyring; the key's 
    24 //                        status is completely fresh on next contact from the partner.
    25 //
    26 //                        If no key is provided, reset the identity default.
    27 //
    28 //                        Note that reset keys will be removed as defaults for all users and identities.
    29 //
    30 //  parameters:
    31 //      session (in)            session handle
    32 //      fpr (in)                fingerprint of key to reset. If NULL, we reset the default key
    33 //                              this identity if there is one, and the user default if not.
    34 //      ident (in)              identity for which the key reset should occur. Must contain 
    35 //                              user_id and address. Must not be NULL.
    36 //
    37 //                              Note: ident->fpr field will be ignored.
    38 //
    39 //
    40 DYNAMIC_API PEP_STATUS key_reset_identity(
    41         PEP_SESSION session,
    42         pEp_identity* ident,
    43         const char* fpr
    44     );
    45 
    46 // key_reset_user() -  reset the default database status for the user / keypair
    47 //                     provided. This will effectively perform key_reset_identity()
    48 //                     each identity associated with the key and user_id, if a key is
    49 //                     provided, and for each key (and all of their identities) if an fpr 
    50 //                     is not.
    51 //
    52 //                     If the user_id is the own user_id, an fpr MUST be provided.
    53 //                     For a reset of all own user keys, call key_reset_all_own_keys() instead.
    54 //
    55 //                     Note that reset keys will be removed as defaults for all users and identities.
    56 //
    57 //  parameters:
    58 //      session (in)            session handle
    59 //      user_id (in)            user_id for which the key reset should occur. If this 
    60 //                              is the own user_id, fpr MUST NOT be NULL.
    61 //      fpr (in)                fingerprint of key to reset.
    62 //                              If NULL, we reset all default 
    63 //                              keys for this user and all of its identities.
    64 //                              *** However, it is forbidden to use the own user_id 
    65 //                                  here when the fpr is NULL. For this functionality, 
    66 //                                  call key_reset_all_own_keys ***
    67 
    68 //
    69 DYNAMIC_API PEP_STATUS key_reset_user(
    70         PEP_SESSION session,
    71         const char* user_id,
    72         const char* fpr
    73     );
    74 
    75 // key_reset_all_own_keys() -  revoke and mistrust all own keys, generate new keys for all 
    76 //                             own identities, and opportunistically communicate
    77 //                             key reset information to people we have recently 
    78 //                             contacted. 
    79 //
    80 // caveat: this will return PEP_CANNOT_FIND_IDENTITY if no own user yet exists.
    81 //         HOWEVER, apps and adapters must decide if this is a reasonable state;
    82 //         since the period where no own user exists will necessarily be very short
    83 //         in most implementations, PEP_CANNOT_FIND_IDENTITY may be returned when 
    84 //         there is some sort of DB corruption and we expect there to be an own user.
    85 //         Apps are responsible for deciding whether or not this is an error condition;
    86 //         one would expect that it generally is (rather than the uninitialised DB case)
    87 //                             
    88 //  parameters:
    89 //      session (in)            session handle
    90 //
    91 DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session);
    92 
    93 
    94 // key_reset() - reset the database status for a key, removing all trust information
    95 //               and default database connections. For own keys, also revoke the key
    96 //               and communicate the revocation and new key to partners we have sent
    97 //               mail to recently from the specific identity (i.e. address/user_id)
    98 //               that contacted them. We also in this case set up information so that
    99 //               if someone we mail uses the wrong key and wasn't yet contacted,
   100 //               we can send them the reset information from the right address. 
   101 //               For non-own keys, also remove key from the keyring.
   102 //
   103 //               Can be called manually or through another protocol.
   104 //
   105 //  parameters:
   106 //      session (in)            session handle
   107 //      fpr (in)                fingerprint of key to reset. If NULL and ident is NULL,
   108 //                              we reset all keys for the own user. If NULL and ident is
   109 //                              an own identity, we reset the default key for that
   110 //                              identity. If that own identity has no default key, we
   111 //                              reset the user default.
   112 //                              if it is NULL and there is a non-own identity, we will reset 
   113 //                              the default key for this identity if present, and user if not.
   114 //      ident (in)              identity for which the key reset should occur.
   115 //                              if NULL and fpr is non-NULL, we'll reset the key for all
   116 //                              associated identities. If both ident and fpr are NULL, see 
   117 //                              the fpr arg documentation.
   118 //
   119 //      Note: ident->fpr is always ignored
   120 //
   121 // Caveat: this is now used in large part for internal calls.
   122 //         external apps should call key_reset_identity and key_reset_userdata
   123 //         and this function should probably be removed from the dynamic api
   124 PEP_STATUS key_reset(
   125         PEP_SESSION session,
   126         const char* fpr,
   127         pEp_identity* ident
   128     );
   129 
   130 
   131 
   132 PEP_STATUS has_key_reset_been_sent(
   133         PEP_SESSION session, 
   134         const char* user_id, 
   135         const char* revoked_fpr,
   136         bool* contacted);
   137 
   138 PEP_STATUS set_reset_contact_notified(
   139         PEP_SESSION session,
   140         const char* revoke_fpr,
   141         const char* contact_id
   142     );
   143 
   144 PEP_STATUS receive_key_reset(PEP_SESSION session,
   145                              message* reset_msg);
   146 
   147 PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
   148                                                message** dst, 
   149                                                pEp_identity* recip,
   150                                                const char* old_fpr,
   151                                                const char* new_fpr);
   152                                                
   153 PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
   154                                      const char* old_fpr, 
   155                                      const char* new_fpr);
   156     
   157 #ifdef __cplusplus
   158 }
   159 #endif