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