src/pEpEngine.h
author us@chu.huenfield.org
Tue, 25 Dec 2018 14:46:45 +0100
branchsync
changeset 3209 c15b4ca2b52a
parent 3189 3f8d3904ba8a
child 3270 d8aea79654c3
permissions -rw-r--r--
Replace use of Sequoia's backend with a custom key store.

- Sequoia's key store doesn't meet pep's needs (in particular, the
ability to search on a key's user id) and trying to shoehorn pep's
needs onto Sequoia's key store abstractions is just introducing
overhead with no appreciable gain in functionality.

- This patch changes the Sequoia backend to use a local sqlite
database to store the public keys.
vb@1517
     1
// This file is under GNU General Public License 3.0
vb@1517
     2
// see LICENSE.txt
vb@1517
     3
vb@23
     4
#pragma once
vb@23
     5
vb@0
     6
#ifdef __cplusplus
vb@0
     7
extern "C" {
vb@0
     8
#endif
vb@0
     9
vb@25
    10
#include <stddef.h>
vb@0
    11
#include <stdint.h>
vb@0
    12
#include <stdbool.h>
vb@0
    13
vb@98
    14
#include "dynamic_api.h"
vb@98
    15
#include "stringlist.h"
krista@2967
    16
#include "stringpair.h"
krista@2967
    17
#include "labeled_int_list.h"    
vb@201
    18
#include "timestamp.h"
vb@0
    19
krista@2152
    20
#define PEP_VERSION "2.0" // protocol version
vb@94
    21
Edouard@658
    22
#define PEP_OWN_USERID "pEp_own_userId"
Edouard@658
    23
    
vb@0
    24
// pEp Engine API
vb@0
    25
vb@0
    26
//  caveat:
vb@0
    27
//      Unicode data has to be normalized to NFC before calling
vb@0
    28
//      UTF-8 strings are UTF-8 encoded C strings (zero terminated)
vb@0
    29
vb@0
    30
vb@46
    31
struct _pEpSession;
vb@46
    32
typedef struct _pEpSession * PEP_SESSION;
vb@0
    33
vb@0
    34
typedef enum {
roker@529
    35
    PEP_STATUS_OK                                   = 0,
vb@0
    36
roker@529
    37
    PEP_INIT_CANNOT_LOAD_GPGME                      = 0x0110,
roker@529
    38
    PEP_INIT_GPGME_INIT_FAILED                      = 0x0111,
roker@529
    39
    PEP_INIT_NO_GPG_HOME                            = 0x0112,
roker@529
    40
    PEP_INIT_NETPGP_INIT_FAILED                     = 0x0113,
krista@2461
    41
    PEP_INIT_CANNOT_DETERMINE_GPG_VERSION           = 0x0114,
krista@2461
    42
    PEP_INIT_UNSUPPORTED_GPG_VERSION                = 0x0115,
krista@2461
    43
    PEP_INIT_CANNOT_CONFIG_GPG_AGENT                = 0x0116,
vb@0
    44
roker@529
    45
    PEP_INIT_SQLITE3_WITHOUT_MUTEX                  = 0x0120,
roker@529
    46
    PEP_INIT_CANNOT_OPEN_DB                         = 0x0121,
roker@529
    47
    PEP_INIT_CANNOT_OPEN_SYSTEM_DB                  = 0x0122,
krista@2800
    48
    PEP_UNKNOWN_DB_ERROR                            = 0x01ff,
roker@529
    49
    
roker@529
    50
    PEP_KEY_NOT_FOUND                               = 0x0201,
roker@529
    51
    PEP_KEY_HAS_AMBIG_NAME                          = 0x0202,
roker@529
    52
    PEP_GET_KEY_FAILED                              = 0x0203,
vb@1103
    53
    PEP_CANNOT_EXPORT_KEY                           = 0x0204,
edouard@1802
    54
    PEP_CANNOT_EDIT_KEY                             = 0x0205,
krista@2461
    55
    PEP_KEY_UNSUITABLE                              = 0x0206,
krista@2940
    56
    PEP_MALFORMED_KEY_RESET_MSG                     = 0x0210,
krista@2940
    57
    PEP_KEY_NOT_RESET                               = 0x0211,
roker@529
    58
    
roker@529
    59
    PEP_CANNOT_FIND_IDENTITY                        = 0x0301,
roker@529
    60
    PEP_CANNOT_SET_PERSON                           = 0x0381,
roker@529
    61
    PEP_CANNOT_SET_PGP_KEYPAIR                      = 0x0382,
roker@529
    62
    PEP_CANNOT_SET_IDENTITY                         = 0x0383,
vb@370
    63
    PEP_CANNOT_SET_TRUST                            = 0x0384,
vb@515
    64
    PEP_KEY_BLACKLISTED                             = 0x0385,
krista@2461
    65
    PEP_CANNOT_FIND_PERSON                          = 0x0386,
krista@2461
    66
    
krista@2461
    67
    PEP_CANNOT_FIND_ALIAS                           = 0x0391,
krista@2461
    68
    PEP_CANNOT_SET_ALIAS                            = 0x0392,
roker@529
    69
    
roker@529
    70
    PEP_UNENCRYPTED                                 = 0x0400,
roker@529
    71
    PEP_VERIFIED                                    = 0x0401,
roker@529
    72
    PEP_DECRYPTED                                   = 0x0402,
roker@529
    73
    PEP_DECRYPTED_AND_VERIFIED                      = 0x0403,
roker@529
    74
    PEP_DECRYPT_WRONG_FORMAT                        = 0x0404,
roker@529
    75
    PEP_DECRYPT_NO_KEY                              = 0x0405,
roker@529
    76
    PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH            = 0x0406,
vb@0
    77
    PEP_VERIFY_NO_KEY                               = 0x0407,
vb@0
    78
    PEP_VERIFIED_AND_TRUSTED                        = 0x0408,
krista@2615
    79
    PEP_CANNOT_REENCRYPT                            = 0x0409,
roker@529
    80
    PEP_CANNOT_DECRYPT_UNKNOWN                      = 0x04ff,
vb@0
    81
roker@529
    82
    PEP_TRUSTWORD_NOT_FOUND                         = 0x0501,
krista@1312
    83
    PEP_TRUSTWORDS_FPR_WRONG_LENGTH                 = 0x0502,
krista@1864
    84
    PEP_TRUSTWORDS_DUPLICATE_FPR                    = 0x0503,
vb@0
    85
vb@0
    86
    PEP_CANNOT_CREATE_KEY                           = 0x0601,
vb@0
    87
    PEP_CANNOT_SEND_KEY                             = 0x0602,
vb@0
    88
vb@458
    89
    PEP_PHRASE_NOT_FOUND                            = 0x0701,
vb@458
    90
vb@690
    91
    PEP_SEND_FUNCTION_NOT_REGISTERED                = 0x0801,
vb@691
    92
    PEP_CONTRAINTS_VIOLATED                         = 0x0802,
vb@691
    93
    PEP_CANNOT_ENCODE                               = 0x0803,
vb@690
    94
edouard@1467
    95
    PEP_SYNC_NO_NOTIFY_CALLBACK                     = 0x0901,
vb@951
    96
    PEP_SYNC_ILLEGAL_MESSAGE                        = 0x0902,
vb@1105
    97
    PEP_SYNC_NO_INJECT_CALLBACK                     = 0x0903,
vb@2868
    98
    PEP_SYNC_NO_CHANNEL                             = 0x0904,
vb@2879
    99
    PEP_SYNC_CANNOT_ENCRYPT                         = 0x0905,
krista@2955
   100
    PEP_SYNC_NO_MESSAGE_SEND_CALLBACK               = 0x0906,
vb@884
   101
vb@1085
   102
    PEP_CANNOT_INCREASE_SEQUENCE                    = 0x0971,
vb@1085
   103
vb@2830
   104
    PEP_STATEMACHINE_ERROR                          = 0x0980,
vb@2830
   105
    PEP_NO_TRUST                                    = 0x0981,
vb@964
   106
    PEP_STATEMACHINE_INVALID_STATE                  = 0x0982,
vb@964
   107
    PEP_STATEMACHINE_INVALID_EVENT                  = 0x0983,
vb@964
   108
    PEP_STATEMACHINE_INVALID_CONDITION              = 0x0984,
vb@964
   109
    PEP_STATEMACHINE_INVALID_ACTION                 = 0x0985,
edouard@1316
   110
    PEP_STATEMACHINE_INHIBITED_EVENT                = 0x0986,
vb@3089
   111
    PEP_STATEMACHINE_CANNOT_SEND                    = 0x0987,
vb@884
   112
roker@529
   113
    PEP_COMMIT_FAILED                               = 0xff01,
vb@1391
   114
    PEP_MESSAGE_CONSUME                             = 0xff02,
vb@1391
   115
    PEP_MESSAGE_IGNORE                              = 0xff03,
vb@0
   116
vb@1091
   117
    PEP_RECORD_NOT_FOUND                            = -6,
vb@44
   118
    PEP_CANNOT_CREATE_TEMP_FILE                     = -5,
vb@0
   119
    PEP_ILLEGAL_VALUE                               = -4,
vb@0
   120
    PEP_BUFFER_TOO_SMALL                            = -3,
roker@529
   121
    PEP_OUT_OF_MEMORY                               = -2,
krista@1914
   122
    PEP_UNKNOWN_ERROR                               = -1,
krista@1914
   123
    
krista@1914
   124
    PEP_VERSION_MISMATCH                            = -7,
vb@0
   125
} PEP_STATUS;
vb@0
   126
vb@0
   127
vb@2833
   128
// messageToSend() - a message needs to be delivered by application
vb@2833
   129
//
vb@2833
   130
//  parameters:
vb@2833
   131
//      msg (in)        message struct with message to send
vb@2833
   132
//
vb@2833
   133
//  return value:
vb@2833
   134
//      PEP_STATUS_OK or any other value on error
vb@2833
   135
//
vb@2833
   136
//  caveat:
vb@2833
   137
//      the ownership of msg goes to the callee
vb@2833
   138
vb@2833
   139
struct _message;
vb@2899
   140
typedef PEP_STATUS (*messageToSend_t)(struct _message *msg);
vb@2833
   141
vb@2833
   142
vb@2879
   143
struct Sync_event;
vb@2879
   144
typedef struct Sync_event *SYNC_EVENT;
vb@2879
   145
vb@2927
   146
// free_Sync_event() - free memory occupied by sync protocol message
vb@2927
   147
//
vb@2927
   148
//  parameters:
vb@2927
   149
//      ev (in)         event to free
vb@2927
   150
vb@2927
   151
void free_Sync_event(SYNC_EVENT ev);
vb@2927
   152
vb@2927
   153
vb@2879
   154
// inject_sync_event - inject sync protocol message
vb@2879
   155
//
vb@2879
   156
//  parameters:
vb@2879
   157
//      ev (in)             event to inject
vb@2879
   158
//      management (in)     application defined; usually a locked queue
vb@2879
   159
//
vb@2879
   160
//  return value:
vb@2879
   161
//      0 if event could be stored successfully or nonzero otherwise
vb@2879
   162
vb@2879
   163
typedef int (*inject_sync_event_t)(SYNC_EVENT ev, void *management);
vb@2879
   164
neal@3189
   165
static inline const char *pep_status_to_string(PEP_STATUS status) {
neal@3189
   166
    switch (status) {
neal@3189
   167
    case PEP_STATUS_OK: return "PEP_STATUS_OK";
neal@3189
   168
neal@3189
   169
    case PEP_INIT_CANNOT_LOAD_GPGME: return "PEP_INIT_CANNOT_LOAD_GPGME";
neal@3189
   170
    case PEP_INIT_GPGME_INIT_FAILED: return "PEP_INIT_GPGME_INIT_FAILED";
neal@3189
   171
    case PEP_INIT_NO_GPG_HOME: return "PEP_INIT_NO_GPG_HOME";
neal@3189
   172
    case PEP_INIT_NETPGP_INIT_FAILED: return "PEP_INIT_NETPGP_INIT_FAILED";
neal@3189
   173
    case PEP_INIT_CANNOT_DETERMINE_GPG_VERSION: return "PEP_INIT_CANNOT_DETERMINE_GPG_VERSION";
neal@3189
   174
    case PEP_INIT_UNSUPPORTED_GPG_VERSION: return "PEP_INIT_UNSUPPORTED_GPG_VERSION";
neal@3189
   175
    case PEP_INIT_CANNOT_CONFIG_GPG_AGENT: return "PEP_INIT_CANNOT_CONFIG_GPG_AGENT";
neal@3189
   176
    case PEP_INIT_SQLITE3_WITHOUT_MUTEX: return "PEP_INIT_SQLITE3_WITHOUT_MUTEX";
neal@3189
   177
    case PEP_INIT_CANNOT_OPEN_DB: return "PEP_INIT_CANNOT_OPEN_DB";
neal@3189
   178
    case PEP_INIT_CANNOT_OPEN_SYSTEM_DB: return "PEP_INIT_CANNOT_OPEN_SYSTEM_DB";
neal@3189
   179
    case PEP_UNKNOWN_DB_ERROR: return "PEP_UNKNOWN_DB_ERROR";
neal@3189
   180
    case PEP_KEY_NOT_FOUND: return "PEP_KEY_NOT_FOUND";
neal@3189
   181
    case PEP_KEY_HAS_AMBIG_NAME: return "PEP_KEY_HAS_AMBIG_NAME";
neal@3189
   182
    case PEP_GET_KEY_FAILED: return "PEP_GET_KEY_FAILED";
neal@3189
   183
    case PEP_CANNOT_EXPORT_KEY: return "PEP_CANNOT_EXPORT_KEY";
neal@3189
   184
    case PEP_CANNOT_EDIT_KEY: return "PEP_CANNOT_EDIT_KEY";
neal@3189
   185
    case PEP_KEY_UNSUITABLE: return "PEP_KEY_UNSUITABLE";
neal@3189
   186
    case PEP_MALFORMED_KEY_RESET_MSG: return "PEP_MALFORMED_KEY_RESET_MSG";
neal@3189
   187
    case PEP_KEY_NOT_RESET: return "PEP_KEY_NOT_RESET";
neal@3189
   188
neal@3189
   189
    case PEP_CANNOT_FIND_IDENTITY: return "PEP_CANNOT_FIND_IDENTITY";
neal@3189
   190
    case PEP_CANNOT_SET_PERSON: return "PEP_CANNOT_SET_PERSON";
neal@3189
   191
    case PEP_CANNOT_SET_PGP_KEYPAIR: return "PEP_CANNOT_SET_PGP_KEYPAIR";
neal@3189
   192
    case PEP_CANNOT_SET_IDENTITY: return "PEP_CANNOT_SET_IDENTITY";
neal@3189
   193
    case PEP_CANNOT_SET_TRUST: return "PEP_CANNOT_SET_TRUST";
neal@3189
   194
    case PEP_KEY_BLACKLISTED: return "PEP_KEY_BLACKLISTED";
neal@3189
   195
    case PEP_CANNOT_FIND_PERSON: return "PEP_CANNOT_FIND_PERSON";
neal@3189
   196
neal@3189
   197
    case PEP_CANNOT_FIND_ALIAS: return "PEP_CANNOT_FIND_ALIAS";
neal@3189
   198
    case PEP_CANNOT_SET_ALIAS: return "PEP_CANNOT_SET_ALIAS";
neal@3189
   199
neal@3189
   200
    case PEP_UNENCRYPTED: return "PEP_UNENCRYPTED";
neal@3189
   201
    case PEP_VERIFIED: return "PEP_VERIFIED";
neal@3189
   202
    case PEP_DECRYPTED: return "PEP_DECRYPTED";
neal@3189
   203
    case PEP_DECRYPTED_AND_VERIFIED: return "PEP_DECRYPTED_AND_VERIFIED";
neal@3189
   204
    case PEP_DECRYPT_WRONG_FORMAT: return "PEP_DECRYPT_WRONG_FORMAT";
neal@3189
   205
    case PEP_DECRYPT_NO_KEY: return "PEP_DECRYPT_NO_KEY";
neal@3189
   206
    case PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH: return "PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH";
neal@3189
   207
    case PEP_VERIFY_NO_KEY: return "PEP_VERIFY_NO_KEY";
neal@3189
   208
    case PEP_VERIFIED_AND_TRUSTED: return "PEP_VERIFIED_AND_TRUSTED";
neal@3189
   209
    case PEP_CANNOT_REENCRYPT: return "PEP_CANNOT_REENCRYPT";
neal@3189
   210
    case PEP_CANNOT_DECRYPT_UNKNOWN: return "PEP_CANNOT_DECRYPT_UNKNOWN";
neal@3189
   211
neal@3189
   212
    case PEP_TRUSTWORD_NOT_FOUND: return "PEP_TRUSTWORD_NOT_FOUND";
neal@3189
   213
    case PEP_TRUSTWORDS_FPR_WRONG_LENGTH: return "PEP_TRUSTWORDS_FPR_WRONG_LENGTH";
neal@3189
   214
    case PEP_TRUSTWORDS_DUPLICATE_FPR: return "PEP_TRUSTWORDS_DUPLICATE_FPR";
neal@3189
   215
neal@3189
   216
    case PEP_CANNOT_CREATE_KEY: return "PEP_CANNOT_CREATE_KEY";
neal@3189
   217
    case PEP_CANNOT_SEND_KEY: return "PEP_CANNOT_SEND_KEY";
neal@3189
   218
neal@3189
   219
    case PEP_PHRASE_NOT_FOUND: return "PEP_PHRASE_NOT_FOUND";
neal@3189
   220
neal@3189
   221
    case PEP_SEND_FUNCTION_NOT_REGISTERED: return "PEP_SEND_FUNCTION_NOT_REGISTERED";
neal@3189
   222
    case PEP_CONTRAINTS_VIOLATED: return "PEP_CONTRAINTS_VIOLATED";
neal@3189
   223
    case PEP_CANNOT_ENCODE: return "PEP_CANNOT_ENCODE";
neal@3189
   224
neal@3189
   225
    case PEP_SYNC_NO_NOTIFY_CALLBACK: return "PEP_SYNC_NO_NOTIFY_CALLBACK";
neal@3189
   226
    case PEP_SYNC_ILLEGAL_MESSAGE: return "PEP_SYNC_ILLEGAL_MESSAGE";
neal@3189
   227
    case PEP_SYNC_NO_INJECT_CALLBACK: return "PEP_SYNC_NO_INJECT_CALLBACK";
neal@3189
   228
    case PEP_SYNC_NO_CHANNEL: return "PEP_SYNC_NO_CHANNEL";
neal@3189
   229
    case PEP_SYNC_CANNOT_ENCRYPT: return "PEP_SYNC_CANNOT_ENCRYPT";
neal@3189
   230
    case PEP_SYNC_NO_MESSAGE_SEND_CALLBACK: return "PEP_SYNC_NO_MESSAGE_SEND_CALLBACK";
neal@3189
   231
neal@3189
   232
    case PEP_CANNOT_INCREASE_SEQUENCE: return "PEP_CANNOT_INCREASE_SEQUENCE";
neal@3189
   233
neal@3189
   234
    case PEP_STATEMACHINE_ERROR: return "PEP_STATEMACHINE_ERROR";
neal@3189
   235
    case PEP_NO_TRUST: return "PEP_NO_TRUST";
neal@3189
   236
    case PEP_STATEMACHINE_INVALID_STATE: return "PEP_STATEMACHINE_INVALID_STATE";
neal@3189
   237
    case PEP_STATEMACHINE_INVALID_EVENT: return "PEP_STATEMACHINE_INVALID_EVENT";
neal@3189
   238
    case PEP_STATEMACHINE_INVALID_CONDITION: return "PEP_STATEMACHINE_INVALID_CONDITION";
neal@3189
   239
    case PEP_STATEMACHINE_INVALID_ACTION: return "PEP_STATEMACHINE_INVALID_ACTION";
neal@3189
   240
    case PEP_STATEMACHINE_INHIBITED_EVENT: return "PEP_STATEMACHINE_INHIBITED_EVENT";
neal@3189
   241
    case PEP_STATEMACHINE_CANNOT_SEND: return "PEP_STATEMACHINE_CANNOT_SEND";
neal@3189
   242
neal@3189
   243
    case PEP_COMMIT_FAILED: return "PEP_COMMIT_FAILED";
neal@3189
   244
    case PEP_MESSAGE_CONSUME: return "PEP_MESSAGE_CONSUME";
neal@3189
   245
    case PEP_MESSAGE_IGNORE: return "PEP_MESSAGE_IGNORE";
neal@3189
   246
neal@3189
   247
    case PEP_RECORD_NOT_FOUND: return "PEP_RECORD_NOT_FOUND";
neal@3189
   248
    case PEP_CANNOT_CREATE_TEMP_FILE: return "PEP_CANNOT_CREATE_TEMP_FILE";
neal@3189
   249
    case PEP_ILLEGAL_VALUE: return "PEP_ILLEGAL_VALUE";
neal@3189
   250
    case PEP_BUFFER_TOO_SMALL: return "PEP_BUFFER_TOO_SMALL";
neal@3189
   251
    case PEP_OUT_OF_MEMORY: return "PEP_OUT_OF_MEMORY";
neal@3189
   252
    case PEP_UNKNOWN_ERROR: return "PEP_UNKNOWN_ERROR";
neal@3189
   253
neal@3189
   254
    case PEP_VERSION_MISMATCH: return "PEP_VERSION_MISMATCH";
neal@3189
   255
neal@3189
   256
    default: return "unknown status code";
neal@3189
   257
    }
neal@3189
   258
}
vb@2879
   259
vb@0
   260
// INIT_STATUS init() - initialize pEpEngine for a thread
vb@0
   261
//
vb@0
   262
//  parameters:
vb@2879
   263
//      session (out)                       init() allocates session memory and
vb@2833
   264
//                                          returns a pointer as a handle
vb@2879
   265
//      messageToSend (in)                  callback for sending message by the
vb@2833
   266
//                                          application
vb@2879
   267
//      inject_sync_event (in)              callback for injecting a sync event
vb@0
   268
//
vb@0
   269
//  return value:
vb@2879
   270
//      PEP_STATUS_OK = 0                   if init() succeeds
vb@2879
   271
//      PEP_INIT_SQLITE3_WITHOUT_MUTEX      if SQLite3 was compiled with
vb@2879
   272
//                                          SQLITE_THREADSAFE 0
vb@2879
   273
//      PEP_INIT_CANNOT_LOAD_GPGME          if libgpgme.dll cannot be found
vb@2879
   274
//      PEP_INIT_GPGME_INIT_FAILED          if GPGME init fails
vb@2879
   275
//      PEP_INIT_CANNOT_OPEN_DB             if user's management db cannot be
vb@2879
   276
//                                          opened
vb@2879
   277
//      PEP_INIT_CANNOT_OPEN_SYSTEM_DB      if system's management db cannot be
vb@2879
   278
//                                          opened
vb@0
   279
//
vb@0
   280
//  caveat:
vb@2833
   281
//      THE CALLER MUST GUARD THIS CALL EXTERNALLY WITH A MUTEX. release()
vb@2833
   282
//      should be similarly guarded.
krista@2126
   283
//
vb@0
   284
//      the pointer is valid only if the return value is PEP_STATUS_OK
vb@0
   285
//      in other case a NULL pointer will be returned; a valid handle must
vb@0
   286
//      be released using release() when it's no longer needed
vb@62
   287
//
vb@62
   288
//      the caller has to guarantee that the first call to this function
vb@62
   289
//      will succeed before further calls can be done
vb@2833
   290
//
vb@2833
   291
//      messageToSend can only be null if no transport is application based
vb@2833
   292
//      if transport system is not used it must not be NULL
vb@0
   293
vb@2833
   294
DYNAMIC_API PEP_STATUS init(
vb@2833
   295
        PEP_SESSION *session,
vb@2879
   296
        messageToSend_t messageToSend,
vb@2879
   297
        inject_sync_event_t inject_sync_event
vb@2833
   298
    );
vb@0
   299
vb@0
   300
vb@0
   301
// void release() - release thread session handle
vb@0
   302
//
vb@0
   303
//  parameters:
roker@529
   304
//        session (in)    session handle to release
vb@62
   305
//
roker@529
   306
//    caveat:
krista@2126
   307
//        THE CALLER MUST GUARD THIS CALL EXTERNALLY WITH A MUTEX. init() should
krista@2126
   308
//        be similarly guarded.
krista@2126
   309
//       
roker@529
   310
//        the last release() can be called only when all other release() calls
roker@529
   311
//        are done
vb@0
   312
vb@0
   313
DYNAMIC_API void release(PEP_SESSION session);
vb@0
   314
vb@0
   315
roker@1722
   316
// const stringlist_t* get_errorstack(PEP_SESSION) - get the error stack for that session, if any
roker@1722
   317
//
roker@1722
   318
//  parameters:
roker@1722
   319
//        session (in)    session handle
roker@1722
   320
//
roker@1722
   321
//    caveat:
roker@1722
   322
//        To get a useful error stack you have to compile with -DDEBUG_ERRORSTACK
roker@1722
   323
//        The error stack belongs to the session. Do no not change it!
roker@1722
   324
DYNAMIC_API const stringlist_t* get_errorstack(PEP_SESSION session);
roker@1722
   325
roker@1778
   326
roker@1777
   327
// void clear_errorstack(PEP_SESSION) - clear the error stack for that session, if any
roker@1777
   328
//
roker@1777
   329
//  parameters:
roker@1777
   330
//        session (in)    session handle
roker@1777
   331
//
roker@1777
   332
DYNAMIC_API void clear_errorstack(PEP_SESSION session);
roker@1777
   333
roker@1722
   334
vb@464
   335
// config_passive_mode() - enable passive mode
vb@464
   336
//
vb@464
   337
//  parameters:
vb@464
   338
//      session (in)    session handle
vb@467
   339
//      enable (in)     flag if enabled or disabled
vb@467
   340
vb@467
   341
DYNAMIC_API void config_passive_mode(PEP_SESSION session, bool enable);
vb@467
   342
vb@464
   343
vb@553
   344
// config_unencrypted_subject() - disable subject encryption
vb@467
   345
//
vb@467
   346
//  parameters:
vb@467
   347
//      session (in)    session handle
vb@467
   348
//      enable (in)     flag if enabled or disabled
vb@467
   349
vb@467
   350
DYNAMIC_API void config_unencrypted_subject(PEP_SESSION session, bool enable);
vb@464
   351
vb@464
   352
Edouard@721
   353
// config_use_only_own_private_keys() - enable passive mode
Edouard@721
   354
//
Edouard@721
   355
//  parameters:
Edouard@721
   356
//      session (in)    session handle
Edouard@721
   357
//      enable (in)     flag if enabled or disabled
Edouard@721
   358
Edouard@721
   359
DYNAMIC_API void config_use_only_own_private_keys(PEP_SESSION session, bool enable);
Edouard@721
   360
Edouard@721
   361
vb@1110
   362
// config_keep_sync_msg() - do not remove sync messages (for debugging purposes)
vb@1109
   363
//
vb@1109
   364
//      session (in)    session handle
vb@1109
   365
//      enable (in)     flag if enabled or disabled
vb@1109
   366
vb@1110
   367
DYNAMIC_API void config_keep_sync_msg(PEP_SESSION session, bool enable);
vb@1109
   368
vb@1109
   369
vb@1819
   370
// config_service_log() - log more for service purposes
vb@1819
   371
//
vb@1819
   372
//      session (in)    session handle
vb@1819
   373
//      enable (in)     flag if enabled or disabled
vb@1819
   374
vb@1819
   375
DYNAMIC_API void config_service_log(PEP_SESSION session, bool enable);
vb@1819
   376
vb@1819
   377
vb@0
   378
// decrypt_and_verify() - decrypt and/or verify a message
vb@0
   379
//
roker@529
   380
//    parameters:
krista@2978
   381
//        session (in)          session handle
krista@2978
   382
//        ctext (in)            cipher text to decrypt and/or verify
krista@2978
   383
//        csize (in)            size of cipher text
krista@2978
   384
//        dsigtext (in)         if extant, *detached* signature text for this
krista@2978
   385
//                              message (or NULL if not)
krista@2978
   386
//        dsize (in)            size of *detached* signature text for this
krista@2978
   387
//                              message (0, if no detached sig exists)
krista@2978
   388
//        ptext (out)           pointer to internal buffer with plain text
krista@2978
   389
//        psize (out)           size of plain text
krista@2978
   390
//        keylist (out)         list of key ids which where used to encrypt
krista@2978
   391
//        filename_ptr (out)    mails produced by certain PGP implementations 
krista@2978
   392
//                              may return a decrypted filename here for attachments. 
krista@2978
   393
//                              Externally, this can generally be NULL, and is an optional
krista@2978
   394
//                              parameter.
vb@0
   395
//
roker@529
   396
//    return value:
roker@529
   397
//        PEP_UNENCRYPTED               message was unencrypted and not signed
roker@529
   398
//        PEP_VERIFIED                  message was unencrypted, signature matches
roker@529
   399
//        PEP_DECRYPTED                 message is decrypted now, no signature
roker@529
   400
//        PEP_DECRYPTED_AND_VERIFIED    message is decrypted now and verified
roker@529
   401
//        PEP_DECRYPT_WRONG_FORMAT      message has wrong format to handle
roker@529
   402
//        PEP_DECRYPT_NO_KEY            key not available to decrypt and/or verify
roker@529
   403
//        PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH    wrong signature
vb@0
   404
//
roker@529
   405
//    caveat:
roker@529
   406
//        the ownerships of ptext as well as keylist are going to the caller
roker@529
   407
//        the caller must use free() (or an Windoze pEp_free()) and
roker@529
   408
//        free_stringlist() to free them
vb@15
   409
//
vb@15
   410
//      if this function failes an error message may be the first element of
vb@15
   411
//      keylist and the other elements may be the keys used for encryption
vb@0
   412
vb@0
   413
DYNAMIC_API PEP_STATUS decrypt_and_verify(
vb@0
   414
        PEP_SESSION session, const char *ctext, size_t csize,
krista@1397
   415
        const char *dsigtext, size_t dsigsize,
krista@2978
   416
        char **ptext, size_t *psize, stringlist_t **keylist,
krista@2978
   417
        char ** filename_ptr
vb@0
   418
    );
vb@0
   419
vb@0
   420
vb@0
   421
// verify_text() - verfy plain text with a digital signature
vb@0
   422
//
vb@0
   423
//  parameters:
vb@0
   424
//      session (in)    session handle
vb@0
   425
//      text (in)       text to verify
vb@0
   426
//      size (in)       size of text
vb@0
   427
//      signature (in)  signature text
vb@0
   428
//      sig_size (in)   size of signature
roker@529
   429
//      keylist (out)   list of key ids which where used to encrypt or NULL on
roker@529
   430
//                        error
vb@0
   431
//
vb@0
   432
//  return value:
roker@529
   433
//        PEP_VERIFIED                message was unencrypted, signature matches
roker@529
   434
//        PEP_DECRYPT_NO_KEY          key not available to decrypt and/or verify
roker@529
   435
//        PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH    wrong signature
vb@0
   436
vb@0
   437
DYNAMIC_API PEP_STATUS verify_text(
vb@0
   438
        PEP_SESSION session, const char *text, size_t size,
vb@0
   439
        const char *signature, size_t sig_size, stringlist_t **keylist
vb@0
   440
    );
vb@0
   441
vb@0
   442
vb@0
   443
// encrypt_and_sign() - encrypt and sign a message
vb@0
   444
//
roker@529
   445
//    parameters:
roker@529
   446
//        session (in)    session handle
roker@529
   447
//        keylist (in)    list of key ids to encrypt with as C strings
roker@529
   448
//        ptext (in)      plain text to decrypt and/or verify
roker@529
   449
//        psize (in)      size of plain text
roker@529
   450
//        ctext (out)     pointer to internal buffer with cipher text
roker@529
   451
//        csize (out)     size of cipher text
vb@0
   452
//
roker@529
   453
//    return value:
roker@529
   454
//        PEP_STATUS_OK = 0            encryption and signing succeeded
hernani@2771
   455
//        PEP_KEY_NOT_FOUND            at least one of the recipient keys
roker@529
   456
//                                     could not be found
hernani@2771
   457
//        PEP_KEY_HAS_AMBIG_NAME       at least one of the recipient keys has
roker@529
   458
//                                     an ambiguous name
roker@529
   459
//        PEP_GET_KEY_FAILED           cannot retrieve key
vb@0
   460
//
roker@529
   461
//    caveat:
roker@529
   462
//      the ownership of ctext is going to the caller
vb@0
   463
//      the caller is responsible to free() it (on Windoze use pEp_free())
vb@20
   464
//      the first key in keylist is being used to sign the message
vb@20
   465
//      this implies there has to be a private key for that keypair
vb@0
   466
vb@0
   467
DYNAMIC_API PEP_STATUS encrypt_and_sign(
vb@0
   468
        PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
vb@0
   469
        size_t psize, char **ctext, size_t *csize
vb@0
   470
    );
vb@0
   471
vb@0
   472
vb@0
   473
// log_event() - log a user defined event defined by UTF-8 encoded strings into
vb@0
   474
// management log
vb@0
   475
//
roker@529
   476
//    parameters:
roker@529
   477
//        session (in)        session handle
roker@529
   478
//        title (in)          C string with event name
roker@529
   479
//        entity (in)         C string with name of entity which is logging
roker@529
   480
//        description (in)    C string with long description for event or NULL if
roker@529
   481
//                            omitted
roker@529
   482
//        comment (in)        C string with user defined comment or NULL if
roker@529
   483
//                            omitted
vb@0
   484
//
roker@529
   485
//    return value:
roker@529
   486
//        PEP_STATUS_OK       log entry created
vb@0
   487
vb@0
   488
DYNAMIC_API PEP_STATUS log_event(
vb@450
   489
        PEP_SESSION session,
vb@451
   490
        const char *title,
vb@451
   491
        const char *entity,
vb@451
   492
        const char *description,
vb@451
   493
        const char *comment
vb@0
   494
    );
vb@0
   495
vb@0
   496
vb@1819
   497
DYNAMIC_API PEP_STATUS log_service(PEP_SESSION session, const char *title,
vb@1819
   498
        const char *entity, const char *description, const char *comment);
vb@1819
   499
vb@1819
   500
#define _STR_(x) #x
vb@1819
   501
#define _D_STR_(x) _STR_(x)
vb@1819
   502
#define S_LINE _D_STR_(__LINE__)
vb@1819
   503
vb@1819
   504
#define SERVICE_LOG(session, title, entity, desc) \
vb@1819
   505
    log_service((session), (title), (entity), (desc), "service " __FILE__ ":" S_LINE)
vb@1819
   506
vb@1819
   507
vb@233
   508
// trustword() - get the corresponding trustword for a 16 bit value
vb@0
   509
//
roker@529
   510
//    parameters:
roker@529
   511
//        session (in)            session handle
roker@529
   512
//        value (in)              value to find a trustword for
roker@529
   513
//        lang (in)               C string with ISO 639-1 language code
roker@529
   514
//        word (out)              pointer to C string with trustword UTF-8 encoded
roker@529
   515
//                                NULL if language is not supported or trustword
roker@529
   516
//                                wordlist is damaged or unavailable
roker@529
   517
//        wsize (out)             length of trustword
vb@0
   518
//
roker@529
   519
//    return value:
roker@529
   520
//        PEP_STATUS_OK            trustword retrieved
roker@529
   521
//        PEP_TRUSTWORD_NOT_FOUND  trustword not found
vb@0
   522
//
roker@529
   523
//    caveat:
roker@529
   524
//        the word pointer goes to the ownership of the caller
vb@0
   525
//      the caller is responsible to free() it (on Windoze use pEp_free())
vb@0
   526
vb@233
   527
DYNAMIC_API PEP_STATUS trustword(
vb@0
   528
            PEP_SESSION session, uint16_t value, const char *lang,
vb@0
   529
            char **word, size_t *wsize
vb@0
   530
        );
vb@0
   531
vb@0
   532
vb@233
   533
// trustwords() - get trustwords for a string of hex values of a fingerprint
vb@0
   534
//
roker@529
   535
//    parameters:
roker@529
   536
//        session (in)        session handle
roker@529
   537
//        fingerprint (in)    C string with hex values to find trustwords for
roker@529
   538
//        lang (in)           C string with ISO 639-1 language code
roker@529
   539
//        words (out)         pointer to C string with trustwords UTF-8 encoded,
roker@529
   540
//                            separated by a blank each
roker@529
   541
//                            NULL if language is not supported or trustword
roker@529
   542
//                            wordlist is damaged or unavailable
roker@529
   543
//        wsize (out)         length of trustwords string
roker@529
   544
//        max_words (in)      only generate a string with max_words;
roker@529
   545
//                            if max_words == 0 there is no such limit
vb@0
   546
//
roker@529
   547
//    return value:
roker@529
   548
//        PEP_STATUS_OK            trustwords retrieved
roker@529
   549
//        PEP_OUT_OF_MEMORY        out of memory
roker@529
   550
//        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
vb@0
   551
//
roker@529
   552
//    caveat:
roker@529
   553
//        the word pointer goes to the ownership of the caller
vb@0
   554
//      the caller is responsible to free() it (on Windoze use pEp_free())
vb@0
   555
//
vb@0
   556
//  DON'T USE THIS FUNCTION FROM HIGH LEVEL LANGUAGES!
vb@0
   557
//
vb@233
   558
//  Better implement a simple one in the adapter yourself using trustword(), and
vb@233
   559
//  return a list of trustwords.
vb@0
   560
//  This function is provided for being used by C and C++ programs only.
vb@0
   561
vb@233
   562
DYNAMIC_API PEP_STATUS trustwords(
vb@0
   563
        PEP_SESSION session, const char *fingerprint, const char *lang,
vb@0
   564
        char **words, size_t *wsize, int max_words
vb@0
   565
    );
vb@0
   566
vb@0
   567
vb@951
   568
// TODO: increase versions in pEp.asn1 if rating changes
vb@951
   569
vb@0
   570
typedef enum _PEP_comm_type {
vb@9
   571
    PEP_ct_unknown = 0,
vb@0
   572
vb@9
   573
    // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
vb@0
   574
vb@9
   575
    PEP_ct_no_encryption = 0x01,                // generic
vb@9
   576
    PEP_ct_no_encrypted_channel = 0x02,
vb@9
   577
    PEP_ct_key_not_found = 0x03,
vb@9
   578
    PEP_ct_key_expired = 0x04,
vb@9
   579
    PEP_ct_key_revoked = 0x05,
vb@9
   580
    PEP_ct_key_b0rken = 0x06,
krista@3071
   581
    PEP_ct_key_expired_but_confirmed = 0x07, // NOT with confirmed bit. Just retaining info here in case of renewal.
vb@9
   582
    PEP_ct_my_key_not_included = 0x09,
vb@9
   583
vb@9
   584
    PEP_ct_security_by_obscurity = 0x0a,
vb@9
   585
    PEP_ct_b0rken_crypto = 0x0b,
Edouard@442
   586
    PEP_ct_key_too_short = 0x0c,
vb@9
   587
krista@2593
   588
    PEP_ct_compromised = 0x0e,                  // known compromised connection
krista@2593
   589
    PEP_ct_compromized = 0x0e,                  // deprecated misspelling
Edouard@442
   590
    PEP_ct_mistrusted = 0x0f,                   // known mistrusted key
vb@0
   591
vb@9
   592
    // range 0x10 to 0x3f: unconfirmed encryption
vb@0
   593
vb@0
   594
    PEP_ct_unconfirmed_encryption = 0x10,       // generic
roker@529
   595
    PEP_ct_OpenPGP_weak_unconfirmed = 0x11,     // RSA 1024 is weak
vb@190
   596
vb@190
   597
    PEP_ct_to_be_checked = 0x20,                // generic
vb@190
   598
    PEP_ct_SMIME_unconfirmed = 0x21,
vb@190
   599
    PEP_ct_CMS_unconfirmed = 0x22,
vb@190
   600
vb@190
   601
    PEP_ct_strong_but_unconfirmed = 0x30,       // generic
vb@122
   602
    PEP_ct_OpenPGP_unconfirmed = 0x38,          // key at least 2048 bit RSA or EC
vb@122
   603
    PEP_ct_OTR_unconfirmed = 0x3a,
vb@0
   604
vb@9
   605
    // range 0x40 to 0x7f: unconfirmed encryption and anonymization
vb@0
   606
vb@0
   607
    PEP_ct_unconfirmed_enc_anon = 0x40,         // generic
lix@710
   608
    PEP_ct_pEp_unconfirmed = 0x7f,
vb@0
   609
vb@9
   610
    PEP_ct_confirmed = 0x80,                    // this bit decides if trust is confirmed
vb@9
   611
vb@9
   612
    // range 0x81 to 0x8f: reserved
vb@9
   613
    // range 0x90 to 0xbf: confirmed encryption
vb@0
   614
vb@0
   615
    PEP_ct_confirmed_encryption = 0x90,         // generic
edouard@1635
   616
    PEP_ct_OpenPGP_weak = 0x91,                 // RSA 1024 is weak (unused)
vb@190
   617
hernani@2772
   618
    PEP_ct_to_be_checked_confirmed = 0xa0,      // generic
vb@190
   619
    PEP_ct_SMIME = 0xa1,
vb@190
   620
    PEP_ct_CMS = 0xa2,
vb@190
   621
vb@190
   622
    PEP_ct_strong_encryption = 0xb0,            // generic
roker@529
   623
    PEP_ct_OpenPGP = 0xb8,                      // key at least 2048 bit RSA or EC
roker@529
   624
    PEP_ct_OTR = 0xba,
vb@0
   625
vb@0
   626
    // range 0xc0 to 0xff: confirmed encryption and anonymization
vb@0
   627
vb@0
   628
    PEP_ct_confirmed_enc_anon = 0xc0,           // generic
roker@529
   629
    PEP_ct_pEp = 0xff
vb@0
   630
} PEP_comm_type;
vb@0
   631
neal@3189
   632
static inline const char *pep_comm_type_to_string(PEP_comm_type ct) {
neal@3189
   633
    switch (ct) {
neal@3189
   634
    case PEP_ct_unknown: return "unknown";
neal@3189
   635
    case PEP_ct_no_encryption: return "no_encryption";
neal@3189
   636
    case PEP_ct_no_encrypted_channel: return "no_encrypted_channel";
neal@3189
   637
    case PEP_ct_key_not_found: return "key_not_found";
neal@3189
   638
    case PEP_ct_key_expired: return "key_expired";
neal@3189
   639
    case PEP_ct_key_revoked: return "key_revoked";
neal@3189
   640
    case PEP_ct_key_b0rken: return "key_b0rken";
neal@3189
   641
    case PEP_ct_my_key_not_included: return "my_key_not_included";
neal@3189
   642
    case PEP_ct_security_by_obscurity: return "security_by_obscurity";
neal@3189
   643
    case PEP_ct_b0rken_crypto: return "b0rken_crypto";
neal@3189
   644
    case PEP_ct_key_too_short: return "key_too_short";
neal@3189
   645
    case PEP_ct_compromised: return "compromised";
neal@3189
   646
    case PEP_ct_mistrusted: return "mistrusted";
neal@3189
   647
    case PEP_ct_unconfirmed_encryption: return "unconfirmed_encryption";
neal@3189
   648
    case PEP_ct_OpenPGP_weak_unconfirmed: return "OpenPGP_weak_unconfirmed";
neal@3189
   649
    case PEP_ct_to_be_checked: return "to_be_checked";
neal@3189
   650
    case PEP_ct_SMIME_unconfirmed: return "SMIME_unconfirmed";
neal@3189
   651
    case PEP_ct_CMS_unconfirmed: return "CMS_unconfirmed";
neal@3189
   652
    case PEP_ct_strong_but_unconfirmed: return "strong_but_unconfirmed";
neal@3189
   653
    case PEP_ct_OpenPGP_unconfirmed: return "OpenPGP_unconfirmed";
neal@3189
   654
    case PEP_ct_OTR_unconfirmed: return "OTR_unconfirmed";
neal@3189
   655
    case PEP_ct_unconfirmed_enc_anon: return "unconfirmed_enc_anon";
neal@3189
   656
    case PEP_ct_pEp_unconfirmed: return "pEp_unconfirmed";
neal@3189
   657
    case PEP_ct_confirmed: return "confirmed";
neal@3189
   658
    case PEP_ct_confirmed_encryption: return "confirmed_encryption";
neal@3189
   659
    case PEP_ct_OpenPGP_weak: return "OpenPGP_weak";
neal@3189
   660
    case PEP_ct_to_be_checked_confirmed: return "to_be_checked_confirmed";
neal@3189
   661
    case PEP_ct_SMIME: return "SMIME";
neal@3189
   662
    case PEP_ct_CMS: return "CMS";
neal@3189
   663
    case PEP_ct_strong_encryption: return "strong_encryption";
neal@3189
   664
    case PEP_ct_OpenPGP: return "OpenPGP";
neal@3189
   665
    case PEP_ct_OTR: return "OTR";
neal@3189
   666
    case PEP_ct_confirmed_enc_anon: return "confirmed_enc_anon";
neal@3189
   667
    case PEP_ct_pEp: return "pEp";
neal@3189
   668
    default: return "invalid comm type";
neal@3189
   669
    }
neal@3189
   670
}
neal@3189
   671
neal@3189
   672
vb@928
   673
typedef enum _identity_flags {
vb@951
   674
    // the first octet flags are app defined settings
edouard@1394
   675
    PEP_idf_not_for_sync = 0x0001,   // don't use this identity for sync
edouard@1394
   676
    PEP_idf_list = 0x0002,           // identity of list of persons
vb@951
   677
    // the second octet flags are calculated
edouard@1394
   678
    PEP_idf_devicegroup = 0x0100     // identity of a device group member
vb@928
   679
} identity_flags;
vb@928
   680
vb@944
   681
typedef unsigned int identity_flags_t;
vb@944
   682
edouard@1394
   683
// typedef enum _keypair_flags {
edouard@1394
   684
// } keypair_flags;
edouard@1364
   685
edouard@1364
   686
typedef unsigned int keypair_flags_t;
edouard@1364
   687
vb@0
   688
typedef struct _pEp_identity {
roker@529
   689
    char *address;              // C string with address UTF-8 encoded
roker@529
   690
    char *fpr;                  // C string with fingerprint UTF-8 encoded
roker@529
   691
    char *user_id;              // C string with user ID UTF-8 encoded
krista@2461
   692
                                // user_id MIGHT be set to "pEp_own_userId"
edouard@1946
   693
                                // (use PEP_OWN_USERID preprocessor define)
edouard@1946
   694
                                // if this is own user's identity.
krista@2461
   695
                                // But it is not REQUIRED to be.
roker@529
   696
    char *username;             // C string with user name UTF-8 encoded
roker@529
   697
    PEP_comm_type comm_type;    // type of communication with this ID
roker@529
   698
    char lang[3];               // language of conversation
vb@0
   699
                                // ISO 639-1 ALPHA-2, last byte is 0
krista@2461
   700
    bool me;                    // if this is the local user herself/himself
vb@944
   701
    identity_flags_t flags;     // identity_flag1 | identity_flag2 | ...
vb@0
   702
} pEp_identity;
vb@0
   703
Edouard@730
   704
typedef struct _identity_list {
Edouard@730
   705
    pEp_identity *ident;
Edouard@730
   706
    struct _identity_list *next;
Edouard@730
   707
} identity_list;
Edouard@730
   708
vb@0
   709
vb@0
   710
// new_identity() - allocate memory and set the string and size fields
vb@0
   711
//
vb@0
   712
//  parameters:
vb@0
   713
//      address (in)        UTF-8 string or NULL 
vb@0
   714
//      fpr (in)            UTF-8 string or NULL 
vb@0
   715
//      user_id (in)        UTF-8 string or NULL 
vb@0
   716
//      username (in)       UTF-8 string or NULL 
vb@0
   717
//
vb@0
   718
//  return value:
vb@932
   719
//      pEp_identity struct or NULL if out of memory
vb@0
   720
//
vb@0
   721
//  caveat:
vb@0
   722
//      the strings are copied; the original strings are still being owned by
vb@0
   723
//      the caller
vb@0
   724
vb@0
   725
DYNAMIC_API pEp_identity *new_identity(
vb@0
   726
        const char *address, const char *fpr, const char *user_id,
vb@0
   727
        const char *username
vb@0
   728
    );
vb@0
   729
vb@0
   730
vb@932
   731
// identity_dup() - allocate memory and duplicate
vb@37
   732
//
vb@37
   733
//  parameters:
vb@37
   734
//      src (in)            identity to duplicate
vb@37
   735
//
vb@37
   736
//  return value:
vb@932
   737
//      pEp_identity struct or NULL if out of memory
vb@37
   738
//
vb@37
   739
//  caveat:
vb@37
   740
//      the strings are copied; the original strings are still being owned by
vb@37
   741
//      the caller
vb@37
   742
vb@37
   743
DYNAMIC_API pEp_identity *identity_dup(const pEp_identity *src);
vb@37
   744
vb@37
   745
vb@0
   746
// free_identity() - free all memory being occupied by a pEp_identity struct
vb@0
   747
//
vb@0
   748
//  parameters:
vb@0
   749
//      identity (in)       struct to release
vb@0
   750
//
vb@0
   751
//  caveat:
vb@0
   752
//      not only the struct but also all string memory referenced by the
vb@0
   753
//      struct is being freed; all pointers inside are invalid afterwards
vb@0
   754
vb@0
   755
DYNAMIC_API void free_identity(pEp_identity *identity);
vb@0
   756
vb@0
   757
vb@0
   758
// get_identity() - get identity information
vb@0
   759
//
roker@529
   760
//    parameters:
roker@529
   761
//        session (in)        session handle
roker@529
   762
//        address (in)        C string with communication address, UTF-8 encoded
Edouard@562
   763
//        user_id (in)        unique C string to identify person that identity
Edouard@562
   764
//                            is refering to
roker@529
   765
//        identity (out)      pointer to pEp_identity structure with results or
roker@529
   766
//                            NULL if failure
vb@0
   767
//
roker@529
   768
//    caveat:
vb@951
   769
//        address and user_id are being copied; the original strings remains in
vb@951
   770
//        the ownership of the caller
roker@529
   771
//        the resulting pEp_identity structure goes to the ownership of the
roker@529
   772
//        caller and has to be freed with free_identity() when not in use any
roker@529
   773
//        more
vb@0
   774
vb@0
   775
DYNAMIC_API PEP_STATUS get_identity(
Edouard@559
   776
        PEP_SESSION session,
Edouard@559
   777
        const char *address,
Edouard@559
   778
        const char *user_id,
vb@0
   779
        pEp_identity **identity
vb@0
   780
    );
vb@0
   781
krista@1799
   782
PEP_STATUS replace_identities_fpr(PEP_SESSION session, 
krista@1799
   783
                                 const char* old_fpr, 
krista@1799
   784
                                 const char* new_fpr); 
krista@1797
   785
krista@1797
   786
vb@0
   787
// set_identity() - set identity information
vb@0
   788
//
roker@529
   789
//    parameters:
roker@529
   790
//        session (in)        session handle
roker@529
   791
//        identity (in)       pointer to pEp_identity structure
vb@0
   792
//
roker@529
   793
//    return value:
roker@529
   794
//        PEP_STATUS_OK = 0             encryption and signing succeeded
roker@529
   795
//        PEP_CANNOT_SET_PERSON         writing to table person failed
roker@529
   796
//        PEP_CANNOT_SET_PGP_KEYPAIR    writing to table pgp_keypair failed
roker@529
   797
//        PEP_CANNOT_SET_IDENTITY       writing to table identity failed
roker@529
   798
//        PEP_COMMIT_FAILED             SQL commit failed
vb@0
   799
//
roker@529
   800
//    caveat:
vb@932
   801
//        address, fpr, user_id and username must be given
vb@0
   802
vb@0
   803
DYNAMIC_API PEP_STATUS set_identity(
vb@0
   804
        PEP_SESSION session, const pEp_identity *identity
vb@0
   805
    );
vb@0
   806
krista@2461
   807
// get_default own_userid() - get the user_id of the own user
krista@2461
   808
//
krista@2461
   809
//    parameters:
krista@2461
   810
//        session (in)        session handle
krista@2461
   811
//        userid  (out)       own user id (if it exists)
krista@2461
   812
//
krista@2461
   813
//    return value:
krista@2461
   814
//        PEP_STATUS_OK = 0             userid was found
krista@2461
   815
//        PEP_CANNOT_FIND_IDENTITY      no own_user found in the DB
krista@2461
   816
//        PEP_UNKNOWN_ERROR             results were returned, but no ID
krista@2461
   817
//                                      found (no reason this should ever occur)
krista@2461
   818
//    caveat:
krista@2461
   819
//        userid will be NULL if not found; otherwise, returned string
krista@2461
   820
//        belongs to the caller.
krista@2461
   821
krista@2461
   822
DYNAMIC_API PEP_STATUS get_default_own_userid(
krista@2461
   823
        PEP_SESSION session, 
krista@2461
   824
        char** userid
krista@2461
   825
    );
krista@2461
   826
krista@2461
   827
// get_userid_alias_default() - get the default user_id which corresponds
krista@2461
   828
//                              to an alias
krista@2461
   829
//    parameters:
krista@2461
   830
//        session (in)        session handle
krista@2461
   831
//        alias_id (in)       the user_id which may be an alias for a default id
krista@2461
   832
//        default_id (out)    the default id for this alias, if the alias
krista@2461
   833
//                            is in the DB as an alias, else NULL
krista@2461
   834
//    return value:
krista@2461
   835
//        PEP_STATUS_OK = 0             userid was found
krista@2461
   836
//        PEP_CANNOT_FIND_ALIAS         this userid is not listed as an 
krista@2461
   837
//                                      alias in the DB
krista@2461
   838
//        PEP_UNKNOWN_ERROR             results were returned, but no ID
krista@2461
   839
//                                      found (no reason this should ever occur)
krista@2461
   840
//    caveat:
krista@2461
   841
//        default_id will be NULL if not found; otherwise, returned string
krista@2461
   842
//        belongs to the caller.
krista@2461
   843
//        also, current implementation does NOT check to see if this userid
krista@2461
   844
//        IS a default.
krista@2461
   845
krista@2461
   846
DYNAMIC_API PEP_STATUS get_userid_alias_default(
krista@2461
   847
        PEP_SESSION session, 
krista@2461
   848
        const char* alias_id,
krista@2461
   849
        char** default_id);
krista@2461
   850
krista@2461
   851
// set_userid_alias() - set an alias to correspond to a default id
krista@2461
   852
//    parameters:
krista@2461
   853
//        session (in)        session handle
krista@2461
   854
//        default_id (in)     the default id for this alias. This must
krista@2461
   855
//                            correspond to the default user_id for an
krista@2461
   856
//                            entry in the person (user) table.
krista@2461
   857
//        alias_id (in)       the alias to be set for this default id
krista@2461
   858
//    return value:
krista@2461
   859
//        PEP_STATUS_OK = 0             userid was found
krista@2461
   860
//        PEP_CANNOT_SET_ALIAS          there was an error setting this
krista@2461
   861
krista@2461
   862
DYNAMIC_API PEP_STATUS set_userid_alias (
krista@2461
   863
        PEP_SESSION session, 
krista@2461
   864
        const char* default_id,
krista@2461
   865
        const char* alias_id);
krista@2461
   866
krista@2461
   867
edouard@1234
   868
// set_device_group() - update own person's device group
edouard@1234
   869
//
edouard@1234
   870
//    parameters:
edouard@1234
   871
//        session (in)        session handle
edouard@1234
   872
//        group_name (in)     new group name
edouard@1234
   873
//
edouard@1234
   874
//    return value:
edouard@1235
   875
//        PEP_STATUS_OK = 0             device group was updated
edouard@1234
   876
//        PEP_CANNOT_SET_PERSON         update failed
edouard@1234
   877
edouard@1234
   878
DYNAMIC_API PEP_STATUS set_device_group(
edouard@1234
   879
        PEP_SESSION session,
edouard@1234
   880
        const char *group_name
edouard@1234
   881
    );
vb@0
   882
edouard@1235
   883
// get_device_group() - get own person's device group
edouard@1235
   884
//
edouard@1235
   885
//    parameters:
edouard@1235
   886
//        session (in)        session handle
edouard@1235
   887
//        group_name (in)     new group name
edouard@1235
   888
//
edouard@1235
   889
//    return value:
edouard@1235
   890
//        PEP_STATUS_OK = 0             couldn't get device group
edouard@1235
   891
//        PEP_RECORD_NOT_FOUND          update failed
edouard@1235
   892
//
edouard@1235
   893
//    caveat:
edouard@1235
   894
//        the ownerships of group_name is going to the caller
edouard@1235
   895
edouard@1235
   896
DYNAMIC_API PEP_STATUS get_device_group(
edouard@1235
   897
        PEP_SESSION session, 
edouard@1235
   898
        char **group_name
edouard@1235
   899
    );
edouard@1235
   900
vb@932
   901
// set_identity_flags() - update identity flags on existing identity
vb@932
   902
//
vb@932
   903
//    parameters:
vb@932
   904
//        session (in)        session handle
vb@934
   905
//        identity (in,out)   pointer to pEp_identity structure
vb@934
   906
//        flags (in)          new value for flags
vb@932
   907
//
vb@932
   908
//    return value:
vb@932
   909
//        PEP_STATUS_OK = 0             encryption and signing succeeded
vb@932
   910
//        PEP_CANNOT_SET_IDENTITY       update of identity failed
vb@932
   911
//
vb@932
   912
//    caveat:
vb@934
   913
//        address and user_id must be given in identity
vb@932
   914
vb@932
   915
DYNAMIC_API PEP_STATUS set_identity_flags(
vb@934
   916
        PEP_SESSION session,
vb@934
   917
        pEp_identity *identity,
vb@1425
   918
        identity_flags_t flags
vb@932
   919
    );
vb@932
   920
edouard@1406
   921
// unset_identity_flags() - update identity flags on existing identity
edouard@1406
   922
//
edouard@1406
   923
//    parameters:
edouard@1406
   924
//        session (in)        session handle
edouard@1406
   925
//        identity (in,out)   pointer to pEp_identity structure
edouard@1406
   926
//        flags (in)          new value for flags
edouard@1406
   927
//
edouard@1406
   928
//    return value:
edouard@1406
   929
//        PEP_STATUS_OK = 0             encryption and signing succeeded
edouard@1406
   930
//        PEP_CANNOT_SET_IDENTITY       update of identity failed
edouard@1406
   931
//
edouard@1406
   932
//    caveat:
edouard@1406
   933
//        address and user_id must be given in identity
edouard@1406
   934
edouard@1406
   935
DYNAMIC_API PEP_STATUS unset_identity_flags(
edouard@1406
   936
        PEP_SESSION session,
edouard@1406
   937
        pEp_identity *identity,
vb@1425
   938
        identity_flags_t flags
edouard@1406
   939
    );
vb@932
   940
krista@2593
   941
// mark_as_compromised() - mark key in trust db as compromised
vb@357
   942
//
roker@529
   943
//    parameters:
roker@529
   944
//        session (in)        session handle
roker@529
   945
//        fpr (in)            fingerprint of key to mark
vb@357
   946
krista@2593
   947
DYNAMIC_API PEP_STATUS mark_as_compromised(
krista@2593
   948
        PEP_SESSION session,
krista@2593
   949
        const char *fpr
krista@2593
   950
    );
krista@2593
   951
krista@2593
   952
krista@2593
   953
// mark_as_compromized() - deprecated to fix misspelling. Please move to
krista@2593
   954
//                         mark_as_compromised();
krista@2593
   955
vb@357
   956
DYNAMIC_API PEP_STATUS mark_as_compromized(
vb@357
   957
        PEP_SESSION session,
vb@357
   958
        const char *fpr
vb@357
   959
    );
vb@357
   960
vb@357
   961
vb@0
   962
// generate_keypair() - generate a new key pair and add it to the key ring
vb@0
   963
//
vb@0
   964
//  parameters:
vb@0
   965
//      session (in)            session handle
roker@529
   966
//        identity (inout)      pointer to pEp_identity structure
vb@0
   967
//
roker@529
   968
//    return value:
roker@529
   969
//        PEP_STATUS_OK = 0       encryption and signing succeeded
roker@529
   970
//        PEP_ILLEGAL_VALUE       illegal values for identity fields given
roker@529
   971
//        PEP_CANNOT_CREATE_KEY   key engine is on strike
vb@0
   972
//
vb@0
   973
//  caveat:
vb@0
   974
//      address and username fields must be set to UTF-8 strings
vb@0
   975
//      the fpr field must be set to NULL
vb@0
   976
//
vb@0
   977
//      this function allocates a string and sets set fpr field of identity
vb@0
   978
//      the caller is responsible to call free() for that string or use
vb@0
   979
//      free_identity() on the struct
vb@0
   980
vb@0
   981
DYNAMIC_API PEP_STATUS generate_keypair(
vb@0
   982
        PEP_SESSION session, pEp_identity *identity
vb@0
   983
    );
vb@0
   984
vb@0
   985
vb@0
   986
// delete_keypair() - delete a public key or a key pair from the key ring
vb@0
   987
//
vb@0
   988
//  parameters:
vb@0
   989
//      session (in)            session handle
vb@0
   990
//      fpr (in)                C string with key id or fingerprint of the
vb@0
   991
//                              public key
vb@0
   992
//
vb@0
   993
//  return value:
vb@0
   994
//      PEP_STATUS_OK = 0       key was successfully deleted
vb@0
   995
//      PEP_KEY_NOT_FOUND       key not found
vb@0
   996
//      PEP_ILLEGAL_VALUE       not a valid key id or fingerprint
vb@0
   997
//      PEP_KEY_HAS_AMBIG_NAME  fpr does not uniquely identify a key
vb@0
   998
//      PEP_OUT_OF_MEMORY       out of memory
vb@0
   999
vb@0
  1000
DYNAMIC_API PEP_STATUS delete_keypair(PEP_SESSION session, const char *fpr);
vb@0
  1001
vb@0
  1002
vb@0
  1003
// import_key() - import key from data
vb@0
  1004
//
vb@0
  1005
//  parameters:
vb@0
  1006
//      session (in)            session handle
vb@0
  1007
//      key_data (in)           key data, i.e. ASCII armored OpenPGP key
vb@0
  1008
//      size (in)               amount of data to handle
Edouard@772
  1009
//      private_keys (out)      list of private keys that have been imported
vb@0
  1010
//
vb@0
  1011
//  return value:
vb@0
  1012
//      PEP_STATUS_OK = 0       key was successfully imported
vb@0
  1013
//      PEP_OUT_OF_MEMORY       out of memory
vb@0
  1014
//      PEP_ILLEGAL_VALUE       there is no key data to import
Edouard@772
  1015
//
Edouard@772
  1016
//  caveat:
Edouard@772
  1017
//      private_keys goes to the ownership of the caller
Edouard@772
  1018
//      private_keys can be left NULL, it is then ignored
vb@0
  1019
Edouard@728
  1020
DYNAMIC_API PEP_STATUS import_key(
Edouard@728
  1021
        PEP_SESSION session,
Edouard@728
  1022
        const char *key_data,
Edouard@728
  1023
        size_t size,
Edouard@728
  1024
        identity_list **private_keys
Edouard@728
  1025
    );
vb@0
  1026
vb@0
  1027
vb@0
  1028
// export_key() - export ascii armored key
vb@0
  1029
//
vb@0
  1030
//  parameters:
vb@0
  1031
//      session (in)            session handle
vb@0
  1032
//      fpr (in)                key id or fingerprint of key
vb@0
  1033
//      key_data (out)          ASCII armored OpenPGP key
roker@529
  1034
//      size (out)              amount of data to handle
vb@0
  1035
//
vb@0
  1036
//  return value:
vb@0
  1037
//      PEP_STATUS_OK = 0       key was successfully exported
vb@0
  1038
//      PEP_OUT_OF_MEMORY       out of memory
vb@0
  1039
//      PEP_KEY_NOT_FOUND       key not found
vb@0
  1040
//
vb@0
  1041
//  caveat:
vb@0
  1042
//      the key_data goes to the ownership of the caller
vb@0
  1043
//      the caller is responsible to free() it (on Windoze use pEp_free())
vb@0
  1044
vb@0
  1045
DYNAMIC_API PEP_STATUS export_key(
vb@0
  1046
        PEP_SESSION session, const char *fpr, char **key_data, size_t *size
vb@0
  1047
    );
vb@0
  1048
vb@0
  1049
vb@1103
  1050
// export_secret_key() - export secret key ascii armored
vb@1103
  1051
//
vb@1103
  1052
//  parameters:
vb@1103
  1053
//      session (in)            session handle
vb@1103
  1054
//      fpr (in)                fingerprint of key, at least 16 hex digits
vb@1103
  1055
//      key_data (out)          ASCII armored OpenPGP secret key
vb@1103
  1056
//      size (out)              amount of data to handle
vb@1103
  1057
//
vb@1103
  1058
//  return value:
vb@1103
  1059
//      PEP_STATUS_OK = 0       key was successfully exported
vb@1103
  1060
//      PEP_OUT_OF_MEMORY       out of memory
vb@1103
  1061
//      PEP_KEY_NOT_FOUND       key not found
vb@1103
  1062
//      PEP_CANNOT_EXPORT_KEY   cannot export secret key (i.e. it's on an HKS)
vb@1103
  1063
//
vb@1103
  1064
//  caveat:
vb@1103
  1065
//      the key_data goes to the ownership of the caller
vb@1103
  1066
//      the caller is responsible to free() it (on Windoze use pEp_free())
vb@1103
  1067
//      beware of leaking secret key data - overwrite it in memory after use
vb@1103
  1068
krista@2593
  1069
DYNAMIC_API PEP_STATUS export_secret_key(
krista@2593
  1070
        PEP_SESSION session, const char *fpr, char **key_data, size_t *size
krista@2593
  1071
    );
krista@2593
  1072
krista@2593
  1073
krista@2593
  1074
// export_secrect_key() - deprecated misspelled function. Please replace with
krista@2593
  1075
//                        export_secret_key
krista@2593
  1076
vb@1103
  1077
DYNAMIC_API PEP_STATUS export_secrect_key(
vb@1103
  1078
        PEP_SESSION session, const char *fpr, char **key_data, size_t *size
vb@1103
  1079
    );
vb@1103
  1080
vb@1103
  1081
vb@0
  1082
// recv_key() - update key(s) from keyserver
vb@0
  1083
//
vb@0
  1084
//  parameters:
vb@0
  1085
//      session (in)            session handle
vb@0
  1086
//      pattern (in)            key id, user id or address to search for as
vb@0
  1087
//                              UTF-8 string
vb@0
  1088
vb@0
  1089
DYNAMIC_API PEP_STATUS recv_key(PEP_SESSION session, const char *pattern);
vb@0
  1090
vb@0
  1091
vb@0
  1092
// find_keys() - find keys in keyring
vb@0
  1093
//
vb@0
  1094
//  parameters:
vb@0
  1095
//      session (in)            session handle
vb@0
  1096
//      pattern (in)            key id, user id or address to search for as
vb@0
  1097
//                              UTF-8 string
vb@0
  1098
//      keylist (out)           list of fingerprints found or NULL on error
vb@0
  1099
//
vb@0
  1100
//  caveat:
roker@529
  1101
//        the ownerships of keylist isgoing to the caller
roker@529
  1102
//        the caller must use free_stringlist() to free it
vb@0
  1103
vb@0
  1104
vb@0
  1105
DYNAMIC_API PEP_STATUS find_keys(
vb@0
  1106
        PEP_SESSION session, const char *pattern, stringlist_t **keylist
vb@0
  1107
    );
vb@0
  1108
vb@0
  1109
// send_key() - send key(s) to keyserver
vb@0
  1110
//
vb@0
  1111
//  parameters:
vb@0
  1112
//      session (in)            session handle
vb@0
  1113
//      pattern (in)            key id, user id or address to search for as
vb@0
  1114
//                              UTF-8 string
vb@0
  1115
vb@0
  1116
DYNAMIC_API PEP_STATUS send_key(PEP_SESSION session, const char *pattern);
vb@0
  1117
vb@0
  1118
vb@0
  1119
// pEp_free() - free memory allocated by pEp engine
vb@0
  1120
//
vb@0
  1121
//  parameters:
vb@0
  1122
//      p (in)                  pointer to free
vb@0
  1123
//
vb@0
  1124
//  The reason for this function is that heap management can be a pretty
vb@0
  1125
//  complex task with Windoze. This free() version calls the free()
vb@0
  1126
//  implementation of the C runtime library which was used to build pEp engine,
vb@0
  1127
//  so you're using the correct heap. For more information, see:
vb@0
  1128
//  <http://msdn.microsoft.com/en-us/library/windows/desktop/aa366711(v=vs.85).aspx>
vb@0
  1129
vb@0
  1130
DYNAMIC_API void pEp_free(void *p);
vb@0
  1131
vb@8
  1132
vb@8
  1133
// get_trust() - get the trust level a key has for a person
vb@8
  1134
//
vb@8
  1135
//  parameters:
vb@8
  1136
//      session (in)            session handle
vb@8
  1137
//      identity (inout)        user_id and fpr to check as UTF-8 strings (in)
krista@2461
  1138
//                              comm_type as result (out)
vb@8
  1139
//
vb@14
  1140
//  this function modifies the given identity struct; the struct remains in
vb@251
  1141
//  the ownership of the caller
vb@14
  1142
//  if the trust level cannot be determined identity->comm_type is set
vb@14
  1143
//  to PEP_ct_unknown
vb@8
  1144
vb@8
  1145
DYNAMIC_API PEP_STATUS get_trust(PEP_SESSION session, pEp_identity *identity);
vb@8
  1146
krista@2129
  1147
krista@1797
  1148
PEP_STATUS set_trust(PEP_SESSION session, 
krista@2480
  1149
                     pEp_identity* identity);
krista@1805
  1150
                            
krista@1805
  1151
PEP_STATUS update_trust_for_fpr(PEP_SESSION session, 
krista@1805
  1152
                                const char* fpr, 
krista@1805
  1153
                                PEP_comm_type comm_type);
vb@8
  1154
vb@251
  1155
// least_trust() - get the least known trust level for a key in the database
vb@251
  1156
//
vb@251
  1157
//  parameters:
vb@251
  1158
//      session (in)            session handle
vb@251
  1159
//      fpr (in)                fingerprint of key to check
vb@251
  1160
//      comm_type (out)         least comm_type as result (out)
vb@251
  1161
//
vb@251
  1162
//  if the trust level cannot be determined comm_type is set to PEP_ct_unknown
vb@251
  1163
vb@251
  1164
DYNAMIC_API PEP_STATUS least_trust(
vb@251
  1165
        PEP_SESSION session,
vb@251
  1166
        const char *fpr,
vb@251
  1167
        PEP_comm_type *comm_type
vb@251
  1168
    );
vb@251
  1169
vb@251
  1170
vb@9
  1171
// get_key_rating() - get the rating a bare key has
vb@9
  1172
//
vb@9
  1173
//  parameters:
vb@9
  1174
//      session (in)            session handle
vb@9
  1175
//      fpr (in)                unique identifyer for key as UTF-8 string
vb@9
  1176
//      comm_type (out)         key rating
vb@10
  1177
//
vb@14
  1178
//  if an error occurs, *comm_type is set to PEP_ct_unknown and an error
vb@10
  1179
//  is returned
vb@9
  1180
vb@9
  1181
DYNAMIC_API PEP_STATUS get_key_rating(
vb@14
  1182
        PEP_SESSION session,
vb@14
  1183
        const char *fpr,
vb@14
  1184
        PEP_comm_type *comm_type
vb@9
  1185
    );
vb@9
  1186
vb@9
  1187
vb@198
  1188
// renew_key() - renew an expired key
vb@196
  1189
//
vb@196
  1190
//  parameters:
vb@196
  1191
//      session (in)            session handle
vb@214
  1192
//      fpr (in)                ID of key to renew as UTF-8 string
vb@201
  1193
//      ts (in)                 timestamp when key should expire or NULL for
vb@201
  1194
//                              default
vb@196
  1195
vb@201
  1196
DYNAMIC_API PEP_STATUS renew_key(
vb@201
  1197
        PEP_SESSION session,
vb@201
  1198
        const char *fpr,
vb@201
  1199
        const timestamp *ts
vb@201
  1200
    );
vb@196
  1201
vb@196
  1202
vb@224
  1203
// revoke_key() - revoke a key
vb@197
  1204
//
vb@197
  1205
//  parameters:
vb@197
  1206
//      session (in)            session handle
vb@214
  1207
//      fpr (in)                ID of key to revoke as UTF-8 string
vb@211
  1208
//      reason (in)             text with reason for revoke as UTF-8 string
vb@211
  1209
//                              or NULL if reason unknown
vb@211
  1210
//
vb@211
  1211
//  caveat:
vb@211
  1212
//      reason text must not include empty lines
vb@224
  1213
//      this function is meant for internal use only; better use
krista@1213
  1214
//      key_mistrusted() of keymanagement API
vb@197
  1215
vb@211
  1216
DYNAMIC_API PEP_STATUS revoke_key(
vb@211
  1217
        PEP_SESSION session,
vb@211
  1218
        const char *fpr,
vb@211
  1219
        const char *reason
vb@211
  1220
    );
vb@197
  1221
vb@197
  1222
vb@214
  1223
// key_expired() - flags if a key is already expired
vb@214
  1224
//
vb@214
  1225
//  parameters:
vb@214
  1226
//      session (in)            session handle
vb@214
  1227
//      fpr (in)                ID of key to check as UTF-8 string
Edouard@701
  1228
//      when (in)               UTC time of when should expiry be considered
vb@214
  1229
//      expired (out)           flag if key expired
vb@214
  1230
vb@214
  1231
DYNAMIC_API PEP_STATUS key_expired(
vb@214
  1232
        PEP_SESSION session,
vb@214
  1233
        const char *fpr,
Edouard@701
  1234
        const time_t when,
vb@214
  1235
        bool *expired
vb@214
  1236
    );
vb@214
  1237
Edouard@694
  1238
    
Edouard@694
  1239
// key_revoked() - flags if a key is already revoked
Edouard@694
  1240
//
Edouard@694
  1241
//  parameters:
Edouard@694
  1242
//      session (in)            session handle
Edouard@694
  1243
//      fpr (in)                ID of key to check as UTF-8 string
Edouard@694
  1244
//      revoked (out)           flag if key revoked
Edouard@694
  1245
Edouard@694
  1246
DYNAMIC_API PEP_STATUS key_revoked(
Edouard@694
  1247
        PEP_SESSION session,
Edouard@694
  1248
        const char *fpr,
Edouard@694
  1249
        bool *revoked
Edouard@694
  1250
    );
Edouard@694
  1251
krista@1797
  1252
PEP_STATUS get_key_userids(
krista@1797
  1253
        PEP_SESSION session,
krista@1797
  1254
        const char* fpr,
krista@1797
  1255
        stringlist_t** keylist
krista@1797
  1256
    );
krista@1797
  1257
vb@214
  1258
vb@450
  1259
// get_crashdump_log() - get the last log messages out
vb@450
  1260
//
vb@450
  1261
//  parameters:
vb@450
  1262
//      session (in)            session handle
vb@450
  1263
//      maxlines (in)           maximum number of lines (0 for default)
vb@458
  1264
//      logdata (out)           logdata as string in double quoted CSV format
vb@463
  1265
//                              column1 is title
vb@463
  1266
//                              column2 is entity
vb@463
  1267
//                              column3 is description
vb@463
  1268
//                              column4 is comment
vb@462
  1269
//
vb@462
  1270
//  caveat:
vb@462
  1271
//      the ownership of logdata goes to the caller
vb@450
  1272
vb@450
  1273
DYNAMIC_API PEP_STATUS get_crashdump_log(
vb@450
  1274
        PEP_SESSION session,
vb@450
  1275
        int maxlines,
vb@450
  1276
        char **logdata
vb@450
  1277
    );
vb@450
  1278
vb@450
  1279
dirk@501
  1280
// get_languagelist() - get the list of languages
vb@458
  1281
//
vb@458
  1282
//  parameters:
vb@458
  1283
//      session (in)            session handle
vb@458
  1284
//      languages (out)         languages as string in double quoted CSV format
vb@463
  1285
//                              column 1 is the ISO 639-1 language code
vb@463
  1286
//                              column 2 is the name of the language
vb@462
  1287
//
vb@462
  1288
//  caveat:
vb@462
  1289
//      the ownership of languages goes to the caller
vb@458
  1290
vb@458
  1291
DYNAMIC_API PEP_STATUS get_languagelist(
vb@458
  1292
        PEP_SESSION session,
vb@458
  1293
        char **languages
vb@458
  1294
    );
vb@458
  1295
vb@458
  1296
vb@458
  1297
// get_phrase() - get phrase in a dedicated language through i18n
vb@458
  1298
//
vb@458
  1299
//  parameters:
vb@458
  1300
//      session (in)            session handle
roker@529
  1301
//      lang (in)               C string with ISO 639-1 language code
vb@458
  1302
//      phrase_id (in)          id of phrase in i18n
vb@458
  1303
//      phrase (out)            phrase as UTF-8 string
vb@462
  1304
//
vb@462
  1305
//  caveat:
vb@462
  1306
//      the ownership of phrase goes to the caller
vb@458
  1307
vb@458
  1308
DYNAMIC_API PEP_STATUS get_phrase(
vb@458
  1309
        PEP_SESSION session,
vb@458
  1310
        const char *lang,
vb@458
  1311
        int phrase_id,
vb@458
  1312
        char **phrase
vb@458
  1313
    );
vb@458
  1314
vb@458
  1315
vb@632
  1316
// sequence_value() - raise the value of a named sequence and retrieve it
vb@632
  1317
//
vb@632
  1318
//  parameters:
vb@632
  1319
//      session (in)            session handle
vb@2848
  1320
//      name (in)               name of sequence
vb@2848
  1321
//      value (out)             value of sequence
vb@1085
  1322
//
vb@1085
  1323
//  returns:
vb@1086
  1324
//      PEP_STATUS_OK                   no error, not own sequence
vb@1086
  1325
//      PEP_SEQUENCE_VIOLATED           if sequence violated
vb@1086
  1326
//      PEP_CANNOT_INCREASE_SEQUENCE    if sequence cannot be increased
vb@1086
  1327
//      PEP_OWN_SEQUENCE                if own sequence
vb@632
  1328
vb@632
  1329
DYNAMIC_API PEP_STATUS sequence_value(
vb@632
  1330
        PEP_SESSION session,
vb@2848
  1331
        const char *name,
vb@652
  1332
        int32_t *value
vb@632
  1333
    );
vb@632
  1334
vb@1044
  1335
Edouard@694
  1336
// set_revoked() - records relation between a revoked key and its replacement
Edouard@694
  1337
//
Edouard@694
  1338
//  parameters:
Edouard@694
  1339
//      session (in)            session handle
Edouard@694
  1340
//      revoked_fpr (in)        revoked fingerprint
Edouard@694
  1341
//      replacement_fpr (in)    replacement key fingerprint
Edouard@694
  1342
//      revocation_date (in)    revocation date
Edouard@694
  1343
Edouard@693
  1344
DYNAMIC_API PEP_STATUS set_revoked(
Edouard@693
  1345
       PEP_SESSION session,
Edouard@693
  1346
       const char *revoked_fpr,
Edouard@693
  1347
       const char *replacement_fpr,
Edouard@693
  1348
       const uint64_t revocation_date
Edouard@693
  1349
    );
Edouard@693
  1350
vb@958
  1351
Edouard@694
  1352
// get_revoked() - find revoked key that may have been replaced by given key, if any
Edouard@694
  1353
//
Edouard@694
  1354
//  parameters:
Edouard@694
  1355
//      session (in)            session handle
Edouard@694
  1356
//      fpr (in)                given fingerprint
Edouard@694
  1357
//      revoked_fpr (out)       revoked fingerprint
Edouard@694
  1358
//      revocation_date (out)   revocation date
Edouard@694
  1359
    
Edouard@693
  1360
DYNAMIC_API PEP_STATUS get_revoked(
Edouard@693
  1361
        PEP_SESSION session,
Edouard@693
  1362
        const char *fpr,
Edouard@693
  1363
        char **revoked_fpr,
Edouard@693
  1364
        uint64_t *revocation_date
Edouard@693
  1365
    );
Edouard@693
  1366
vb@958
  1367
// key_created() - get creation date of a key
vb@958
  1368
//
vb@958
  1369
//  parameters:
vb@958
  1370
//      session (in)            session handle
vb@958
  1371
//      fpr (in)                fingerprint of key
vb@958
  1372
//      created (out)           date of creation
vb@958
  1373
vb@958
  1374
PEP_STATUS key_created(
vb@958
  1375
        PEP_SESSION session,
vb@958
  1376
        const char *fpr,
vb@958
  1377
        time_t *created
vb@958
  1378
    );
vb@958
  1379
vb@958
  1380
krista@1377
  1381
// find_private_keys() - find keys in keyring
krista@1357
  1382
//
krista@1357
  1383
//  parameters:
krista@1357
  1384
//      session (in)            session handle
krista@1357
  1385
//      pattern (in)            key id, user id or address to search for as
krista@1357
  1386
//                              UTF-8 string
krista@1357
  1387
//      keylist (out)           list of fingerprints found or NULL on error
krista@1357
  1388
//
krista@1357
  1389
//  caveat:
krista@1357
  1390
//        the ownerships of keylist isgoing to the caller
krista@1357
  1391
//        the caller must use free_stringlist() to free it
krista@1357
  1392
PEP_STATUS find_private_keys(PEP_SESSION session, const char* pattern,
krista@1357
  1393
                             stringlist_t **keylist);
krista@1357
  1394
krista@1011
  1395
// get_engine_version() - returns the current version of pEpEngine (this is different
krista@1011
  1396
//                        from the pEp protocol version!)
krista@1011
  1397
//
krista@1011
  1398
//  parameters: none
krista@1011
  1399
//
krista@1011
  1400
//  return_value: const char* to the engine version string constant
krista@1011
  1401
//
krista@1011
  1402
DYNAMIC_API const char* get_engine_version();
krista@1011
  1403
vb@2833
  1404
// is_pEp_user() - returns true if the USER corresponding to this identity 
krista@2490
  1405
//                 has been listed in the *person* table as a pEp user. 
krista@2490
  1406
//
krista@2490
  1407
//  parameters:
krista@2490
  1408
//      identity (in) - identity containing the user_id to check (this is
krista@2490
  1409
//                      the only part of the struct we require to be set)
vb@2834
  1410
//      is_pEp (out)  - boolean pointer - will return true or false by
krista@2490
  1411
//                      reference with respect to whether or not user is
vb@2834
  1412
//                      a known pEp user
krista@2490
  1413
//
krista@2490
  1414
//  return_value: PEP_STATUS_OK if user found in person table
krista@2490
  1415
//                PEP_ILLEGAL_VALUE if no user_id in input
krista@2490
  1416
//                PEP_CANNOT_FIND_PERSON if user_id doesn't exist
krista@2490
  1417
//
krista@2490
  1418
//  caveat: This *does not check comm_type*
krista@2490
  1419
//                         
vb@2833
  1420
DYNAMIC_API PEP_STATUS is_pEp_user(PEP_SESSION session, 
krista@2490
  1421
                                   pEp_identity *identity, 
vb@2834
  1422
                                   bool* is_pEp);
krista@2490
  1423
krista@2490
  1424
krista@1307
  1425
vb@2833
  1426
DYNAMIC_API PEP_STATUS reset_pEptest_hack(PEP_SESSION session);
vb@482
  1427
krista@2461
  1428
// This is used internally when there is a temporary identity to be retrieved
krista@2461
  1429
// that may not yet have an FPR attached. See get_identity() for functionality,
krista@2461
  1430
// params and caveats.
krista@2461
  1431
PEP_STATUS get_identity_without_trust_check(
krista@2461
  1432
        PEP_SESSION session,
krista@2461
  1433
        const char *address,
krista@2461
  1434
        const char *user_id,
krista@2461
  1435
        pEp_identity **identity
krista@2461
  1436
    );
krista@2461
  1437
    
krista@2461
  1438
PEP_STATUS get_identities_by_address(
krista@2461
  1439
        PEP_SESSION session,
krista@2461
  1440
        const char *address,
krista@2461
  1441
        identity_list** id_list
krista@2461
  1442
    );
krista@2893
  1443
    
krista@2893
  1444
PEP_STATUS get_identities_by_userid(
krista@2893
  1445
        PEP_SESSION session,
krista@2893
  1446
        const char *user_id,
krista@2893
  1447
        identity_list **identities
krista@2893
  1448
    );    
krista@2461
  1449
        
krista@2461
  1450
PEP_STATUS replace_userid(PEP_SESSION session, const char* old_uid,
krista@2461
  1451
                              const char* new_uid);
krista@2461
  1452
                              
krista@2948
  1453
PEP_STATUS remove_key(PEP_SESSION session, const char* fpr);
krista@2948
  1454
                              
krista@2461
  1455
PEP_STATUS remove_fpr_as_default(PEP_SESSION session, 
krista@2461
  1456
                                    const char* fpr);
krista@2461
  1457
                              
krista@2461
  1458
                                    
krista@2461
  1459
PEP_STATUS get_main_user_fpr(PEP_SESSION session, 
krista@2461
  1460
                             const char* user_id,
krista@2461
  1461
                             char** main_fpr);
krista@2461
  1462
krista@2461
  1463
PEP_STATUS replace_main_user_fpr(PEP_SESSION session, const char* user_id,
krista@2461
  1464
                              const char* new_fpr);
krista@2461
  1465
    
krista@2817
  1466
DYNAMIC_API PEP_STATUS get_replacement_fpr(
krista@2817
  1467
        PEP_SESSION session,
krista@2817
  1468
        const char *fpr,
krista@2817
  1469
        char **revoked_fpr,
krista@2817
  1470
        uint64_t *revocation_date
krista@2817
  1471
    );
krista@2817
  1472
    
krista@2461
  1473
PEP_STATUS refresh_userid_default_key(PEP_SESSION session, const char* user_id);
krista@2461
  1474
krista@2468
  1475
// This ONLY sets the *user* flag, and creates a shell identity if necessary.
krista@2956
  1476
DYNAMIC_API PEP_STATUS set_as_pEp_user(PEP_SESSION session, pEp_identity* user);
krista@2468
  1477
krista@2480
  1478
// returns true (by reference) if a person with this user_id exists; 
krista@2480
  1479
// Also replaces aliased user_ids by defaults in identity.
krista@2480
  1480
PEP_STATUS exists_person(PEP_SESSION session, pEp_identity* identity, bool* exists);
krista@2468
  1481
krista@2477
  1482
PEP_STATUS set_pgp_keypair(PEP_SESSION session, const char* fpr);
krista@2468
  1483
krista@2995
  1484
// exposed for testing
krista@2995
  1485
PEP_STATUS set_person(PEP_SESSION session, pEp_identity* identity,
krista@2995
  1486
                      bool guard_transaction);
krista@2919
  1487
PEP_STATUS bind_own_ident_with_contact_ident(PEP_SESSION session,
krista@2919
  1488
                                             pEp_identity* own_ident, 
krista@2919
  1489
                                             pEp_identity* contact_ident);
krista@2919
  1490
krista@2817
  1491
PEP_STATUS get_last_contacted(
krista@2817
  1492
        PEP_SESSION session,
krista@2817
  1493
        identity_list** id_list
krista@2817
  1494
    );
krista@2817
  1495
krista@2817
  1496
PEP_STATUS get_own_ident_for_contact_id(PEP_SESSION session,
krista@2817
  1497
                                          const pEp_identity* contact,
krista@2817
  1498
                                          pEp_identity** own_ident);
krista@2817
  1499
krista@2817
  1500
PEP_STATUS exists_trust_entry(PEP_SESSION session, pEp_identity* identity,
krista@2817
  1501
                              bool* exists);
krista@2817
  1502
krista@2817
  1503
PEP_STATUS is_own_key(PEP_SESSION session, const char* fpr, bool* own_key);
krista@2817
  1504
krista@2893
  1505
PEP_STATUS get_identities_by_main_key_id(
krista@2893
  1506
        PEP_SESSION session,
krista@2893
  1507
        const char *fpr,
krista@2893
  1508
        identity_list **identities);
krista@3139
  1509
        
krista@3139
  1510
PEP_STATUS sign_only(PEP_SESSION session, 
krista@3139
  1511
                     const char *data, 
krista@3139
  1512
                     size_t data_size, 
krista@3139
  1513
                     const char *fpr, 
krista@3139
  1514
                     char **sign, 
krista@3139
  1515
                     size_t *sign_size);
krista@3139
  1516
                     
vb@0
  1517
#ifdef __cplusplus
vb@0
  1518
}
vb@0
  1519
#endif