src/keymanagement.h
author Volker Birk <vb@pep-project.org>
Fri, 17 May 2019 17:59:06 +0200
branchsync
changeset 3720 9ed76a79d784
parent 3583 3c796707c727
child 4286 471cebdff1c6
child 4322 76806e5aebb2
permissions -rw-r--r--
...
vb@1517
     1
// This file is under GNU General Public License 3.0
vb@1517
     2
// see LICENSE.txt
vb@1517
     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@2461
    17
//                          (identity->fpr is OUT ONLY), and at least
krista@2461
    18
//                          .address must be set. 
krista@2461
    19
//                          If .username is set, it will be used to set or patch
krista@2461
    20
//                          the username record for this identity.                         
edouard@1850
    21
//  return value:
edouard@1850
    22
//      PEP_STATUS_OK if identity could be updated,
krista@2461
    23
//      PEP_ILLEGAL_VALUE if called with illegal inputs, including an identity
krista@2461
    24
//                        with .me set or with an own user_id specified in the
krista@2461
    25
//                        *input* (see caveats) 
krista@2461
    26
//      PEP_KEY_UNSUITABLE if a default key was found for this identity, no
krista@2461
    27
//                         other acceptable keys were found; if this is returned,
krista@2461
    28
//                         the reason for rejecting the first default key found
krista@2461
    29
//                         may be found in the comm_type
edouard@1850
    30
//      any other value on error
edouard@1850
    31
//
vb@0
    32
//  caveat:
krista@2461
    33
//      at least identity->address must be a non-empty UTF-8 string as input
krista@2461
    34
//      update_identity() never writes flags; use set_identity_flags() for
krista@2461
    35
//      writing
krista@2461
    36
//      this function NEVER reads the incoming fpr, only writes to it.
krista@2461
    37
//      this function will fail if called on an identity which, with its input
krista@2461
    38
//      values, *explicitly* indicates it is an own identity (i.e. .me is set
krista@2461
    39
//      to true on input, or a user_id is given AND it is a known own user_id).
krista@2461
    40
//      however, it can RETURN an own identity if this is not indicated a
krista@2461
    41
//      priori, and in fact will do so with prejudice when not faced with a
krista@2461
    42
//      matching default (i.e. it is forced to search by address only).
krista@2461
    43
//      if the identity is known to be an own identity (or the caller wishes
krista@2461
    44
//      to make it one), call myself() on the identity instead.
krista@2461
    45
//
krista@2461
    46
//      FIXME: is this next point accurate?
vb@10
    47
//      if this function returns PEP_ct_unknown or PEP_ct_key_expired in
vb@10
    48
//      identity->comm_type, the caller must insert the identity into the
vb@10
    49
//      asynchronous management implementation, so retrieve_next_identity()
vb@10
    50
//      will return this identity later
krista@2461
    51
//      END FIXME
vb@0
    52
vb@1387
    53
DYNAMIC_API PEP_STATUS update_identity(
vb@0
    54
        PEP_SESSION session, pEp_identity * identity
vb@0
    55
    );
vb@0
    56
vb@2535
    57
// TODO: remove
krista@2461
    58
// initialise_own_identities () - ensures that an own identity is complete
krista@2461
    59
//
krista@2461
    60
//  parameters:
krista@2461
    61
//      session (in)        session to use
krista@2461
    62
//      my_idents (inout)   identities of local user to quick-set
krista@2461
    63
//                          For these, at least .address must be set.
krista@2461
    64
//                          if no .user_id is set, AND the DB doesn't contain
krista@2461
    65
//                          a default user_id, PEP_OWN_USERID will be used and
krista@2461
    66
//                          become the perennial default for the DB.
krista@2461
    67
//
krista@2461
    68
//  return value:
krista@2461
    69
//      PEP_STATUS_OK if identity could be set,
krista@2461
    70
//      any other value on error
krista@2461
    71
//
krista@2461
    72
//  caveat:
krista@2461
    73
//      this function does NOT generate keypairs. It is intended to
krista@2461
    74
//      precede running of the engine on actual messages. It effectively
krista@2461
    75
//      behaves like myself(), but when there would normally be key generation
krista@2461
    76
//      (when there is no valid key, for example),
krista@2461
    77
//      it instead stores an identity without keys.
krista@2461
    78
//
krista@2461
    79
//      N.B. to adapter devs - this function is likely unnecessary, so please
krista@2461
    80
//      do not put work into exposing it yet. Tickets will be filed if need be.
vb@0
    81
vb@2535
    82
// DYNAMIC_API PEP_STATUS initialise_own_identities(PEP_SESSION session,
vb@2535
    83
//                                                  identity_list* my_idents);
krista@2461
    84
krista@2461
    85
// myself() - ensures that an own identity is complete
vb@0
    86
//
vb@0
    87
//  parameters:
vb@0
    88
//      session (in)        session to use
vb@0
    89
//      identity (inout)    identity of local user
krista@2461
    90
//                          both .address and .user_id must be set.
krista@2461
    91
//                          if .fpr is set, an attempt will be made to make
krista@2461
    92
//                          that the default key for this identity after key
krista@2461
    93
//                          validation
krista@2461
    94
//                          if .fpr is not set, key retrieval is performed
krista@2461
    95
//                          If .username is set, it will be used to set or patch
krista@2461
    96
//                          the username record for this identity.                         
vb@0
    97
//
vb@0
    98
//  return value:
vb@0
    99
//      PEP_STATUS_OK if identity could be completed or was already complete,
vb@0
   100
//      any other value on error
vb@0
   101
//  caveat:
krista@2461
   102
//      If an fpr was entered and is not a valid key, the reason for failure
krista@2461
   103
//      is immediately returned in the status and, possibly, identity->comm_type
krista@2461
   104
//      If a default own user_id exists in the database, an alias will 
krista@2461
   105
//      be created for the default for the input user_id. The ENGINE'S default
krista@2461
   106
//      user_id is always returned in the .user_id field
krista@2461
   107
//      myself() NEVER elects keys from the keyring; it will only choose keys
krista@2461
   108
//      which have been set up explicitly via myself(), or which were imported
krista@2461
   109
//      during a first time DB setup from an OpenPGP keyring (compatibility only) 
vb@0
   110
//      this function generates a keypair on demand; because it's synchronous
vb@0
   111
//      it can need a decent amount of time to return
vb@0
   112
//      if you need to do this asynchronous, you need to return an identity
vb@0
   113
//      with retrieve_next_identity() where pEp_identity.me is true
vb@0
   114
vb@0
   115
DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
vb@0
   116
krista@3346
   117
PEP_STATUS _myself(PEP_SESSION session, 
krista@3346
   118
                   pEp_identity * identity, 
krista@3346
   119
                   bool do_keygen, 
krista@3346
   120
                   bool ignore_flags,
krista@3346
   121
                   bool read_only);
vb@0
   122
vb@0
   123
// retrieve_next_identity() - callback being called by do_keymanagement()
vb@0
   124
//
vb@0
   125
//  parameters:
vb@0
   126
//      management (in)     data structure to deliver (implementation defined)
vb@0
   127
//
vb@0
   128
//  return value:
vb@0
   129
//      identity to check or NULL to terminate do_keymanagement()
vb@0
   130
//      if given identity must be created with new_identity()
vb@0
   131
//      the identity struct is going to the ownership of this library
vb@0
   132
//      it must not be freed by the callee
vb@0
   133
//
vb@0
   134
//  caveat:
vb@0
   135
//      this callback has to block until an identity or NULL can be returned
vb@0
   136
//      an implementation is not provided by this library; instead it has to be
vb@0
   137
//      implemented by the user of this library
vb@0
   138
vb@0
   139
typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
vb@0
   140
vb@0
   141
vb@292
   142
// examine_identity() - callback for appending to queue
vb@292
   143
//
vb@292
   144
//  parameters:
vb@292
   145
//      ident (in)          identity to examine
vb@292
   146
//      management (in)     data structure to deliver (implementation defined)
vb@292
   147
//
vb@292
   148
//  return value:
vb@292
   149
//      0 if identity was added successfully to queue or nonzero otherwise
vb@292
   150
vb@296
   151
typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
vb@292
   152
vb@292
   153
vb@292
   154
// register_examine_function() - register examine_identity() callback
vb@292
   155
//
vb@292
   156
//  parameters:
vb@292
   157
//      session (in)            session to use
vb@292
   158
//      examine_identity (in)   examine_identity() function to register
vb@292
   159
//      management (in)     data structure to deliver (implementation defined)
vb@292
   160
vb@296
   161
DYNAMIC_API PEP_STATUS register_examine_function(
vb@292
   162
        PEP_SESSION session, 
vb@292
   163
        examine_identity_t examine_identity,
vb@292
   164
        void *management
vb@292
   165
    );
vb@292
   166
vb@292
   167
vb@0
   168
// do_keymanagement() - function to be run on an extra thread
vb@0
   169
//
vb@0
   170
//  parameters:
vb@2833
   171
//      retrieve_next_identity (in) pointer to retrieve_next_identity()
vb@2833
   172
//                                  callback which returns at least a valid
vb@2833
   173
//                                  address field in the identity struct
vb@0
   174
//
vb@0
   175
//  return value:
vb@0
   176
//      PEP_STATUS_OK if thread has to terminate successfully or any other
vb@0
   177
//      value on failure
vb@0
   178
//
vb@0
   179
//  caveat:
vb@0
   180
//      to ensure proper working of this library, a thread has to be started
vb@0
   181
//      with this function immediately after initialization
vb@2833
   182
//
vb@0
   183
//      do_keymanagement() calls retrieve_next_identity(management)
vb@2833
   184
//
vb@2833
   185
//      messageToSend can only be null if no transport is application based
vb@2833
   186
//      if transport system is not used it must not be NULL
vb@0
   187
vb@0
   188
DYNAMIC_API PEP_STATUS do_keymanagement(
vb@0
   189
        retrieve_next_identity_t retrieve_next_identity,
vb@0
   190
        void *management
vb@0
   191
    );
vb@0
   192
vb@215
   193
krista@2129
   194
// key_mistrusted() - mark key as being compromised
vb@215
   195
//
vb@215
   196
//  parameters:
vb@215
   197
//      session (in)        session to use
krista@2129
   198
//      ident (in)          person and key which was compromised
krista@2461
   199
//  caveat:
krista@2461
   200
//      ident is INPUT ONLY. If you want updated trust on the identity, you'll have
krista@2461
   201
//      to call update_identity or myself respectively after this.
krista@2461
   202
//      N.B. If you are calling this on a key that is the identity or user default,
krista@2461
   203
//      it will be removed as the default key for ANY identity and user for which
krista@2461
   204
//      it is the default. Please keep in mind that the undo in undo_last_mistrust
krista@2461
   205
//      will only undo the current identity's / it's user's default, not any
krista@2461
   206
//      other identities which may be impacted (this will not affect most use
krista@2461
   207
//      cases)
vb@215
   208
krista@1213
   209
DYNAMIC_API PEP_STATUS key_mistrusted(
vb@357
   210
        PEP_SESSION session,
vb@357
   211
        pEp_identity *ident
vb@357
   212
    );
vb@215
   213
krista@2461
   214
// trust_personal_key() - mark a key as trusted for a user
vb@354
   215
//
vb@354
   216
//  parameters:
vb@354
   217
//      session (in)        session to use
krista@3221
   218
//      ident (in)          person and key to trust in - this must not be an
krista@3221
   219
//                          own_identity in which the .me flag is set or
krista@3221
   220
//                          the user_id is an own user_id.
vb@354
   221
//
vb@354
   222
//  caveat:
vb@354
   223
//      the fields user_id, address and fpr must be supplied
krista@3221
   224
//      own identities will result in a return of PEP_ILLEGAL_VALUE.
krista@2494
   225
//      for non-own users, this will 1) set the trust bit on its comm type in the DB,
krista@2461
   226
//      2) set this key as the identity default if the current identity default
krista@2461
   227
//      is not trusted, and 3) set this key as the user default if the current
krista@2461
   228
//      user default is not trusted.
vb@354
   229
vb@354
   230
DYNAMIC_API PEP_STATUS trust_personal_key(
vb@354
   231
        PEP_SESSION session,
vb@354
   232
        pEp_identity *ident
vb@354
   233
    );
vb@354
   234
krista@3222
   235
// trust_own_key() - mark a key as trusted for self, generally
krista@3222
   236
//                   used when we need to trust a public key
krista@3222
   237
//                   associated with outselves for issues like
krista@3222
   238
//                   manual key import
krista@3222
   239
//  parameters:
krista@3222
   240
//      session (in)        session to use
krista@3222
   241
//      ident (in)          own ident containing fpr to trust
krista@3222
   242
//
krista@3222
   243
//  caveat:
krista@3222
   244
//      if this is a public key only, keep in mind that if
krista@3222
   245
//      the private part of the keypair is later added,
krista@3222
   246
//      it will not undergo separate trust evaluation. This
krista@3222
   247
//      is fine - even desired - as long as the semantics
krista@3222
   248
//      of this function are understood as both trusting
krista@3222
   249
//      the key and verifying it as an own key. This will
krista@3222
   250
//      NEVER cause replacement of or setting of a default
krista@3222
   251
//      *alone*. However, if a private key is ever associated
krista@3222
   252
//      with this fpr, please keep in mind that trusting it
krista@3222
   253
//      here makes it an eligible key for selection for    
krista@3222
   254
//      encryption later. So use this function on purpose with
krista@3222
   255
//      an understanding of what you're doing!
krista@3222
   256
//
krista@3222
   257
DYNAMIC_API PEP_STATUS trust_own_key(
krista@3222
   258
        PEP_SESSION session,
krista@3222
   259
        pEp_identity *ident
krista@3222
   260
    );
krista@3222
   261
vb@354
   262
krista@2461
   263
// key_reset_trust() - reset trust bit or explicitly mistrusted status for an identity and
krista@2461
   264
//                     its accompanying key/user_id pair.
Edouard@410
   265
//  parameters:
Edouard@410
   266
//      session (in)        session to use
krista@2461
   267
//      ident (in)          identity for person and key whose trust status is to be reset
krista@2461
   268
//
krista@2461
   269
//  caveat:
krista@2461
   270
//      ident is INPUT ONLY. If you want updated trust on the identity, you'll have
krista@2461
   271
//      to call update_identity or myself respectively after this.
krista@2461
   272
//      N.B. If you are calling this on a key that is the identity or user default,
krista@2461
   273
//      it will be removed as the default key for the identity and user (but is still
krista@2461
   274
//      available for key election, it is just not the cached default anymore)
Edouard@410
   275
Edouard@410
   276
DYNAMIC_API PEP_STATUS key_reset_trust(
Edouard@410
   277
        PEP_SESSION session,
Edouard@410
   278
        pEp_identity *ident
Edouard@410
   279
    );
Edouard@410
   280
Edouard@584
   281
// own_key_is_listed() - returns true id key is listed as own key
Edouard@584
   282
//
Edouard@584
   283
//  parameters:
Edouard@584
   284
//      session (in)        session to use
Edouard@584
   285
//      fpr (in)            fingerprint of key to test
roker@2060
   286
//      listed (out)        flags if key is own
Edouard@584
   287
Edouard@584
   288
DYNAMIC_API PEP_STATUS own_key_is_listed(
Edouard@584
   289
        PEP_SESSION session,
Edouard@584
   290
        const char *fpr,
Edouard@584
   291
        bool *listed
Edouard@584
   292
    );
Edouard@584
   293
Edouard@584
   294
edouard@1412
   295
// _own_identities_retrieve() - retrieve all own identities
edouard@1412
   296
//
edouard@1412
   297
//  parameters:
edouard@1412
   298
//      session (in)            session to use
edouard@1412
   299
//      own_identities (out)    list of own identities
edouard@1412
   300
//      excluded_flags (int)    flags to exclude from results
edouard@1412
   301
//
edouard@1412
   302
//  caveat:
edouard@1412
   303
//      the ownership of the copy of own_identities goes to the caller
edouard@1412
   304
edouard@1412
   305
DYNAMIC_API PEP_STATUS _own_identities_retrieve(
edouard@1412
   306
        PEP_SESSION session,
edouard@1412
   307
        identity_list **own_identities,
edouard@1412
   308
        identity_flags_t excluded_flags
edouard@1412
   309
    );
edouard@1412
   310
vb@955
   311
// own_identities_retrieve() - retrieve all own identities
Edouard@584
   312
//
Edouard@584
   313
//  parameters:
vb@955
   314
//      session (in)            session to use
vb@955
   315
//      own_identities (out)    list of own identities
Edouard@584
   316
//
Edouard@584
   317
//  caveat:
vb@1133
   318
//      the ownership of the copy of own_identities goes to the caller
Edouard@584
   319
vb@955
   320
DYNAMIC_API PEP_STATUS own_identities_retrieve(
Edouard@584
   321
        PEP_SESSION session,
vb@955
   322
        identity_list **own_identities
Edouard@584
   323
    );
Edouard@410
   324
krista@1357
   325
PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
krista@1357
   326
                             bool *has_private);
krista@1357
   327
edouard@1412
   328
// _own_keys_retrieve() - retrieve all flagged keypair fingerprints 
edouard@1412
   329
//
edouard@1412
   330
//  parameters:
edouard@1412
   331
//      session (in)            session to use
edouard@1412
   332
//      keylist (out)           list of fingerprints
krista@3583
   333
//      excluded_flags (in)     flags to exclude from results
krista@3583
   334
//      private_only (in)       if true, return only fprs for
krista@3583
   335
//                              which we have the secret part
edouard@1412
   336
//  caveat:
edouard@1412
   337
//      the ownership of the list goes to the caller
edouard@1412
   338
DYNAMIC_API PEP_STATUS _own_keys_retrieve(
edouard@1412
   339
        PEP_SESSION session,
edouard@1412
   340
        stringlist_t **keylist,
krista@3583
   341
        identity_flags_t excluded_flags,
krista@3583
   342
        bool private_only
edouard@1412
   343
      );
edouard@1412
   344
krista@3583
   345
// own_keys_retrieve() - retrieve all flagged public/private keypair fingerprints 
edouard@1370
   346
//
edouard@1370
   347
//  parameters:
edouard@1370
   348
//      session (in)            session to use
edouard@1370
   349
//      keylist (out)           list of fingerprints
edouard@1370
   350
//
edouard@1370
   351
//  caveat:
edouard@1370
   352
//      the ownership of the list goes to the caller
krista@3583
   353
//      this function does not return keys without a private key part
krista@3583
   354
//
edouard@1394
   355
DYNAMIC_API PEP_STATUS own_keys_retrieve(
edouard@1370
   356
        PEP_SESSION session,
edouard@1370
   357
        stringlist_t **keylist
edouard@1370
   358
      );
edouard@1370
   359
vb@2535
   360
// set_own_key() - mark a key as own key
vb@2535
   361
//
vb@2535
   362
//  parameters:
vb@2535
   363
//      session (in)            session to use
vb@2535
   364
//      me (inout)              own identity this key is used for
vb@2535
   365
//      fpr (in)                fingerprint of the key to mark as own key
vb@2535
   366
//
vb@2535
   367
//  caveat:
vb@2535
   368
//      the key has to be in the key ring already
vb@2535
   369
//      me->address, me->user_id and me->username must be set to valid data
vb@2535
   370
//      myself() is called by set_own_key() without key generation
vb@2535
   371
//      me->flags are ignored
vb@2535
   372
//      me->address must not be an alias
vb@2535
   373
//      me->fpr will be ignored and replaced by fpr
vb@2535
   374
edouard@1752
   375
DYNAMIC_API PEP_STATUS set_own_key(
edouard@1752
   376
       PEP_SESSION session,
vb@2535
   377
       pEp_identity *me,
edouard@1752
   378
       const char *fpr
edouard@1752
   379
    );
edouard@1752
   380
krista@2893
   381
PEP_STATUS get_all_keys_for_user(PEP_SESSION session, 
krista@2893
   382
                                 const char* user_id,
krista@2893
   383
                                 stringlist_t** keys);
krista@2893
   384
krista@2893
   385
krista@3346
   386
//PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
krista@2461
   387
krista@2471
   388
PEP_STATUS add_mistrusted_key(PEP_SESSION session, const char* fpr);
krista@2471
   389
PEP_STATUS delete_mistrusted_key(PEP_SESSION session, const char* fpr);
krista@2471
   390
PEP_STATUS is_mistrusted_key(PEP_SESSION session, const char* fpr, bool* mistrusted);
krista@2615
   391
PEP_STATUS get_user_default_key(PEP_SESSION session, const char* user_id,
krista@2615
   392
                                char** default_key);
krista@2615
   393
krista@2615
   394
krista@2615
   395
krista@2471
   396
krista@2548
   397
// Only call on retrieval of previously stored identity!
krista@2548
   398
// Also, we presume that if the stored_identity was sent in
krista@2548
   399
// without an fpr, there wasn't one in the trust DB for this
krista@2548
   400
// identity.
krista@2548
   401
PEP_STATUS get_valid_pubkey(PEP_SESSION session,
krista@2548
   402
                            pEp_identity* stored_identity,
krista@2548
   403
                            bool* is_identity_default,
krista@2548
   404
                            bool* is_user_default,
krista@2548
   405
                            bool* is_address_default,
krista@2548
   406
                            bool check_blacklist);
krista@2471
   407
vb@0
   408
#ifdef __cplusplus
vb@0
   409
}
vb@0
   410
#endif