src/pEpEngine.h
author Krista Grothoff <krista@pep-project.org>
Wed, 28 Sep 2016 13:49:12 +0200
branchENGINE-96
changeset 1213 a2e69db48026
parent 1170 8949bee99bcd
child 1234 c03758736a0b
permissions -rw-r--r--
ENGINE-96: #comment all calls renamed. Roker is checking out the semantics of the references to 'compromized' to see if they also need to be renamed to 'mistrusted' for consistency within the engine. THIS IS AN API CHANGE AND WILL BREAK ADAPTERS.
     1 #pragma once
     2 
     3 #ifdef __cplusplus
     4 extern "C" {
     5 #endif
     6 
     7 #include <stddef.h>
     8 #include <stdint.h>
     9 #include <stdbool.h>
    10 
    11 #include "dynamic_api.h"
    12 #include "stringlist.h"
    13 #include "stringpair.h"    
    14 #include "timestamp.h"
    15 
    16 #define PEP_VERSION "1.0" // protocol version
    17 
    18 #define PEP_OWN_USERID "pEp_own_userId"
    19     
    20 // pEp Engine API
    21 
    22 //  caveat:
    23 //      Unicode data has to be normalized to NFC before calling
    24 //      UTF-8 strings are UTF-8 encoded C strings (zero terminated)
    25 
    26 
    27 struct _pEpSession;
    28 typedef struct _pEpSession * PEP_SESSION;
    29 
    30 typedef enum {
    31     PEP_STATUS_OK                                   = 0,
    32 
    33     PEP_INIT_CANNOT_LOAD_GPGME                      = 0x0110,
    34     PEP_INIT_GPGME_INIT_FAILED                      = 0x0111,
    35     PEP_INIT_NO_GPG_HOME                            = 0x0112,
    36     PEP_INIT_NETPGP_INIT_FAILED                     = 0x0113,
    37 
    38     PEP_INIT_SQLITE3_WITHOUT_MUTEX                  = 0x0120,
    39     PEP_INIT_CANNOT_OPEN_DB                         = 0x0121,
    40     PEP_INIT_CANNOT_OPEN_SYSTEM_DB                  = 0x0122,
    41     
    42     PEP_KEY_NOT_FOUND                               = 0x0201,
    43     PEP_KEY_HAS_AMBIG_NAME                          = 0x0202,
    44     PEP_GET_KEY_FAILED                              = 0x0203,
    45     PEP_CANNOT_EXPORT_KEY                           = 0x0204,
    46     
    47     PEP_CANNOT_FIND_IDENTITY                        = 0x0301,
    48     PEP_CANNOT_SET_PERSON                           = 0x0381,
    49     PEP_CANNOT_SET_PGP_KEYPAIR                      = 0x0382,
    50     PEP_CANNOT_SET_IDENTITY                         = 0x0383,
    51     PEP_CANNOT_SET_TRUST                            = 0x0384,
    52     PEP_KEY_BLACKLISTED                             = 0x0385,
    53     
    54     PEP_UNENCRYPTED                                 = 0x0400,
    55     PEP_VERIFIED                                    = 0x0401,
    56     PEP_DECRYPTED                                   = 0x0402,
    57     PEP_DECRYPTED_AND_VERIFIED                      = 0x0403,
    58     PEP_DECRYPT_WRONG_FORMAT                        = 0x0404,
    59     PEP_DECRYPT_NO_KEY                              = 0x0405,
    60     PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH            = 0x0406,
    61     PEP_VERIFY_NO_KEY                               = 0x0407,
    62     PEP_VERIFIED_AND_TRUSTED                        = 0x0408,
    63     PEP_CANNOT_DECRYPT_UNKNOWN                      = 0x04ff,
    64 
    65     PEP_TRUSTWORD_NOT_FOUND                         = 0x0501,
    66 
    67     PEP_CANNOT_CREATE_KEY                           = 0x0601,
    68     PEP_CANNOT_SEND_KEY                             = 0x0602,
    69 
    70     PEP_PHRASE_NOT_FOUND                            = 0x0701,
    71 
    72     PEP_SEND_FUNCTION_NOT_REGISTERED                = 0x0801,
    73     PEP_CONTRAINTS_VIOLATED                         = 0x0802,
    74     PEP_CANNOT_ENCODE                               = 0x0803,
    75 
    76     PEP_SYNC_NO_TRUSTWORDS_CALLBACK                 = 0x0901,
    77     PEP_SYNC_ILLEGAL_MESSAGE                        = 0x0902,
    78     PEP_SYNC_NO_INJECT_CALLBACK                     = 0x0903,
    79 
    80     PEP_SEQUENCE_VIOLATED                           = 0x0970,
    81     PEP_CANNOT_INCREASE_SEQUENCE                    = 0x0971,
    82     PEP_CANNOT_SET_SEQUENCE_VALUE                   = 0x0972,
    83     PEP_OWN_SEQUENCE                                = 0x097f,
    84 
    85     PEP_SYNC_STATEMACHINE_ERROR                     = 0x0980,
    86     PEP_SYNC_NO_TRUST                               = 0x0981,
    87     PEP_STATEMACHINE_INVALID_STATE                  = 0x0982,
    88     PEP_STATEMACHINE_INVALID_EVENT                  = 0x0983,
    89     PEP_STATEMACHINE_INVALID_CONDITION              = 0x0984,
    90     PEP_STATEMACHINE_INVALID_ACTION                 = 0x0985,
    91 
    92     PEP_COMMIT_FAILED                               = 0xff01,
    93     PEP_MESSAGE_CONSUMED                            = 0xff02,
    94     PEP_MESSAGE_DISCARDED                           = 0xff03,
    95 
    96     PEP_RECORD_NOT_FOUND                            = -6,
    97     PEP_CANNOT_CREATE_TEMP_FILE                     = -5,
    98     PEP_ILLEGAL_VALUE                               = -4,
    99     PEP_BUFFER_TOO_SMALL                            = -3,
   100     PEP_OUT_OF_MEMORY                               = -2,
   101     PEP_UNKNOWN_ERROR                               = -1
   102 } PEP_STATUS;
   103 
   104 
   105 // INIT_STATUS init() - initialize pEpEngine for a thread
   106 //
   107 //  parameters:
   108 //        session (out)   init() allocates session memory and returns a pointer
   109 //                        as a handle
   110 //
   111 //  return value:
   112 //        PEP_STATUS_OK = 0                 if init() succeeds
   113 //        PEP_INIT_SQLITE3_WITHOUT_MUTEX    if SQLite3 was compiled with
   114 //                                            SQLITE_THREADSAFE 0
   115 //        PEP_INIT_CANNOT_LOAD_GPGME        if libgpgme.dll cannot be found
   116 //        PEP_INIT_GPGME_INIT_FAILED        if GPGME init fails
   117 //        PEP_INIT_CANNOT_OPEN_DB           if user's management db cannot be
   118 //                                            opened
   119 //        PEP_INIT_CANNOT_OPEN_SYSTEM_DB    if system's management db cannot be
   120 //                                            opened
   121 //
   122 //  caveat:
   123 //      the pointer is valid only if the return value is PEP_STATUS_OK
   124 //      in other case a NULL pointer will be returned; a valid handle must
   125 //      be released using release() when it's no longer needed
   126 //
   127 //      the caller has to guarantee that the first call to this function
   128 //      will succeed before further calls can be done
   129 
   130 DYNAMIC_API PEP_STATUS init(PEP_SESSION *session);
   131 
   132 
   133 // void release() - release thread session handle
   134 //
   135 //  parameters:
   136 //        session (in)    session handle to release
   137 //
   138 //    caveat:
   139 //        the last release() can be called only when all other release() calls
   140 //        are done
   141 
   142 DYNAMIC_API void release(PEP_SESSION session);
   143 
   144 
   145 // config_passive_mode() - enable passive mode
   146 //
   147 //  parameters:
   148 //      session (in)    session handle
   149 //      enable (in)     flag if enabled or disabled
   150 
   151 DYNAMIC_API void config_passive_mode(PEP_SESSION session, bool enable);
   152 
   153 
   154 // config_unencrypted_subject() - disable subject encryption
   155 //
   156 //  parameters:
   157 //      session (in)    session handle
   158 //      enable (in)     flag if enabled or disabled
   159 
   160 DYNAMIC_API void config_unencrypted_subject(PEP_SESSION session, bool enable);
   161 
   162 
   163 // config_use_only_own_private_keys() - enable passive mode
   164 //
   165 //  parameters:
   166 //      session (in)    session handle
   167 //      enable (in)     flag if enabled or disabled
   168 
   169 DYNAMIC_API void config_use_only_own_private_keys(PEP_SESSION session, bool enable);
   170 
   171 
   172 // config_keep_sync_msg() - do not remove sync messages (for debugging purposes)
   173 //
   174 //      session (in)    session handle
   175 //      enable (in)     flag if enabled or disabled
   176 
   177 DYNAMIC_API void config_keep_sync_msg(PEP_SESSION session, bool enable);
   178 
   179 
   180 // decrypt_and_verify() - decrypt and/or verify a message
   181 //
   182 //    parameters:
   183 //        session (in)    session handle
   184 //        ctext (in)      cipher text to decrypt and/or verify
   185 //        csize (in)      size of cipher text
   186 //        ptext (out)     pointer to internal buffer with plain text
   187 //        psize (out)     size of plain text
   188 //        keylist (out)   list of key ids which where used to encrypt
   189 //
   190 //    return value:
   191 //        PEP_UNENCRYPTED               message was unencrypted and not signed
   192 //        PEP_VERIFIED                  message was unencrypted, signature matches
   193 //        PEP_DECRYPTED                 message is decrypted now, no signature
   194 //        PEP_DECRYPTED_AND_VERIFIED    message is decrypted now and verified
   195 //        PEP_DECRYPT_WRONG_FORMAT      message has wrong format to handle
   196 //        PEP_DECRYPT_NO_KEY            key not available to decrypt and/or verify
   197 //        PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH    wrong signature
   198 //
   199 //    caveat:
   200 //        the ownerships of ptext as well as keylist are going to the caller
   201 //        the caller must use free() (or an Windoze pEp_free()) and
   202 //        free_stringlist() to free them
   203 //
   204 //      if this function failes an error message may be the first element of
   205 //      keylist and the other elements may be the keys used for encryption
   206 
   207 DYNAMIC_API PEP_STATUS decrypt_and_verify(
   208         PEP_SESSION session, const char *ctext, size_t csize,
   209         char **ptext, size_t *psize, stringlist_t **keylist
   210     );
   211 
   212 
   213 // verify_text() - verfy plain text with a digital signature
   214 //
   215 //  parameters:
   216 //      session (in)    session handle
   217 //      text (in)       text to verify
   218 //      size (in)       size of text
   219 //      signature (in)  signature text
   220 //      sig_size (in)   size of signature
   221 //      keylist (out)   list of key ids which where used to encrypt or NULL on
   222 //                        error
   223 //
   224 //  return value:
   225 //        PEP_VERIFIED                message was unencrypted, signature matches
   226 //        PEP_DECRYPT_NO_KEY          key not available to decrypt and/or verify
   227 //        PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH    wrong signature
   228 
   229 DYNAMIC_API PEP_STATUS verify_text(
   230         PEP_SESSION session, const char *text, size_t size,
   231         const char *signature, size_t sig_size, stringlist_t **keylist
   232     );
   233 
   234 
   235 // encrypt_and_sign() - encrypt and sign a message
   236 //
   237 //    parameters:
   238 //        session (in)    session handle
   239 //        keylist (in)    list of key ids to encrypt with as C strings
   240 //        ptext (in)      plain text to decrypt and/or verify
   241 //        psize (in)      size of plain text
   242 //        ctext (out)     pointer to internal buffer with cipher text
   243 //        csize (out)     size of cipher text
   244 //
   245 //    return value:
   246 //        PEP_STATUS_OK = 0            encryption and signing succeeded
   247 //        PEP_KEY_NOT_FOUND            at least one of the receipient keys
   248 //                                     could not be found
   249 //        PEP_KEY_HAS_AMBIG_NAME       at least one of the receipient keys has
   250 //                                     an ambiguous name
   251 //        PEP_GET_KEY_FAILED           cannot retrieve key
   252 //
   253 //    caveat:
   254 //      the ownership of ctext is going to the caller
   255 //      the caller is responsible to free() it (on Windoze use pEp_free())
   256 //      the first key in keylist is being used to sign the message
   257 //      this implies there has to be a private key for that keypair
   258 
   259 DYNAMIC_API PEP_STATUS encrypt_and_sign(
   260         PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
   261         size_t psize, char **ctext, size_t *csize
   262     );
   263 
   264 
   265 // log_event() - log a user defined event defined by UTF-8 encoded strings into
   266 // management log
   267 //
   268 //    parameters:
   269 //        session (in)        session handle
   270 //        title (in)          C string with event name
   271 //        entity (in)         C string with name of entity which is logging
   272 //        description (in)    C string with long description for event or NULL if
   273 //                            omitted
   274 //        comment (in)        C string with user defined comment or NULL if
   275 //                            omitted
   276 //
   277 //    return value:
   278 //        PEP_STATUS_OK       log entry created
   279 
   280 DYNAMIC_API PEP_STATUS log_event(
   281         PEP_SESSION session,
   282         const char *title,
   283         const char *entity,
   284         const char *description,
   285         const char *comment
   286     );
   287 
   288 
   289 // trustword() - get the corresponding trustword for a 16 bit value
   290 //
   291 //    parameters:
   292 //        session (in)            session handle
   293 //        value (in)              value to find a trustword for
   294 //        lang (in)               C string with ISO 639-1 language code
   295 //        word (out)              pointer to C string with trustword UTF-8 encoded
   296 //                                NULL if language is not supported or trustword
   297 //                                wordlist is damaged or unavailable
   298 //        wsize (out)             length of trustword
   299 //
   300 //    return value:
   301 //        PEP_STATUS_OK            trustword retrieved
   302 //        PEP_TRUSTWORD_NOT_FOUND  trustword not found
   303 //
   304 //    caveat:
   305 //        the word pointer goes to the ownership of the caller
   306 //      the caller is responsible to free() it (on Windoze use pEp_free())
   307 
   308 DYNAMIC_API PEP_STATUS trustword(
   309             PEP_SESSION session, uint16_t value, const char *lang,
   310             char **word, size_t *wsize
   311         );
   312 
   313 
   314 // trustwords() - get trustwords for a string of hex values of a fingerprint
   315 //
   316 //    parameters:
   317 //        session (in)        session handle
   318 //        fingerprint (in)    C string with hex values to find trustwords for
   319 //        lang (in)           C string with ISO 639-1 language code
   320 //        words (out)         pointer to C string with trustwords UTF-8 encoded,
   321 //                            separated by a blank each
   322 //                            NULL if language is not supported or trustword
   323 //                            wordlist is damaged or unavailable
   324 //        wsize (out)         length of trustwords string
   325 //        max_words (in)      only generate a string with max_words;
   326 //                            if max_words == 0 there is no such limit
   327 //
   328 //    return value:
   329 //        PEP_STATUS_OK            trustwords retrieved
   330 //        PEP_OUT_OF_MEMORY        out of memory
   331 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   332 //
   333 //    caveat:
   334 //        the word pointer goes to the ownership of the caller
   335 //      the caller is responsible to free() it (on Windoze use pEp_free())
   336 //
   337 //  DON'T USE THIS FUNCTION FROM HIGH LEVEL LANGUAGES!
   338 //
   339 //  Better implement a simple one in the adapter yourself using trustword(), and
   340 //  return a list of trustwords.
   341 //  This function is provided for being used by C and C++ programs only.
   342 
   343 DYNAMIC_API PEP_STATUS trustwords(
   344         PEP_SESSION session, const char *fingerprint, const char *lang,
   345         char **words, size_t *wsize, int max_words
   346     );
   347 
   348 
   349 // TODO: increase versions in pEp.asn1 if rating changes
   350 
   351 typedef enum _PEP_comm_type {
   352     PEP_ct_unknown = 0,
   353 
   354     // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
   355 
   356     PEP_ct_no_encryption = 0x01,                // generic
   357     PEP_ct_no_encrypted_channel = 0x02,
   358     PEP_ct_key_not_found = 0x03,
   359     PEP_ct_key_expired = 0x04,
   360     PEP_ct_key_revoked = 0x05,
   361     PEP_ct_key_b0rken = 0x06,
   362     PEP_ct_my_key_not_included = 0x09,
   363 
   364     PEP_ct_security_by_obscurity = 0x0a,
   365     PEP_ct_b0rken_crypto = 0x0b,
   366     PEP_ct_key_too_short = 0x0c,
   367 
   368     PEP_ct_compromized = 0x0e,                  // known compromized connection
   369     PEP_ct_mistrusted = 0x0f,                   // known mistrusted key
   370 
   371     // range 0x10 to 0x3f: unconfirmed encryption
   372 
   373     PEP_ct_unconfirmed_encryption = 0x10,       // generic
   374     PEP_ct_OpenPGP_weak_unconfirmed = 0x11,     // RSA 1024 is weak
   375 
   376     PEP_ct_to_be_checked = 0x20,                // generic
   377     PEP_ct_SMIME_unconfirmed = 0x21,
   378     PEP_ct_CMS_unconfirmed = 0x22,
   379 
   380     PEP_ct_strong_but_unconfirmed = 0x30,       // generic
   381     PEP_ct_OpenPGP_unconfirmed = 0x38,          // key at least 2048 bit RSA or EC
   382     PEP_ct_OTR_unconfirmed = 0x3a,
   383 
   384     // range 0x40 to 0x7f: unconfirmed encryption and anonymization
   385 
   386     PEP_ct_unconfirmed_enc_anon = 0x40,         // generic
   387     PEP_ct_pEp_unconfirmed = 0x7f,
   388 
   389     PEP_ct_confirmed = 0x80,                    // this bit decides if trust is confirmed
   390 
   391     // range 0x81 to 0x8f: reserved
   392     // range 0x90 to 0xbf: confirmed encryption
   393 
   394     PEP_ct_confirmed_encryption = 0x90,         // generic
   395     PEP_ct_OpenPGP_weak = 0x91,                 // RSA 1024 is weak
   396 
   397     PEP_ct_to_be_checked_confirmed = 0xa0,      //generic
   398     PEP_ct_SMIME = 0xa1,
   399     PEP_ct_CMS = 0xa2,
   400 
   401     PEP_ct_strong_encryption = 0xb0,            // generic
   402     PEP_ct_OpenPGP = 0xb8,                      // key at least 2048 bit RSA or EC
   403     PEP_ct_OTR = 0xba,
   404 
   405     // range 0xc0 to 0xff: confirmed encryption and anonymization
   406 
   407     PEP_ct_confirmed_enc_anon = 0xc0,           // generic
   408     PEP_ct_pEp = 0xff
   409 } PEP_comm_type;
   410 
   411 typedef enum _identity_flags {
   412     // the first octet flags are app defined settings
   413     PEP_idf_not_for_sync = 1,   // don't use this identity for sync
   414     PEP_idf_list = 2,           // identity of list of persons
   415 
   416     // the second octet flags are calculated
   417     PEP_idf_devicegroup = 256   // identity of a device group member
   418 } identity_flags;
   419 
   420 typedef unsigned int identity_flags_t;
   421 
   422 typedef struct _pEp_identity {
   423     char *address;              // C string with address UTF-8 encoded
   424     char *fpr;                  // C string with fingerprint UTF-8 encoded
   425     char *user_id;              // C string with user ID UTF-8 encoded
   426     char *username;             // C string with user name UTF-8 encoded
   427     PEP_comm_type comm_type;    // type of communication with this ID
   428     char lang[3];               // language of conversation
   429                                 // ISO 639-1 ALPHA-2, last byte is 0
   430     bool me;                    // if this is the local user herself/himself
   431     identity_flags_t flags;     // identity_flag1 | identity_flag2 | ...
   432 } pEp_identity;
   433 
   434 typedef struct _identity_list {
   435     pEp_identity *ident;
   436     struct _identity_list *next;
   437 } identity_list;
   438 
   439 
   440 // new_identity() - allocate memory and set the string and size fields
   441 //
   442 //  parameters:
   443 //      address (in)        UTF-8 string or NULL 
   444 //      fpr (in)            UTF-8 string or NULL 
   445 //      user_id (in)        UTF-8 string or NULL 
   446 //      username (in)       UTF-8 string or NULL 
   447 //
   448 //  return value:
   449 //      pEp_identity struct or NULL if out of memory
   450 //
   451 //  caveat:
   452 //      the strings are copied; the original strings are still being owned by
   453 //      the caller
   454 
   455 DYNAMIC_API pEp_identity *new_identity(
   456         const char *address, const char *fpr, const char *user_id,
   457         const char *username
   458     );
   459 
   460 
   461 // identity_dup() - allocate memory and duplicate
   462 //
   463 //  parameters:
   464 //      src (in)            identity to duplicate
   465 //
   466 //  return value:
   467 //      pEp_identity struct or NULL if out of memory
   468 //
   469 //  caveat:
   470 //      the strings are copied; the original strings are still being owned by
   471 //      the caller
   472 
   473 DYNAMIC_API pEp_identity *identity_dup(const pEp_identity *src);
   474 
   475 
   476 // free_identity() - free all memory being occupied by a pEp_identity struct
   477 //
   478 //  parameters:
   479 //      identity (in)       struct to release
   480 //
   481 //  caveat:
   482 //      not only the struct but also all string memory referenced by the
   483 //      struct is being freed; all pointers inside are invalid afterwards
   484 
   485 DYNAMIC_API void free_identity(pEp_identity *identity);
   486 
   487 
   488 // get_identity() - get identity information
   489 //
   490 //    parameters:
   491 //        session (in)        session handle
   492 //        address (in)        C string with communication address, UTF-8 encoded
   493 //        user_id (in)        unique C string to identify person that identity
   494 //                            is refering to
   495 //        identity (out)      pointer to pEp_identity structure with results or
   496 //                            NULL if failure
   497 //
   498 //    caveat:
   499 //        address and user_id are being copied; the original strings remains in
   500 //        the ownership of the caller
   501 //        the resulting pEp_identity structure goes to the ownership of the
   502 //        caller and has to be freed with free_identity() when not in use any
   503 //        more
   504 
   505 DYNAMIC_API PEP_STATUS get_identity(
   506         PEP_SESSION session,
   507         const char *address,
   508         const char *user_id,
   509         pEp_identity **identity
   510     );
   511 
   512 // set_identity() - set identity information
   513 //
   514 //    parameters:
   515 //        session (in)        session handle
   516 //        identity (in)       pointer to pEp_identity structure
   517 //
   518 //    return value:
   519 //        PEP_STATUS_OK = 0             encryption and signing succeeded
   520 //        PEP_CANNOT_SET_PERSON         writing to table person failed
   521 //        PEP_CANNOT_SET_PGP_KEYPAIR    writing to table pgp_keypair failed
   522 //        PEP_CANNOT_SET_IDENTITY       writing to table identity failed
   523 //        PEP_COMMIT_FAILED             SQL commit failed
   524 //        PEP_KEY_BLACKLISTED           Key blacklisted, cannot set identity
   525 //
   526 //    caveat:
   527 //        address, fpr, user_id and username must be given
   528 
   529 DYNAMIC_API PEP_STATUS set_identity(
   530         PEP_SESSION session, const pEp_identity *identity
   531     );
   532 
   533 
   534 // set_identity_flags() - update identity flags on existing identity
   535 //
   536 //    parameters:
   537 //        session (in)        session handle
   538 //        identity (in,out)   pointer to pEp_identity structure
   539 //        flags (in)          new value for flags
   540 //
   541 //    return value:
   542 //        PEP_STATUS_OK = 0             encryption and signing succeeded
   543 //        PEP_CANNOT_SET_IDENTITY       update of identity failed
   544 //
   545 //    caveat:
   546 //        address and user_id must be given in identity
   547 
   548 DYNAMIC_API PEP_STATUS set_identity_flags(
   549         PEP_SESSION session,
   550         pEp_identity *identity,
   551         unsigned int flags
   552     );
   553 
   554 
   555 // mark_as_compromized() - mark key in trust db as compromized
   556 //
   557 //    parameters:
   558 //        session (in)        session handle
   559 //        fpr (in)            fingerprint of key to mark
   560 
   561 DYNAMIC_API PEP_STATUS mark_as_compromized(
   562         PEP_SESSION session,
   563         const char *fpr
   564     );
   565 
   566 
   567 // generate_keypair() - generate a new key pair and add it to the key ring
   568 //
   569 //  parameters:
   570 //      session (in)            session handle
   571 //        identity (inout)      pointer to pEp_identity structure
   572 //
   573 //    return value:
   574 //        PEP_STATUS_OK = 0       encryption and signing succeeded
   575 //        PEP_ILLEGAL_VALUE       illegal values for identity fields given
   576 //        PEP_CANNOT_CREATE_KEY   key engine is on strike
   577 //
   578 //  caveat:
   579 //      address and username fields must be set to UTF-8 strings
   580 //      the fpr field must be set to NULL
   581 //
   582 //      this function allocates a string and sets set fpr field of identity
   583 //      the caller is responsible to call free() for that string or use
   584 //      free_identity() on the struct
   585 
   586 DYNAMIC_API PEP_STATUS generate_keypair(
   587         PEP_SESSION session, pEp_identity *identity
   588     );
   589 
   590 
   591 // delete_keypair() - delete a public key or a key pair from the key ring
   592 //
   593 //  parameters:
   594 //      session (in)            session handle
   595 //      fpr (in)                C string with key id or fingerprint of the
   596 //                              public key
   597 //
   598 //  return value:
   599 //      PEP_STATUS_OK = 0       key was successfully deleted
   600 //      PEP_KEY_NOT_FOUND       key not found
   601 //      PEP_ILLEGAL_VALUE       not a valid key id or fingerprint
   602 //      PEP_KEY_HAS_AMBIG_NAME  fpr does not uniquely identify a key
   603 //      PEP_OUT_OF_MEMORY       out of memory
   604 
   605 DYNAMIC_API PEP_STATUS delete_keypair(PEP_SESSION session, const char *fpr);
   606 
   607 
   608 // import_key() - import key from data
   609 //
   610 //  parameters:
   611 //      session (in)            session handle
   612 //      key_data (in)           key data, i.e. ASCII armored OpenPGP key
   613 //      size (in)               amount of data to handle
   614 //      private_keys (out)      list of private keys that have been imported
   615 //
   616 //  return value:
   617 //      PEP_STATUS_OK = 0       key was successfully imported
   618 //      PEP_OUT_OF_MEMORY       out of memory
   619 //      PEP_ILLEGAL_VALUE       there is no key data to import
   620 //
   621 //  caveat:
   622 //      private_keys goes to the ownership of the caller
   623 //      private_keys can be left NULL, it is then ignored
   624 
   625 DYNAMIC_API PEP_STATUS import_key(
   626         PEP_SESSION session,
   627         const char *key_data,
   628         size_t size,
   629         identity_list **private_keys
   630     );
   631 
   632 
   633 // export_key() - export ascii armored key
   634 //
   635 //  parameters:
   636 //      session (in)            session handle
   637 //      fpr (in)                key id or fingerprint of key
   638 //      key_data (out)          ASCII armored OpenPGP key
   639 //      size (out)              amount of data to handle
   640 //
   641 //  return value:
   642 //      PEP_STATUS_OK = 0       key was successfully exported
   643 //      PEP_OUT_OF_MEMORY       out of memory
   644 //      PEP_KEY_NOT_FOUND       key not found
   645 //
   646 //  caveat:
   647 //      the key_data goes to the ownership of the caller
   648 //      the caller is responsible to free() it (on Windoze use pEp_free())
   649 
   650 DYNAMIC_API PEP_STATUS export_key(
   651         PEP_SESSION session, const char *fpr, char **key_data, size_t *size
   652     );
   653 
   654 
   655 // export_secret_key() - export secret key ascii armored
   656 //
   657 //  parameters:
   658 //      session (in)            session handle
   659 //      fpr (in)                fingerprint of key, at least 16 hex digits
   660 //      key_data (out)          ASCII armored OpenPGP secret key
   661 //      size (out)              amount of data to handle
   662 //
   663 //  return value:
   664 //      PEP_STATUS_OK = 0       key was successfully exported
   665 //      PEP_OUT_OF_MEMORY       out of memory
   666 //      PEP_KEY_NOT_FOUND       key not found
   667 //      PEP_CANNOT_EXPORT_KEY   cannot export secret key (i.e. it's on an HKS)
   668 //
   669 //  caveat:
   670 //      the key_data goes to the ownership of the caller
   671 //      the caller is responsible to free() it (on Windoze use pEp_free())
   672 //      beware of leaking secret key data - overwrite it in memory after use
   673 
   674 DYNAMIC_API PEP_STATUS export_secrect_key(
   675         PEP_SESSION session, const char *fpr, char **key_data, size_t *size
   676     );
   677 
   678 
   679 // recv_key() - update key(s) from keyserver
   680 //
   681 //  parameters:
   682 //      session (in)            session handle
   683 //      pattern (in)            key id, user id or address to search for as
   684 //                              UTF-8 string
   685 
   686 DYNAMIC_API PEP_STATUS recv_key(PEP_SESSION session, const char *pattern);
   687 
   688 
   689 // find_keys() - find keys in keyring
   690 //
   691 //  parameters:
   692 //      session (in)            session handle
   693 //      pattern (in)            key id, user id or address to search for as
   694 //                              UTF-8 string
   695 //      keylist (out)           list of fingerprints found or NULL on error
   696 //
   697 //  caveat:
   698 //        the ownerships of keylist isgoing to the caller
   699 //        the caller must use free_stringlist() to free it
   700 
   701 
   702 DYNAMIC_API PEP_STATUS find_keys(
   703         PEP_SESSION session, const char *pattern, stringlist_t **keylist
   704     );
   705 
   706 // send_key() - send key(s) to keyserver
   707 //
   708 //  parameters:
   709 //      session (in)            session handle
   710 //      pattern (in)            key id, user id or address to search for as
   711 //                              UTF-8 string
   712 
   713 DYNAMIC_API PEP_STATUS send_key(PEP_SESSION session, const char *pattern);
   714 
   715 
   716 // pEp_free() - free memory allocated by pEp engine
   717 //
   718 //  parameters:
   719 //      p (in)                  pointer to free
   720 //
   721 //  The reason for this function is that heap management can be a pretty
   722 //  complex task with Windoze. This free() version calls the free()
   723 //  implementation of the C runtime library which was used to build pEp engine,
   724 //  so you're using the correct heap. For more information, see:
   725 //  <http://msdn.microsoft.com/en-us/library/windows/desktop/aa366711(v=vs.85).aspx>
   726 
   727 DYNAMIC_API void pEp_free(void *p);
   728 
   729 
   730 // get_trust() - get the trust level a key has for a person
   731 //
   732 //  parameters:
   733 //      session (in)            session handle
   734 //      identity (inout)        user_id and fpr to check as UTF-8 strings (in)
   735 //                              user_id and comm_type as result (out)
   736 //
   737 //  this function modifies the given identity struct; the struct remains in
   738 //  the ownership of the caller
   739 //  if the trust level cannot be determined identity->comm_type is set
   740 //  to PEP_ct_unknown
   741 
   742 DYNAMIC_API PEP_STATUS get_trust(PEP_SESSION session, pEp_identity *identity);
   743 
   744 
   745 // least_trust() - get the least known trust level for a key in the database
   746 //
   747 //  parameters:
   748 //      session (in)            session handle
   749 //      fpr (in)                fingerprint of key to check
   750 //      comm_type (out)         least comm_type as result (out)
   751 //
   752 //  if the trust level cannot be determined comm_type is set to PEP_ct_unknown
   753 
   754 DYNAMIC_API PEP_STATUS least_trust(
   755         PEP_SESSION session,
   756         const char *fpr,
   757         PEP_comm_type *comm_type
   758     );
   759 
   760 
   761 // get_key_rating() - get the rating a bare key has
   762 //
   763 //  parameters:
   764 //      session (in)            session handle
   765 //      fpr (in)                unique identifyer for key as UTF-8 string
   766 //      comm_type (out)         key rating
   767 //
   768 //  if an error occurs, *comm_type is set to PEP_ct_unknown and an error
   769 //  is returned
   770 
   771 DYNAMIC_API PEP_STATUS get_key_rating(
   772         PEP_SESSION session,
   773         const char *fpr,
   774         PEP_comm_type *comm_type
   775     );
   776 
   777 
   778 // renew_key() - renew an expired key
   779 //
   780 //  parameters:
   781 //      session (in)            session handle
   782 //      fpr (in)                ID of key to renew as UTF-8 string
   783 //      ts (in)                 timestamp when key should expire or NULL for
   784 //                              default
   785 
   786 DYNAMIC_API PEP_STATUS renew_key(
   787         PEP_SESSION session,
   788         const char *fpr,
   789         const timestamp *ts
   790     );
   791 
   792 
   793 // revoke_key() - revoke a key
   794 //
   795 //  parameters:
   796 //      session (in)            session handle
   797 //      fpr (in)                ID of key to revoke as UTF-8 string
   798 //      reason (in)             text with reason for revoke as UTF-8 string
   799 //                              or NULL if reason unknown
   800 //
   801 //  caveat:
   802 //      reason text must not include empty lines
   803 //      this function is meant for internal use only; better use
   804 //      key_mistrusted() of keymanagement API
   805 
   806 DYNAMIC_API PEP_STATUS revoke_key(
   807         PEP_SESSION session,
   808         const char *fpr,
   809         const char *reason
   810     );
   811 
   812 
   813 // key_expired() - flags if a key is already expired
   814 //
   815 //  parameters:
   816 //      session (in)            session handle
   817 //      fpr (in)                ID of key to check as UTF-8 string
   818 //      when (in)               UTC time of when should expiry be considered
   819 //      expired (out)           flag if key expired
   820 
   821 DYNAMIC_API PEP_STATUS key_expired(
   822         PEP_SESSION session,
   823         const char *fpr,
   824         const time_t when,
   825         bool *expired
   826     );
   827 
   828     
   829 // key_revoked() - flags if a key is already revoked
   830 //
   831 //  parameters:
   832 //      session (in)            session handle
   833 //      fpr (in)                ID of key to check as UTF-8 string
   834 //      revoked (out)           flag if key revoked
   835 
   836 DYNAMIC_API PEP_STATUS key_revoked(
   837         PEP_SESSION session,
   838         const char *fpr,
   839         bool *revoked
   840     );
   841 
   842 
   843 // get_crashdump_log() - get the last log messages out
   844 //
   845 //  parameters:
   846 //      session (in)            session handle
   847 //      maxlines (in)           maximum number of lines (0 for default)
   848 //      logdata (out)           logdata as string in double quoted CSV format
   849 //                              column1 is title
   850 //                              column2 is entity
   851 //                              column3 is description
   852 //                              column4 is comment
   853 //
   854 //  caveat:
   855 //      the ownership of logdata goes to the caller
   856 
   857 DYNAMIC_API PEP_STATUS get_crashdump_log(
   858         PEP_SESSION session,
   859         int maxlines,
   860         char **logdata
   861     );
   862 
   863 
   864 // get_languagelist() - get the list of languages
   865 //
   866 //  parameters:
   867 //      session (in)            session handle
   868 //      languages (out)         languages as string in double quoted CSV format
   869 //                              column 1 is the ISO 639-1 language code
   870 //                              column 2 is the name of the language
   871 //
   872 //  caveat:
   873 //      the ownership of languages goes to the caller
   874 
   875 DYNAMIC_API PEP_STATUS get_languagelist(
   876         PEP_SESSION session,
   877         char **languages
   878     );
   879 
   880 
   881 // get_phrase() - get phrase in a dedicated language through i18n
   882 //
   883 //  parameters:
   884 //      session (in)            session handle
   885 //      lang (in)               C string with ISO 639-1 language code
   886 //      phrase_id (in)          id of phrase in i18n
   887 //      phrase (out)            phrase as UTF-8 string
   888 //
   889 //  caveat:
   890 //      the ownership of phrase goes to the caller
   891 
   892 DYNAMIC_API PEP_STATUS get_phrase(
   893         PEP_SESSION session,
   894         const char *lang,
   895         int phrase_id,
   896         char **phrase
   897     );
   898 
   899 
   900 // sequence_value() - raise the value of a named sequence and retrieve it
   901 //
   902 //  parameters:
   903 //      session (in)            session handle
   904 //      name (inout)            name of sequence or char[37] set to {0, }
   905 //                              for new own sequence named as UUID
   906 //      value (inout)           value of sequence value to test or 0 for
   907 //                              getting next value
   908 //
   909 //  returns:
   910 //      PEP_STATUS_OK                   no error, not own sequence
   911 //      PEP_SEQUENCE_VIOLATED           if sequence violated
   912 //      PEP_CANNOT_INCREASE_SEQUENCE    if sequence cannot be increased
   913 //      PEP_OWN_SEQUENCE                if own sequence
   914 
   915 DYNAMIC_API PEP_STATUS sequence_value(
   916         PEP_SESSION session,
   917         char *name,
   918         int32_t *value
   919     );
   920 
   921 
   922 // set_revoked() - records relation between a revoked key and its replacement
   923 //
   924 //  parameters:
   925 //      session (in)            session handle
   926 //      revoked_fpr (in)        revoked fingerprint
   927 //      replacement_fpr (in)    replacement key fingerprint
   928 //      revocation_date (in)    revocation date
   929 
   930 DYNAMIC_API PEP_STATUS set_revoked(
   931        PEP_SESSION session,
   932        const char *revoked_fpr,
   933        const char *replacement_fpr,
   934        const uint64_t revocation_date
   935     );
   936 
   937 
   938 // get_revoked() - find revoked key that may have been replaced by given key, if any
   939 //
   940 //  parameters:
   941 //      session (in)            session handle
   942 //      fpr (in)                given fingerprint
   943 //      revoked_fpr (out)       revoked fingerprint
   944 //      revocation_date (out)   revocation date
   945     
   946 DYNAMIC_API PEP_STATUS get_revoked(
   947         PEP_SESSION session,
   948         const char *fpr,
   949         char **revoked_fpr,
   950         uint64_t *revocation_date
   951     );
   952 
   953 
   954 // key_created() - get creation date of a key
   955 //
   956 //  parameters:
   957 //      session (in)            session handle
   958 //      fpr (in)                fingerprint of key
   959 //      created (out)           date of creation
   960 
   961 PEP_STATUS key_created(
   962         PEP_SESSION session,
   963         const char *fpr,
   964         time_t *created
   965     );
   966 
   967 
   968 // get_engine_version() - returns the current version of pEpEngine (this is different
   969 //                        from the pEp protocol version!)
   970 //
   971 //  parameters: none
   972 //
   973 //  return_value: const char* to the engine version string constant
   974 //
   975 DYNAMIC_API const char* get_engine_version();
   976 
   977 DYNAMIC_API PEP_STATUS reset_peptest_hack(PEP_SESSION session);
   978 
   979 #ifdef __cplusplus
   980 }
   981 #endif