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