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