src/keymanagement.h
author Krista Bennett <krista@pep-project.org>
Fri, 27 Oct 2017 20:02:41 +0200
branchENGINE-293
changeset 2219 99b05a2f117e
parent 2129 fd3108a623c5
child 2308 b7ef1c9005ae
permissions -rw-r--r--
shelving changes
vb@1513
     1
// This file is under GNU General Public License 3.0
vb@1513
     2
// see LICENSE.txt
vb@1513
     3
vb@39
     4
#pragma once
vb@39
     5
vb@217
     6
#include "pEpEngine.h"
vb@217
     7
vb@0
     8
#ifdef __cplusplus
vb@0
     9
extern "C" {
vb@0
    10
#endif
vb@0
    11
vb@0
    12
// update_identity() - update identity information
vb@0
    13
//
vb@0
    14
//  parameters:
vb@0
    15
//      session (in)        session to use
vb@0
    16
//      identity (inout)    identity information of communication partner
krista@1220
    17
//                          (identity->fpr is OUT ONLY)
edouard@1850
    18
//  return value:
edouard@1850
    19
//      PEP_STATUS_OK if identity could be updated,
edouard@1850
    20
//      PEP_GET_KEY_FAILED for own identity that must be completed (myself())
edouard@1850
    21
//      any other value on error
edouard@1850
    22
//
vb@0
    23
//  caveat:
vb@10
    24
//      if this function returns PEP_ct_unknown or PEP_ct_key_expired in
vb@10
    25
//      identity->comm_type, the caller must insert the identity into the
vb@10
    26
//      asynchronous management implementation, so retrieve_next_identity()
vb@10
    27
//      will return this identity later
vb@21
    28
//      at least identity->address must be a non-empty UTF-8 string as input
vb@932
    29
//      update_identity() never writes flags; use set_identity_flags() for
vb@932
    30
//      writing
krista@1220
    31
//      this function NEVER reads the incoming fpr, only writes to it.
vb@0
    32
vb@1387
    33
DYNAMIC_API PEP_STATUS update_identity(
vb@0
    34
        PEP_SESSION session, pEp_identity * identity
vb@0
    35
    );
vb@0
    36
vb@0
    37
krista@2219
    38
// myself() - ensures that an own identity is complete
vb@0
    39
//
vb@0
    40
//  parameters:
vb@0
    41
//      session (in)        session to use
vb@0
    42
//      identity (inout)    identity of local user
krista@2219
    43
//                          at least .address must be set.
krista@2219
    44
//                          if no .user_id is set, AND the DB doesn't contain
krista@2219
    45
//                          a user_id, PEP_OWN_USERID will be used.
krista@2219
    46
//                          if no .username is set and none is in the DB,
krista@2219
    47
//                          username will be set to "Anonymous"
vb@0
    48
//
vb@0
    49
//  return value:
vb@0
    50
//      PEP_STATUS_OK if identity could be completed or was already complete,
vb@0
    51
//      any other value on error
vb@0
    52
//
vb@0
    53
//  caveat:
vb@0
    54
//      this function generates a keypair on demand; because it's synchronous
vb@0
    55
//      it can need a decent amount of time to return
vb@0
    56
//      if you need to do this asynchronous, you need to return an identity
vb@0
    57
//      with retrieve_next_identity() where pEp_identity.me is true
vb@0
    58
vb@0
    59
DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
vb@0
    60
edouard@1406
    61
PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
vb@0
    62
vb@0
    63
// retrieve_next_identity() - callback being called by do_keymanagement()
vb@0
    64
//
vb@0
    65
//  parameters:
vb@0
    66
//      management (in)     data structure to deliver (implementation defined)
vb@0
    67
//
vb@0
    68
//  return value:
vb@0
    69
//      identity to check or NULL to terminate do_keymanagement()
vb@0
    70
//      if given identity must be created with new_identity()
vb@0
    71
//      the identity struct is going to the ownership of this library
vb@0
    72
//      it must not be freed by the callee
vb@0
    73
//
vb@0
    74
//  caveat:
vb@0
    75
//      this callback has to block until an identity or NULL can be returned
vb@0
    76
//      an implementation is not provided by this library; instead it has to be
vb@0
    77
//      implemented by the user of this library
vb@0
    78
vb@0
    79
typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
vb@0
    80
vb@0
    81
vb@292
    82
// examine_identity() - callback for appending to queue
vb@292
    83
//
vb@292
    84
//  parameters:
vb@292
    85
//      ident (in)          identity to examine
vb@292
    86
//      management (in)     data structure to deliver (implementation defined)
vb@292
    87
//
vb@292
    88
//  return value:
vb@292
    89
//      0 if identity was added successfully to queue or nonzero otherwise
vb@292
    90
vb@296
    91
typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
vb@292
    92
vb@292
    93
vb@292
    94
// register_examine_function() - register examine_identity() callback
vb@292
    95
//
vb@292
    96
//  parameters:
vb@292
    97
//      session (in)            session to use
vb@292
    98
//      examine_identity (in)   examine_identity() function to register
vb@292
    99
//      management (in)     data structure to deliver (implementation defined)
vb@292
   100
vb@296
   101
DYNAMIC_API PEP_STATUS register_examine_function(
vb@292
   102
        PEP_SESSION session, 
vb@292
   103
        examine_identity_t examine_identity,
vb@292
   104
        void *management
vb@292
   105
    );
vb@292
   106
vb@292
   107
vb@0
   108
// do_keymanagement() - function to be run on an extra thread
vb@0
   109
//
vb@0
   110
//  parameters:
vb@0
   111
//      retrieve_next_identity  pointer to retrieve_next_identity() callback
vb@0
   112
//                              which returns at least a valid address field in
vb@0
   113
//                              the identity struct
vb@0
   114
//      management              management data to give to keymanagement
vb@0
   115
//                              (implementation defined)
vb@0
   116
//
vb@0
   117
//  return value:
vb@0
   118
//      PEP_STATUS_OK if thread has to terminate successfully or any other
vb@0
   119
//      value on failure
vb@0
   120
//
vb@0
   121
//  caveat:
vb@0
   122
//      to ensure proper working of this library, a thread has to be started
vb@0
   123
//      with this function immediately after initialization
vb@0
   124
//      do_keymanagement() calls retrieve_next_identity(management)
vb@0
   125
vb@0
   126
DYNAMIC_API PEP_STATUS do_keymanagement(
vb@0
   127
        retrieve_next_identity_t retrieve_next_identity,
vb@0
   128
        void *management
vb@0
   129
    );
vb@0
   130
vb@215
   131
krista@2129
   132
// key_mistrusted() - mark key as being compromised
vb@215
   133
//
vb@215
   134
//  parameters:
vb@215
   135
//      session (in)        session to use
krista@2129
   136
//      ident (in)          person and key which was compromised
vb@215
   137
krista@1213
   138
DYNAMIC_API PEP_STATUS key_mistrusted(
vb@357
   139
        PEP_SESSION session,
vb@357
   140
        pEp_identity *ident
vb@357
   141
    );
vb@215
   142
krista@2129
   143
// undo_last_mistrust() - reset identity and trust status for the last
krista@2129
   144
//                        identity in this session marked as mistrusted
krista@2129
   145
//                        to their cached values from the time of mistrust
krista@2129
   146
//  parameters:
krista@2129
   147
//      session (in)        session to use
krista@2129
   148
//
krista@2129
   149
//  return value:
krista@2129
   150
//      PEP_STATUS_OK if identity and trust were successfully restored.
krista@2129
   151
//      Otherwise, error status from attempts to set.
krista@2129
   152
//
krista@2129
   153
//  caveat:
krista@2129
   154
//      only works for this session, and only once. cache is invalidated
krista@2129
   155
//      upon use.
krista@2129
   156
//
krista@2129
   157
//      WILL NOT WORK ON MISTRUSTED OWN KEY
krista@2129
   158
krista@2129
   159
DYNAMIC_API PEP_STATUS undo_last_mistrust(PEP_SESSION session);
krista@2129
   160
vb@215
   161
vb@354
   162
// trust_personal_key() - mark a key as trusted with a person
vb@354
   163
//
vb@354
   164
//  parameters:
vb@354
   165
//      session (in)        session to use
vb@354
   166
//      ident (in)          person and key to trust in
vb@354
   167
//
vb@354
   168
//  caveat:
vb@354
   169
//      the fields user_id, address and fpr must be supplied
vb@354
   170
vb@354
   171
DYNAMIC_API PEP_STATUS trust_personal_key(
vb@354
   172
        PEP_SESSION session,
vb@354
   173
        pEp_identity *ident
vb@354
   174
    );
vb@354
   175
vb@354
   176
krista@1213
   177
// key_reset_trust() - undo trust_personal_key and key_mistrusted() for keys
vb@421
   178
//                     we don't own
Edouard@410
   179
//
Edouard@410
   180
//  parameters:
Edouard@410
   181
//      session (in)        session to use
Edouard@410
   182
//      ident (in)          person and key which was compromized
Edouard@410
   183
Edouard@410
   184
DYNAMIC_API PEP_STATUS key_reset_trust(
Edouard@410
   185
        PEP_SESSION session,
Edouard@410
   186
        pEp_identity *ident
Edouard@410
   187
    );
Edouard@410
   188
Edouard@584
   189
// own_key_is_listed() - returns true id key is listed as own key
Edouard@584
   190
//
Edouard@584
   191
//  parameters:
Edouard@584
   192
//      session (in)        session to use
Edouard@584
   193
//      fpr (in)            fingerprint of key to test
roker@2060
   194
//      listed (out)        flags if key is own
Edouard@584
   195
Edouard@584
   196
DYNAMIC_API PEP_STATUS own_key_is_listed(
Edouard@584
   197
        PEP_SESSION session,
Edouard@584
   198
        const char *fpr,
Edouard@584
   199
        bool *listed
Edouard@584
   200
    );
Edouard@584
   201
Edouard@584
   202
edouard@1412
   203
// _own_identities_retrieve() - retrieve all own identities
edouard@1412
   204
//
edouard@1412
   205
//  parameters:
edouard@1412
   206
//      session (in)            session to use
edouard@1412
   207
//      own_identities (out)    list of own identities
edouard@1412
   208
//      excluded_flags (int)    flags to exclude from results
edouard@1412
   209
//
edouard@1412
   210
//  caveat:
edouard@1412
   211
//      the ownership of the copy of own_identities goes to the caller
edouard@1412
   212
edouard@1412
   213
DYNAMIC_API PEP_STATUS _own_identities_retrieve(
edouard@1412
   214
        PEP_SESSION session,
edouard@1412
   215
        identity_list **own_identities,
edouard@1412
   216
        identity_flags_t excluded_flags
edouard@1412
   217
    );
edouard@1412
   218
vb@955
   219
// own_identities_retrieve() - retrieve all own identities
Edouard@584
   220
//
Edouard@584
   221
//  parameters:
vb@955
   222
//      session (in)            session to use
vb@955
   223
//      own_identities (out)    list of own identities
Edouard@584
   224
//
Edouard@584
   225
//  caveat:
vb@1133
   226
//      the ownership of the copy of own_identities goes to the caller
Edouard@584
   227
vb@955
   228
DYNAMIC_API PEP_STATUS own_identities_retrieve(
Edouard@584
   229
        PEP_SESSION session,
vb@955
   230
        identity_list **own_identities
Edouard@584
   231
    );
Edouard@410
   232
krista@1357
   233
PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
krista@1357
   234
                             bool *has_private);
krista@1357
   235
edouard@1412
   236
// _own_keys_retrieve() - retrieve all flagged keypair fingerprints 
edouard@1412
   237
//
edouard@1412
   238
//  parameters:
edouard@1412
   239
//      session (in)            session to use
edouard@1412
   240
//      keylist (out)           list of fingerprints
edouard@1412
   241
//      excluded_flags (int)    flags to exclude from results
edouard@1412
   242
//
edouard@1412
   243
//  caveat:
edouard@1412
   244
//      the ownership of the list goes to the caller
edouard@1412
   245
DYNAMIC_API PEP_STATUS _own_keys_retrieve(
edouard@1412
   246
        PEP_SESSION session,
edouard@1412
   247
        stringlist_t **keylist,
edouard@1412
   248
        identity_flags_t excluded_flags
edouard@1412
   249
      );
edouard@1412
   250
edouard@1394
   251
// own_keys_retrieve() - retrieve all flagged keypair fingerprints 
edouard@1370
   252
//
edouard@1370
   253
//  parameters:
edouard@1370
   254
//      session (in)            session to use
edouard@1370
   255
//      keylist (out)           list of fingerprints
edouard@1370
   256
//
edouard@1370
   257
//  caveat:
edouard@1370
   258
//      the ownership of the list goes to the caller
edouard@1394
   259
DYNAMIC_API PEP_STATUS own_keys_retrieve(
edouard@1370
   260
        PEP_SESSION session,
edouard@1370
   261
        stringlist_t **keylist
edouard@1370
   262
      );
edouard@1370
   263
edouard@1752
   264
DYNAMIC_API PEP_STATUS set_own_key(
edouard@1752
   265
       PEP_SESSION session,
edouard@1752
   266
       const char *address,
edouard@1752
   267
       const char *fpr
edouard@1752
   268
    );
edouard@1752
   269
vb@0
   270
#ifdef __cplusplus
vb@0
   271
}
vb@0
   272
#endif