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