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