src/key_reset.h
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Thu, 04 Jun 2020 11:18:45 +0200
changeset 4729 3df9a2a67597
parent 4505 c71ec33fb346
child 4792 7056435ab9e7
child 4885 babf5ac40215
permissions -rw-r--r--
forgot test files
krista@2947
     1
// This file is under GNU General Public License 3.0
krista@2947
     2
// see LICENSE.txt
krista@2947
     3
krista@2947
     4
#pragma once
krista@2947
     5
krista@2947
     6
#include "pEpEngine.h"
krista@2947
     7
#include "keymanagement.h"
krista@2947
     8
#include "message.h"
krista@2947
     9
#include "message_api.h"
krista@2947
    10
#include "cryptotech.h"
vb@4256
    11
#include "keyreset_command.h"
krista@2947
    12
krista@2947
    13
#ifdef __cplusplus
krista@2947
    14
extern "C" {
krista@2947
    15
#endif
krista@2947
    16
krista@3498
    17
// key_reset_identity() - reset the default database status for the identity / keypair
krista@3503
    18
//                        provided. If this corresponds to an own identity and a private key,
krista@3498
    19
//                        also revoke the key, generate a new one, and communicate the 
krista@3498
    20
//                        reset to recently contacted pEp partners for this identity.
krista@3503
    21
//
krista@3498
    22
//                        If it does not, remove the key from the keyring; the key's 
krista@3498
    23
//                        status is completely fresh on next contact from the partner.
krista@3495
    24
//
krista@3503
    25
//                        If no key is provided, reset the identity default.
krista@3498
    26
//
krista@3503
    27
//                        Note that reset keys will be removed as defaults for all users and identities.
krista@3495
    28
//
krista@3495
    29
//  parameters:
krista@3495
    30
//      session (in)            session handle
krista@3495
    31
//      fpr (in)                fingerprint of key to reset. If NULL, we reset the default key
krista@3498
    32
//                              this identity if there is one, and the user default if not.
krista@3495
    33
//      ident (in)              identity for which the key reset should occur. Must contain 
krista@3503
    34
//                              user_id and address. Must not be NULL.
krista@3495
    35
//
krista@3498
    36
//                              Note: ident->fpr field will be ignored.
krista@3495
    37
//
krista@3495
    38
//
krista@3495
    39
DYNAMIC_API PEP_STATUS key_reset_identity(
krista@3495
    40
        PEP_SESSION session,
krista@3503
    41
        pEp_identity* ident,
krista@3503
    42
        const char* fpr
krista@3495
    43
    );
krista@3495
    44
krista@3498
    45
// key_reset_user() -  reset the default database status for the user / keypair
krista@3498
    46
//                     provided. This will effectively perform key_reset_identity()
krista@3498
    47
//                     each identity associated with the key and user_id, if a key is
krista@3498
    48
//                     provided, and for each key (and all of their identities) if an fpr 
krista@3498
    49
//                     is not.
krista@3495
    50
//
krista@3503
    51
//                     If the user_id is the own user_id, an fpr MUST be provided.
krista@3503
    52
//                     For a reset of all own user keys, call key_reset_all_own_keys() instead.
krista@3498
    53
//
krista@3503
    54
//                     Note that reset keys will be removed as defaults for all users and identities.
krista@3495
    55
//
krista@3495
    56
//  parameters:
krista@3495
    57
//      session (in)            session handle
krista@3503
    58
//      user_id (in)            user_id for which the key reset should occur. If this 
krista@3529
    59
//                              is the own user_id, fpr MUST NOT be NULL.
krista@3503
    60
//      fpr (in)                fingerprint of key to reset.
krista@3503
    61
//                              If NULL, we reset all default 
krista@3495
    62
//                              keys for this user and all of its identities.
krista@3503
    63
//                              *** However, it is forbidden to use the own user_id 
krista@3503
    64
//                                  here when the fpr is NULL. For this functionality, 
krista@3503
    65
//                                  call key_reset_all_own_keys ***
krista@3503
    66
krista@3495
    67
//
krista@3495
    68
DYNAMIC_API PEP_STATUS key_reset_user(
krista@3495
    69
        PEP_SESSION session,
krista@3503
    70
        const char* user_id,
krista@3503
    71
        const char* fpr
krista@3495
    72
    );
krista@3495
    73
krista@3503
    74
// key_reset_all_own_keys() -  revoke and mistrust all own keys, generate new keys for all 
krista@3503
    75
//                             own identities, and opportunistically communicate
krista@3503
    76
//                             key reset information to people we have recently 
krista@3503
    77
//                             contacted. 
krista@3529
    78
//
krista@3529
    79
// caveat: this will return PEP_CANNOT_FIND_IDENTITY if no own user yet exists.
krista@3529
    80
//         HOWEVER, apps and adapters must decide if this is a reasonable state;
krista@3529
    81
//         since the period where no own user exists will necessarily be very short
krista@3529
    82
//         in most implementations, PEP_CANNOT_FIND_IDENTITY may be returned when 
krista@3529
    83
//         there is some sort of DB corruption and we expect there to be an own user.
krista@3529
    84
//         Apps are responsible for deciding whether or not this is an error condition;
krista@3529
    85
//         one would expect that it generally is (rather than the uninitialised DB case)
krista@3503
    86
//                             
krista@3503
    87
//  parameters:
krista@3503
    88
//      session (in)            session handle
krista@3503
    89
//
krista@3503
    90
DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session);
krista@3503
    91
krista@4344
    92
// FIXME: Doc
krista@4344
    93
DYNAMIC_API PEP_STATUS key_reset_own_grouped_keys(PEP_SESSION session);
krista@3503
    94
krista@2948
    95
// key_reset() - reset the database status for a key, removing all trust information
krista@2948
    96
//               and default database connections. For own keys, also revoke the key
krista@2948
    97
//               and communicate the revocation and new key to partners we have sent
krista@2948
    98
//               mail to recently from the specific identity (i.e. address/user_id)
krista@2948
    99
//               that contacted them. We also in this case set up information so that
krista@2948
   100
//               if someone we mail uses the wrong key and wasn't yet contacted,
krista@3498
   101
//               we can send them the reset information from the right address. 
krista@3498
   102
//               For non-own keys, also remove key from the keyring.
krista@2948
   103
//
krista@2948
   104
//               Can be called manually or through another protocol.
krista@2948
   105
//
krista@2948
   106
//  parameters:
krista@2948
   107
//      session (in)            session handle
krista@2948
   108
//      fpr (in)                fingerprint of key to reset. If NULL and ident is NULL,
krista@2948
   109
//                              we reset all keys for the own user. If NULL and ident is
krista@2948
   110
//                              an own identity, we reset the default key for that
krista@2948
   111
//                              identity. If that own identity has no default key, we
krista@2948
   112
//                              reset the user default.
krista@3495
   113
//                              if it is NULL and there is a non-own identity, we will reset 
krista@3498
   114
//                              the default key for this identity if present, and user if not.
krista@2948
   115
//      ident (in)              identity for which the key reset should occur.
krista@2948
   116
//                              if NULL and fpr is non-NULL, we'll reset the key for all
krista@2948
   117
//                              associated identities. If both ident and fpr are NULL, see 
krista@2948
   118
//                              the fpr arg documentation.
krista@2948
   119
//
krista@2950
   120
//      Note: ident->fpr is always ignored
krista@2950
   121
//
krista@3495
   122
// Caveat: this is now used in large part for internal calls.
krista@3495
   123
//         external apps should call key_reset_identity and key_reset_userdata
krista@3495
   124
//         and this function should probably be removed from the dynamic api
krista@3495
   125
PEP_STATUS key_reset(
krista@2947
   126
        PEP_SESSION session,
krista@2947
   127
        const char* fpr,
krista@4312
   128
        pEp_identity* ident
krista@2947
   129
    );
krista@2947
   130
krista@4312
   131
/*
krista@4245
   132
PEP_STATUS key_reset_own_and_deliver_revocations(PEP_SESSION session, 
krista@4245
   133
                                                 identity_list** own_identities, 
krista@4245
   134
                                                 stringlist_t** revocations, 
krista@4245
   135
                                                 stringlist_t** keys);
krista@4312
   136
*/
krista@3495
   137
krista@2947
   138
PEP_STATUS has_key_reset_been_sent(
krista@2947
   139
        PEP_SESSION session, 
krista@4312
   140
        const char* from_addr,
krista@2947
   141
        const char* user_id, 
krista@2947
   142
        const char* revoked_fpr,
krista@2947
   143
        bool* contacted);
krista@2947
   144
krista@2947
   145
PEP_STATUS set_reset_contact_notified(
krista@2947
   146
        PEP_SESSION session,
krista@4312
   147
        const char* own_address,
krista@2947
   148
        const char* revoke_fpr,
krista@2947
   149
        const char* contact_id
krista@2947
   150
    );
krista@2947
   151
krista@2947
   152
PEP_STATUS receive_key_reset(PEP_SESSION session,
krista@2947
   153
                             message* reset_msg);
krista@2947
   154
krista@2947
   155
PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
krista@2947
   156
                                               message** dst, 
krista@4312
   157
                                               pEp_identity* own_identity,
krista@2947
   158
                                               pEp_identity* recip,
krista@2947
   159
                                               const char* old_fpr,
krista@2947
   160
                                               const char* new_fpr);
krista@4312
   161
krista@2947
   162
                                               
krista@2947
   163
PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
krista@4312
   164
                                     pEp_identity* from_ident,
krista@2947
   165
                                     const char* old_fpr, 
krista@2947
   166
                                     const char* new_fpr);
vb@4256
   167
 
vb@4261
   168
PEP_STATUS key_reset_commands_to_PER(const keyreset_command_list *command_list, char **cmds, size_t *size);
vb@4261
   169
PEP_STATUS PER_to_key_reset_commands(const char *cmds, size_t size, keyreset_command_list **command_list);
vb@4256
   170
krista@2947
   171
#ifdef __cplusplus
krista@2947
   172
}
krista@2947
   173
#endif