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