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