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