src/pEpEngine.h
author Volker Birk <vb@pep-project.org>
Sat, 20 Feb 2016 14:43:28 +0100
changeset 450 ae04b9c42932
parent 442 e028f6d1d583
child 451 495e53a4b441
permissions -rw-r--r--
adding get_crashdump_log()
     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 "timestamp.h"
    14 
    15 #define PEP_VERSION "1.0"
    16 
    17 // pEp Engine API
    18 
    19 //  caveat:
    20 //      Unicode data has to be normalized to NFC before calling
    21 //      UTF-8 strings are UTF-8 encoded C strings (zero terminated)
    22 
    23 
    24 struct _pEpSession;
    25 typedef struct _pEpSession * PEP_SESSION;
    26 
    27 typedef enum {
    28 	PEP_STATUS_OK									= 0,
    29 
    30 	PEP_INIT_CANNOT_LOAD_GPGME						= 0x0110,
    31 	PEP_INIT_GPGME_INIT_FAILED						= 0x0111,
    32 	PEP_INIT_NO_GPG_HOME							= 0x0112,
    33 	PEP_INIT_NETPGP_INIT_FAILED						= 0x0113,
    34 
    35 	PEP_INIT_SQLITE3_WITHOUT_MUTEX					= 0x0120,
    36 	PEP_INIT_CANNOT_OPEN_DB							= 0x0121,
    37 	PEP_INIT_CANNOT_OPEN_SYSTEM_DB					= 0x0122,
    38 	
    39 	PEP_KEY_NOT_FOUND						        = 0x0201,
    40 	PEP_KEY_HAS_AMBIG_NAME					        = 0x0202,
    41 	PEP_GET_KEY_FAILED						        = 0x0203,
    42 	
    43 	PEP_CANNOT_FIND_IDENTITY						= 0x0301,
    44 	PEP_CANNOT_SET_PERSON							= 0x0381,
    45 	PEP_CANNOT_SET_PGP_KEYPAIR						= 0x0382,
    46 	PEP_CANNOT_SET_IDENTITY							= 0x0383,
    47     PEP_CANNOT_SET_TRUST                            = 0x0384,
    48 	
    49 	PEP_UNENCRYPTED									= 0x0400,
    50 	PEP_VERIFIED									= 0x0401,
    51 	PEP_DECRYPTED									= 0x0402,
    52 	PEP_DECRYPTED_AND_VERIFIED						= 0x0403,
    53 	PEP_DECRYPT_WRONG_FORMAT						= 0x0404,
    54 	PEP_DECRYPT_NO_KEY								= 0x0405,
    55 	PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH			= 0x0406,
    56     PEP_VERIFY_NO_KEY                               = 0x0407,
    57     PEP_VERIFIED_AND_TRUSTED                        = 0x0408,
    58 	PEP_CANNOT_DECRYPT_UNKNOWN						= 0x04ff,
    59 
    60 	PEP_TRUSTWORD_NOT_FOUND							= 0x0501,
    61 
    62     PEP_CANNOT_CREATE_KEY                           = 0x0601,
    63     PEP_CANNOT_SEND_KEY                             = 0x0602,
    64 
    65 	PEP_COMMIT_FAILED								= 0xff01,
    66 
    67     PEP_CANNOT_CREATE_TEMP_FILE                     = -5,
    68     PEP_ILLEGAL_VALUE                               = -4,
    69     PEP_BUFFER_TOO_SMALL                            = -3,
    70 	PEP_OUT_OF_MEMORY								= -2,
    71 	PEP_UNKNOWN_ERROR								= -1
    72 } PEP_STATUS;
    73 
    74 
    75 // INIT_STATUS init() - initialize pEpEngine for a thread
    76 //
    77 //  parameters:
    78 //		session (out)	init() allocates session memory and returns a pointer
    79 //		                as a handle
    80 //
    81 //  return value:
    82 //		PEP_STATUS_OK = 0					if init() succeeds
    83 //		PEP_INIT_SQLITE3_WITHOUT_MUTEX		if SQLite3 was compiled with
    84 //		                                    SQLITE_THREADSAFE 0
    85 //		PEP_INIT_CANNOT_LOAD_GPGME			if libgpgme.dll cannot be found
    86 //		PEP_INIT_GPGME_INIT_FAILED			if GPGME init fails
    87 //		PEP_INIT_CANNOT_OPEN_DB				if user's management db cannot be
    88 //		                                    opened
    89 //		PEP_INIT_CANNOT_OPEN_SYSTEM_DB		if system's management db cannot be
    90 //		                                    opened
    91 //
    92 //  caveat:
    93 //      the pointer is valid only if the return value is PEP_STATUS_OK
    94 //      in other case a NULL pointer will be returned; a valid handle must
    95 //      be released using release() when it's no longer needed
    96 //
    97 //      the caller has to guarantee that the first call to this function
    98 //      will succeed before further calls can be done
    99 
   100 DYNAMIC_API PEP_STATUS init(PEP_SESSION *session);
   101 
   102 
   103 // void release() - release thread session handle
   104 //
   105 //  parameters:
   106 //		session (in)	session handle to release
   107 //
   108 //	caveat:
   109 //	    the last release() can be called only when all other release() calls
   110 //	    are done
   111 
   112 DYNAMIC_API void release(PEP_SESSION session);
   113 
   114 
   115 // decrypt_and_verify() - decrypt and/or verify a message
   116 //
   117 //	parameters:
   118 //		session (in)	session handle
   119 //		ctext (in)		cipher text to decrypt and/or verify
   120 //		csize (in)		size of cipher text
   121 //		ptext (out)		pointer to internal buffer with plain text
   122 //		psize (out)		size of plain text
   123 //		keylist (out)	list of key ids which where used to encrypt
   124 //
   125 //	return value:
   126 //		PEP_UNENCRYPTED				message was unencrypted and not signed
   127 //		PEP_VERIFIED				message was unencrypted, signature matches
   128 //		PEP_DECRYPTED				message is decrypted now, no signature
   129 //		PEP_DECRYPTED_AND_VERIFIED	message is decrypted now and verified
   130 //		PEP_DECRYPT_WRONG_FORMAT	message has wrong format to handle
   131 //		PEP_DECRYPT_NO_KEY			key not available to decrypt and/or verify
   132 //		PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH	wrong signature
   133 //
   134 //	caveat:
   135 //	    the ownerships of ptext as well as keylist are going to the caller
   136 //	    the caller must use free() (or an Windoze pEp_free()) and
   137 //	    free_stringlist() to free them
   138 //
   139 //      if this function failes an error message may be the first element of
   140 //      keylist and the other elements may be the keys used for encryption
   141 
   142 DYNAMIC_API PEP_STATUS decrypt_and_verify(
   143         PEP_SESSION session, const char *ctext, size_t csize,
   144         char **ptext, size_t *psize, stringlist_t **keylist
   145     );
   146 
   147 
   148 // verify_text() - verfy plain text with a digital signature
   149 //
   150 //  parameters:
   151 //      session (in)    session handle
   152 //      text (in)       text to verify
   153 //      size (in)       size of text
   154 //      signature (in)  signature text
   155 //      sig_size (in)   size of signature
   156 //		keylist (out)	list of key ids which where used to encrypt or NULL on
   157 //		                error
   158 //
   159 //  return value:
   160 //		PEP_VERIFIED				message was unencrypted, signature matches
   161 //		PEP_DECRYPT_NO_KEY			key not available to decrypt and/or verify
   162 //		PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH	wrong signature
   163 
   164 DYNAMIC_API PEP_STATUS verify_text(
   165         PEP_SESSION session, const char *text, size_t size,
   166         const char *signature, size_t sig_size, stringlist_t **keylist
   167     );
   168 
   169 
   170 // encrypt_and_sign() - encrypt and sign a message
   171 //
   172 //	parameters:
   173 //		session (in)	session handle
   174 //		keylist (in)	list of key ids to encrypt with as C strings
   175 //		ptext (in)		plain text to decrypt and/or verify
   176 //		psize (in)		size of plain text
   177 //		ctext (out)		pointer to internal buffer with cipher text
   178 //		csize (out)		size of cipher text
   179 //
   180 //	return value:
   181 //		PEP_STATUS_OK = 0				encryption and signing succeeded
   182 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
   183 //		                                could not be found
   184 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
   185 //		                                an ambiguous name
   186 //		PEP_GET_KEY_FAILED		        cannot retrieve key
   187 //
   188 //	caveat:
   189 //	    the ownership of ctext is going to the caller
   190 //      the caller is responsible to free() it (on Windoze use pEp_free())
   191 //      the first key in keylist is being used to sign the message
   192 //      this implies there has to be a private key for that keypair
   193 
   194 DYNAMIC_API PEP_STATUS encrypt_and_sign(
   195         PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
   196         size_t psize, char **ctext, size_t *csize
   197     );
   198 
   199 
   200 // log_event() - log a user defined event defined by UTF-8 encoded strings into
   201 // management log
   202 //
   203 //	parameters:
   204 //		session (in)		session handle
   205 //		title (in)			C string with event name
   206 //		entity (in)			C string with name of entity which is logging
   207 //		description (in)	C string with long description for event or NULL if
   208 //		                    omitted
   209 //		comment (in)		C string with user defined comment or NULL if
   210 //		                    omitted
   211 //
   212 //	return value:
   213 //	    PEP_STATUS_OK       log entry created
   214 
   215 DYNAMIC_API PEP_STATUS log_event(
   216         PEP_SESSION session,
   217         char *title,
   218         char *entity,
   219         char *description,
   220         char *comment
   221     );
   222 
   223 
   224 // trustword() - get the corresponding trustword for a 16 bit value
   225 //
   226 //	parameters:
   227 //		session (in)		    session handle
   228 //		value (in)			    value to find a trustword for
   229 //		lang (in)			    C string with ISO 639-1 language code
   230 //		word (out)			    pointer to C string with trustword UTF-8 encoded
   231 //							    NULL if language is not supported or trustword
   232 //							    wordlist is damaged or unavailable
   233 //		wsize (out)			    length of trustword
   234 //
   235 //	return value:
   236 //	    PEP_STATUS_OK           trustword retrieved
   237 //	    PEP_TRUSTWORD_NOT_FOUND  trustword not found
   238 //
   239 //	caveat:
   240 //		the word pointer goes to the ownership of the caller
   241 //      the caller is responsible to free() it (on Windoze use pEp_free())
   242 
   243 DYNAMIC_API PEP_STATUS trustword(
   244             PEP_SESSION session, uint16_t value, const char *lang,
   245             char **word, size_t *wsize
   246         );
   247 
   248 
   249 // trustwords() - get trustwords for a string of hex values of a fingerprint
   250 //
   251 //	parameters:
   252 //		session (in)		session handle
   253 //		fingerprint (in)	C string with hex values to find trustwords for
   254 //		lang (in)			C string with ISO 639-1 language code
   255 //		words (out)			pointer to C string with trustwords UTF-8 encoded,
   256 //		                    separated by a blank each
   257 //							NULL if language is not supported or trustword
   258 //							wordlist is damaged or unavailable
   259 //		wsize (out)			length of trustwords string
   260 //		max_words (in)		only generate a string with max_words;
   261 //							if max_words == 0 there is no such limit
   262 //
   263 //	return value:
   264 //	    PEP_STATUS_OK           trustwords retrieved
   265 //      PEP_OUT_OF_MEMORY       out of memory
   266 //	    PEP_TRUSTWORD_NOT_FOUND at least one trustword not found
   267 //
   268 //	caveat:
   269 //		the word pointer goes to the ownership of the caller
   270 //      the caller is responsible to free() it (on Windoze use pEp_free())
   271 //
   272 //  DON'T USE THIS FUNCTION FROM HIGH LEVEL LANGUAGES!
   273 //
   274 //  Better implement a simple one in the adapter yourself using trustword(), and
   275 //  return a list of trustwords.
   276 //  This function is provided for being used by C and C++ programs only.
   277 
   278 DYNAMIC_API PEP_STATUS trustwords(
   279         PEP_SESSION session, const char *fingerprint, const char *lang,
   280         char **words, size_t *wsize, int max_words
   281     );
   282 
   283 
   284 typedef enum _PEP_comm_type {
   285     PEP_ct_unknown = 0,
   286 
   287     // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
   288 
   289     PEP_ct_no_encryption = 0x01,                // generic
   290     PEP_ct_no_encrypted_channel = 0x02,
   291     PEP_ct_key_not_found = 0x03,
   292     PEP_ct_key_expired = 0x04,
   293     PEP_ct_key_revoked = 0x05,
   294     PEP_ct_key_b0rken = 0x06,
   295     PEP_ct_my_key_not_included = 0x09,
   296 
   297     PEP_ct_security_by_obscurity = 0x0a,
   298     PEP_ct_b0rken_crypto = 0x0b,
   299     PEP_ct_key_too_short = 0x0c,
   300 
   301     PEP_ct_compromized = 0x0e,                  // known compromized connection
   302     PEP_ct_mistrusted = 0x0f,                   // known mistrusted key
   303 
   304     // range 0x10 to 0x3f: unconfirmed encryption
   305 
   306     PEP_ct_unconfirmed_encryption = 0x10,       // generic
   307     PEP_ct_OpenPGP_weak_unconfirmed = 0x11,	    // RSA 1024 is weak
   308 
   309     PEP_ct_to_be_checked = 0x20,                // generic
   310     PEP_ct_SMIME_unconfirmed = 0x21,
   311     PEP_ct_CMS_unconfirmed = 0x22,
   312 
   313     PEP_ct_strong_but_unconfirmed = 0x30,       // generic
   314     PEP_ct_OpenPGP_unconfirmed = 0x38,          // key at least 2048 bit RSA or EC
   315     PEP_ct_OTR_unconfirmed = 0x3a,
   316 
   317     // range 0x40 to 0x7f: unconfirmed encryption and anonymization
   318 
   319     PEP_ct_unconfirmed_enc_anon = 0x40,         // generic
   320     PEP_ct_PEP_unconfirmed = 0x7f,
   321 
   322     PEP_ct_confirmed = 0x80,                    // this bit decides if trust is confirmed
   323 
   324     // range 0x81 to 0x8f: reserved
   325     // range 0x90 to 0xbf: confirmed encryption
   326 
   327     PEP_ct_confirmed_encryption = 0x90,         // generic
   328 	PEP_ct_OpenPGP_weak = 0x91,                 // RSA 1024 is weak
   329 
   330     PEP_ct_to_be_checked_confirmed = 0xa0,      //generic
   331     PEP_ct_SMIME = 0xa1,
   332     PEP_ct_CMS = 0xa2,
   333 
   334     PEP_ct_strong_encryption = 0xb0,            // generic
   335 	PEP_ct_OpenPGP = 0xb8,                      // key at least 2048 bit RSA or EC
   336 	PEP_ct_OTR = 0xba,
   337 
   338     // range 0xc0 to 0xff: confirmed encryption and anonymization
   339 
   340     PEP_ct_confirmed_enc_anon = 0xc0,           // generic
   341 	PEP_ct_pEp = 0xff
   342 } PEP_comm_type;
   343 
   344 typedef struct _pEp_identity {
   345 	size_t struct_size;			// size of whole struct
   346 	char *address;		        // C string with address UTF-8 encoded
   347 	size_t address_size;		// size of address
   348 	char *fpr;			        // C string with fingerprint UTF-8 encoded
   349 	size_t fpr_size;			// size of fingerprint
   350 	char *user_id;		        // C string with user ID UTF-8 encoded
   351 	size_t user_id_size;		// size of user ID
   352 	char *username;		        // C string with user name UTF-8 encoded
   353 	size_t username_size;		// size of user name
   354 	PEP_comm_type comm_type;	// type of communication with this ID
   355     char lang[3];				// language of conversation
   356                                 // ISO 639-1 ALPHA-2, last byte is 0
   357     bool me;                    // if this is the local user herself/himself
   358 } pEp_identity;
   359 
   360 
   361 // new_identity() - allocate memory and set the string and size fields
   362 //
   363 //  parameters:
   364 //      address (in)        UTF-8 string or NULL 
   365 //      fpr (in)            UTF-8 string or NULL 
   366 //      user_id (in)        UTF-8 string or NULL 
   367 //      username (in)       UTF-8 string or NULL 
   368 //
   369 //  return value:
   370 //      pEp_identity struct with correct size values or NULL if out of memory
   371 //
   372 //  caveat:
   373 //      the strings are copied; the original strings are still being owned by
   374 //      the caller
   375 
   376 DYNAMIC_API pEp_identity *new_identity(
   377         const char *address, const char *fpr, const char *user_id,
   378         const char *username
   379     );
   380 
   381 
   382 // identity_dup() - allocate memory and set the string and size fields
   383 //
   384 //  parameters:
   385 //      src (in)            identity to duplicate
   386 //
   387 //  return value:
   388 //      pEp_identity struct with correct size values or NULL if out of memory
   389 //
   390 //  caveat:
   391 //      the strings are copied; the original strings are still being owned by
   392 //      the caller
   393 
   394 DYNAMIC_API pEp_identity *identity_dup(const pEp_identity *src);
   395 
   396 
   397 // free_identity() - free all memory being occupied by a pEp_identity struct
   398 //
   399 //  parameters:
   400 //      identity (in)       struct to release
   401 //
   402 //  caveat:
   403 //      not only the struct but also all string memory referenced by the
   404 //      struct is being freed; all pointers inside are invalid afterwards
   405 
   406 DYNAMIC_API void free_identity(pEp_identity *identity);
   407 
   408 
   409 // get_identity() - get identity information
   410 //
   411 //	parameters:
   412 //		session (in)		session handle
   413 //		address (in)		C string with communication address, UTF-8 encoded
   414 //		identity (out)		pointer to pEp_identity structure with results or
   415 //		                    NULL if failure
   416 //
   417 //	caveat:
   418 //	    the address string is being copied; the original string remains in the
   419 //	    ownership of the caller
   420 //		the resulting pEp_identity structure goes to the ownership of the
   421 //		caller and has to be freed with free_identity() when not in use any
   422 //		more
   423 
   424 DYNAMIC_API PEP_STATUS get_identity(
   425         PEP_SESSION session, const char *address,
   426         pEp_identity **identity
   427     );
   428 
   429 
   430 // set_identity() - set identity information
   431 //
   432 //	parameters:
   433 //		session (in)		session handle
   434 //		identity (in)		pointer to pEp_identity structure
   435 //
   436 //	return value:
   437 //		PEP_STATUS_OK = 0			    encryption and signing succeeded
   438 //		PEP_CANNOT_SET_PERSON		    writing to table person failed
   439 //		PEP_CANNOT_SET_PGP_KEYPAIR	    writing to table pgp_keypair failed
   440 //		PEP_CANNOT_SET_IDENTITY		    writing to table identity failed
   441 //		PEP_COMMIT_FAILED			    SQL commit failed
   442 //
   443 //	caveat:
   444 //		in the identity structure you need to set the const char * fields to
   445 //		UTF-8 C strings
   446 //		the size fields are ignored
   447 
   448 DYNAMIC_API PEP_STATUS set_identity(
   449         PEP_SESSION session, const pEp_identity *identity
   450     );
   451 
   452 
   453 // mark_as_compromized() - mark key in trust db as compromized
   454 //
   455 //	parameters:
   456 //		session (in)		session handle
   457 //		fpr (in)            fingerprint of key to mark
   458 
   459 DYNAMIC_API PEP_STATUS mark_as_compromized(
   460         PEP_SESSION session,
   461         const char *fpr
   462     );
   463 
   464 
   465 // generate_keypair() - generate a new key pair and add it to the key ring
   466 //
   467 //  parameters:
   468 //      session (in)            session handle
   469 //		identity (inout)	    pointer to pEp_identity structure
   470 //
   471 //	return value:
   472 //		PEP_STATUS_OK = 0	    encryption and signing succeeded
   473 //		PEP_ILLEGAL_VALUE       illegal values for identity fields given
   474 //		PEP_CANNOT_CREATE_KEY   key engine is on strike
   475 //
   476 //  caveat:
   477 //      address and username fields must be set to UTF-8 strings
   478 //      the fpr field must be set to NULL
   479 //
   480 //      this function allocates a string and sets set fpr field of identity
   481 //      the caller is responsible to call free() for that string or use
   482 //      free_identity() on the struct
   483 
   484 DYNAMIC_API PEP_STATUS generate_keypair(
   485         PEP_SESSION session, pEp_identity *identity
   486     );
   487 
   488 
   489 // delete_keypair() - delete a public key or a key pair from the key ring
   490 //
   491 //  parameters:
   492 //      session (in)            session handle
   493 //      fpr (in)                C string with key id or fingerprint of the
   494 //                              public key
   495 //
   496 //  return value:
   497 //      PEP_STATUS_OK = 0       key was successfully deleted
   498 //      PEP_KEY_NOT_FOUND       key not found
   499 //      PEP_ILLEGAL_VALUE       not a valid key id or fingerprint
   500 //      PEP_KEY_HAS_AMBIG_NAME  fpr does not uniquely identify a key
   501 //      PEP_OUT_OF_MEMORY       out of memory
   502 
   503 DYNAMIC_API PEP_STATUS delete_keypair(PEP_SESSION session, const char *fpr);
   504 
   505 
   506 // import_key() - import key from data
   507 //
   508 //  parameters:
   509 //      session (in)            session handle
   510 //      key_data (in)           key data, i.e. ASCII armored OpenPGP key
   511 //      size (in)               amount of data to handle
   512 //
   513 //  return value:
   514 //      PEP_STATUS_OK = 0       key was successfully imported
   515 //      PEP_OUT_OF_MEMORY       out of memory
   516 //      PEP_ILLEGAL_VALUE       there is no key data to import
   517 
   518 DYNAMIC_API PEP_STATUS import_key(PEP_SESSION session, const char *key_data, size_t size);
   519 
   520 
   521 // export_key() - export ascii armored key
   522 //
   523 //  parameters:
   524 //      session (in)            session handle
   525 //      fpr (in)                key id or fingerprint of key
   526 //      key_data (out)          ASCII armored OpenPGP key
   527 //      size (out)               amount of data to handle
   528 //
   529 //  return value:
   530 //      PEP_STATUS_OK = 0       key was successfully exported
   531 //      PEP_OUT_OF_MEMORY       out of memory
   532 //      PEP_KEY_NOT_FOUND       key not found
   533 //
   534 //  caveat:
   535 //      the key_data goes to the ownership of the caller
   536 //      the caller is responsible to free() it (on Windoze use pEp_free())
   537 
   538 DYNAMIC_API PEP_STATUS export_key(
   539         PEP_SESSION session, const char *fpr, char **key_data, size_t *size
   540     );
   541 
   542 
   543 // recv_key() - update key(s) from keyserver
   544 //
   545 //  parameters:
   546 //      session (in)            session handle
   547 //      pattern (in)            key id, user id or address to search for as
   548 //                              UTF-8 string
   549 
   550 DYNAMIC_API PEP_STATUS recv_key(PEP_SESSION session, const char *pattern);
   551 
   552 
   553 // find_keys() - find keys in keyring
   554 //
   555 //  parameters:
   556 //      session (in)            session handle
   557 //      pattern (in)            key id, user id or address to search for as
   558 //                              UTF-8 string
   559 //      keylist (out)           list of fingerprints found or NULL on error
   560 //
   561 //  caveat:
   562 //	    the ownerships of keylist isgoing to the caller
   563 //	    the caller must use free_stringlist() to free it
   564 
   565 
   566 DYNAMIC_API PEP_STATUS find_keys(
   567         PEP_SESSION session, const char *pattern, stringlist_t **keylist
   568     );
   569 
   570 
   571 // send_key() - send key(s) to keyserver
   572 //
   573 //  parameters:
   574 //      session (in)            session handle
   575 //      pattern (in)            key id, user id or address to search for as
   576 //                              UTF-8 string
   577 
   578 DYNAMIC_API PEP_STATUS send_key(PEP_SESSION session, const char *pattern);
   579 
   580 
   581 // pEp_free() - free memory allocated by pEp engine
   582 //
   583 //  parameters:
   584 //      p (in)                  pointer to free
   585 //
   586 //  The reason for this function is that heap management can be a pretty
   587 //  complex task with Windoze. This free() version calls the free()
   588 //  implementation of the C runtime library which was used to build pEp engine,
   589 //  so you're using the correct heap. For more information, see:
   590 //  <http://msdn.microsoft.com/en-us/library/windows/desktop/aa366711(v=vs.85).aspx>
   591 
   592 DYNAMIC_API void pEp_free(void *p);
   593 
   594 
   595 // get_trust() - get the trust level a key has for a person
   596 //
   597 //  parameters:
   598 //      session (in)            session handle
   599 //      identity (inout)        user_id and fpr to check as UTF-8 strings (in)
   600 //                              user_id and comm_type as result (out)
   601 //
   602 //  this function modifies the given identity struct; the struct remains in
   603 //  the ownership of the caller
   604 //  if the trust level cannot be determined identity->comm_type is set
   605 //  to PEP_ct_unknown
   606 
   607 DYNAMIC_API PEP_STATUS get_trust(PEP_SESSION session, pEp_identity *identity);
   608 
   609 
   610 // least_trust() - get the least known trust level for a key in the database
   611 //
   612 //  parameters:
   613 //      session (in)            session handle
   614 //      fpr (in)                fingerprint of key to check
   615 //      comm_type (out)         least comm_type as result (out)
   616 //
   617 //  if the trust level cannot be determined comm_type is set to PEP_ct_unknown
   618 
   619 DYNAMIC_API PEP_STATUS least_trust(
   620         PEP_SESSION session,
   621         const char *fpr,
   622         PEP_comm_type *comm_type
   623     );
   624 
   625 
   626 // get_key_rating() - get the rating a bare key has
   627 //
   628 //  parameters:
   629 //      session (in)            session handle
   630 //      fpr (in)                unique identifyer for key as UTF-8 string
   631 //      comm_type (out)         key rating
   632 //
   633 //  if an error occurs, *comm_type is set to PEP_ct_unknown and an error
   634 //  is returned
   635 
   636 DYNAMIC_API PEP_STATUS get_key_rating(
   637         PEP_SESSION session,
   638         const char *fpr,
   639         PEP_comm_type *comm_type
   640     );
   641 
   642 
   643 // renew_key() - renew an expired key
   644 //
   645 //  parameters:
   646 //      session (in)            session handle
   647 //      fpr (in)                ID of key to renew as UTF-8 string
   648 //      ts (in)                 timestamp when key should expire or NULL for
   649 //                              default
   650 
   651 DYNAMIC_API PEP_STATUS renew_key(
   652         PEP_SESSION session,
   653         const char *fpr,
   654         const timestamp *ts
   655     );
   656 
   657 
   658 // revoke_key() - revoke a key
   659 //
   660 //  parameters:
   661 //      session (in)            session handle
   662 //      fpr (in)                ID of key to revoke as UTF-8 string
   663 //      reason (in)             text with reason for revoke as UTF-8 string
   664 //                              or NULL if reason unknown
   665 //
   666 //  caveat:
   667 //      reason text must not include empty lines
   668 //      this function is meant for internal use only; better use
   669 //      key_compromized() of keymanagement API
   670 
   671 DYNAMIC_API PEP_STATUS revoke_key(
   672         PEP_SESSION session,
   673         const char *fpr,
   674         const char *reason
   675     );
   676 
   677 
   678 // key_expired() - flags if a key is already expired
   679 //
   680 //  parameters:
   681 //      session (in)            session handle
   682 //      fpr (in)                ID of key to check as UTF-8 string
   683 //      expired (out)           flag if key expired
   684 
   685 DYNAMIC_API PEP_STATUS key_expired(
   686         PEP_SESSION session,
   687         const char *fpr,
   688         bool *expired
   689     );
   690 
   691 
   692 // get_crashdump_log() - get the last log messages out
   693 //
   694 //  parameters:
   695 //      session (in)            session handle
   696 //      maxlines (in)           maximum number of lines (0 for default)
   697 //      logdata (out)           logdata
   698 
   699 DYNAMIC_API PEP_STATUS get_crashdump_log(
   700         PEP_SESSION session,
   701         int maxlines,
   702         char **logdata
   703     );
   704 
   705 
   706 #ifdef __cplusplus
   707 }
   708 #endif