You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

2251 lines
69 KiB

8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
6 years ago
6 years ago
6 years ago
6 years ago
4 years ago
6 years ago
8 years ago
6 years ago
8 years ago
8 years ago
8 years ago
8 years ago
4 years ago
4 years ago
4 years ago
3 years ago
8 years ago
4 years ago
4 years ago
8 years ago
8 years ago
7 years ago
7 years ago
7 years ago
7 years ago
3 years ago
8 years ago
6 years ago
8 years ago
8 years ago
8 years ago
3 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
6 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
7 years ago
8 years ago
8 years ago
6 years ago
8 years ago
8 years ago
7 years ago
7 years ago
8 years ago
8 years ago
6 years ago
6 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
7 years ago
7 years ago
7 years ago
7 years ago
6 years ago
6 years ago
3 years ago
4 years ago
4 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
8 years ago
  1. /**
  2. * @file pEpEngine.h
  3. * @brief pEp Engine API, as well as exposed internal functions and structures. (The latter should probably be factored out at some point)
  4. * @license GNU General Public License 3.0 - see LICENSE.txt
  5. */
  6. #pragma once
  7. #ifdef __cplusplus
  8. extern "C" {
  9. #endif
  10. #include <stddef.h>
  11. #include <stdint.h>
  12. #include <stdbool.h>
  13. #include "dynamic_api.h"
  14. #include "stringlist.h"
  15. #include "stringpair.h"
  16. #include "labeled_int_list.h"
  17. #include "timestamp.h"
  18. #define PEP_VERSION "2.1" // pEp *protocol* version
  19. // RELEASE version this targets
  20. // (string: major.minor.patch)
  21. #define PEP_ENGINE_VERSION "2.1.0"
  22. #define PEP_ENGINE_VERSION_MAJOR 2
  23. #define PEP_ENGINE_VERSION_MINOR 1
  24. #define PEP_ENGINE_VERSION_PATCH 0
  25. #define PEP_ENGINE_VERSION_RC 29
  26. #define PEP_OWN_USERID "pEp_own_userId"
  27. // pEp Engine API
  28. // caveat:
  29. // Unicode data has to be normalized to NFC before calling
  30. // UTF-8 strings are UTF-8 encoded C strings (zero terminated)
  31. struct _pEpSession;
  32. typedef struct _pEpSession * PEP_SESSION;
  33. /**
  34. * @enum PEP_STATUS
  35. *
  36. * @brief TODO
  37. *
  38. */
  39. typedef enum {
  40. PEP_STATUS_OK = 0,
  41. PEP_INIT_CANNOT_LOAD_CRYPTO_LIB = 0x0110,
  42. PEP_INIT_CRYPTO_LIB_INIT_FAILED = 0x0111,
  43. PEP_INIT_NO_CRYPTO_HOME = 0x0112,
  44. // PEP_INIT_NETPGP_INIT_FAILED = 0x0113,
  45. PEP_INIT_CANNOT_DETERMINE_CRYPTO_VERSION = 0x0114,
  46. PEP_INIT_UNSUPPORTED_CRYPTO_VERSION = 0x0115,
  47. PEP_INIT_CANNOT_CONFIG_CRYPTO_AGENT = 0x0116,
  48. PEP_INIT_SQLITE3_WITHOUT_MUTEX = 0x0120,
  49. PEP_INIT_CANNOT_OPEN_DB = 0x0121,
  50. PEP_INIT_CANNOT_OPEN_SYSTEM_DB = 0x0122,
  51. PEP_INIT_DB_DOWNGRADE_VIOLATION = 0x0123,
  52. PEP_UNKNOWN_DB_ERROR = 0x01ff,
  53. PEP_KEY_NOT_FOUND = 0x0201,
  54. PEP_KEY_HAS_AMBIG_NAME = 0x0202,
  55. PEP_GET_KEY_FAILED = 0x0203,
  56. PEP_CANNOT_EXPORT_KEY = 0x0204,
  57. PEP_CANNOT_EDIT_KEY = 0x0205,
  58. PEP_KEY_UNSUITABLE = 0x0206,
  59. PEP_MALFORMED_KEY_RESET_MSG = 0x0210,
  60. PEP_KEY_NOT_RESET = 0x0211,
  61. PEP_CANNOT_DELETE_KEY = 0x0212,
  62. PEP_KEY_IMPORTED = 0x0220,
  63. PEP_NO_KEY_IMPORTED = 0x0221,
  64. PEP_KEY_IMPORT_STATUS_UNKNOWN = 0x0222,
  65. PEP_SOME_KEYS_IMPORTED = 0x0223,
  66. PEP_CANNOT_FIND_IDENTITY = 0x0301,
  67. PEP_CANNOT_SET_PERSON = 0x0381,
  68. PEP_CANNOT_SET_PGP_KEYPAIR = 0x0382,
  69. PEP_CANNOT_SET_IDENTITY = 0x0383,
  70. PEP_CANNOT_SET_TRUST = 0x0384,
  71. PEP_KEY_BLACKLISTED = 0x0385,
  72. PEP_CANNOT_FIND_PERSON = 0x0386,
  73. PEP_CANNOT_SET_PEP_VERSION = 0X0387,
  74. PEP_CANNOT_FIND_ALIAS = 0x0391,
  75. PEP_CANNOT_SET_ALIAS = 0x0392,
  76. PEP_UNENCRYPTED = 0x0400,
  77. PEP_VERIFIED = 0x0401,
  78. PEP_DECRYPTED = 0x0402,
  79. PEP_DECRYPTED_AND_VERIFIED = 0x0403,
  80. PEP_DECRYPT_WRONG_FORMAT = 0x0404,
  81. PEP_DECRYPT_NO_KEY = 0x0405,
  82. PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH = 0x0406,
  83. PEP_VERIFY_NO_KEY = 0x0407,
  84. PEP_VERIFIED_AND_TRUSTED = 0x0408,
  85. PEP_CANNOT_REENCRYPT = 0x0409,
  86. PEP_VERIFY_SIGNER_KEY_REVOKED = 0x040a,
  87. PEP_CANNOT_DECRYPT_UNKNOWN = 0x04ff,
  88. PEP_TRUSTWORD_NOT_FOUND = 0x0501,
  89. PEP_TRUSTWORDS_FPR_WRONG_LENGTH = 0x0502,
  90. PEP_TRUSTWORDS_DUPLICATE_FPR = 0x0503,
  91. PEP_CANNOT_CREATE_KEY = 0x0601,
  92. PEP_CANNOT_SEND_KEY = 0x0602,
  93. PEP_PHRASE_NOT_FOUND = 0x0701,
  94. PEP_SEND_FUNCTION_NOT_REGISTERED = 0x0801,
  95. PEP_CONTRAINTS_VIOLATED = 0x0802,
  96. PEP_CANNOT_ENCODE = 0x0803,
  97. PEP_SYNC_NO_NOTIFY_CALLBACK = 0x0901,
  98. PEP_SYNC_ILLEGAL_MESSAGE = 0x0902,
  99. PEP_SYNC_NO_INJECT_CALLBACK = 0x0903,
  100. PEP_SYNC_NO_CHANNEL = 0x0904,
  101. PEP_SYNC_CANNOT_ENCRYPT = 0x0905,
  102. PEP_SYNC_NO_MESSAGE_SEND_CALLBACK = 0x0906,
  103. PEP_SYNC_CANNOT_START = 0x0907,
  104. PEP_CANNOT_INCREASE_SEQUENCE = 0x0971,
  105. PEP_STATEMACHINE_ERROR = 0x0980,
  106. PEP_NO_TRUST = 0x0981,
  107. PEP_STATEMACHINE_INVALID_STATE = 0x0982,
  108. PEP_STATEMACHINE_INVALID_EVENT = 0x0983,
  109. PEP_STATEMACHINE_INVALID_CONDITION = 0x0984,
  110. PEP_STATEMACHINE_INVALID_ACTION = 0x0985,
  111. PEP_STATEMACHINE_INHIBITED_EVENT = 0x0986,
  112. PEP_STATEMACHINE_CANNOT_SEND = 0x0987,
  113. PEP_PASSPHRASE_REQUIRED = 0x0a00,
  114. PEP_WRONG_PASSPHRASE = 0x0a01,
  115. PEP_PASSPHRASE_FOR_NEW_KEYS_REQUIRED = 0x0a02,
  116. PEP_DISTRIBUTION_ILLEGAL_MESSAGE = 0x1002,
  117. PEP_COMMIT_FAILED = 0xff01,
  118. PEP_MESSAGE_CONSUME = 0xff02,
  119. PEP_MESSAGE_IGNORE = 0xff03,
  120. PEP_CANNOT_CONFIG = 0xff04,
  121. PEP_RECORD_NOT_FOUND = -6,
  122. PEP_CANNOT_CREATE_TEMP_FILE = -5,
  123. PEP_ILLEGAL_VALUE = -4,
  124. PEP_BUFFER_TOO_SMALL = -3,
  125. PEP_OUT_OF_MEMORY = -2,
  126. PEP_UNKNOWN_ERROR = -1,
  127. PEP_VERSION_MISMATCH = -7,
  128. } PEP_STATUS;
  129. /**
  130. * @enum PEP_enc_format
  131. *
  132. * @brief TODO
  133. *
  134. */
  135. typedef enum _PEP_enc_format {
  136. PEP_enc_none = 0, // message is not encrypted
  137. PEP_enc_pieces = 1, // inline PGP + PGP extensions, was removed
  138. PEP_enc_inline = 1, // still there
  139. PEP_enc_S_MIME, // RFC5751
  140. PEP_enc_PGP_MIME, // RFC3156
  141. PEP_enc_PEP, // pEp encryption format
  142. PEP_enc_PGP_MIME_Outlook1, // Message B0rken by Outlook type 1
  143. PEP_enc_inline_EA,
  144. PEP_enc_auto = 255 // figure out automatically where possible
  145. } PEP_enc_format;
  146. /**
  147. * <!-- messageToSend() -->
  148. *
  149. * @brief A message needs to be delivered by application
  150. *
  151. * @param[in] msg message struct with message to send
  152. *
  153. * @retval PEP_STATUS_OK or any other value on error
  154. *
  155. * @warning the ownership of msg goes to the callee
  156. *
  157. */
  158. struct _message;
  159. typedef PEP_STATUS (*messageToSend_t)(struct _message *msg);
  160. struct Sync_event;
  161. typedef struct Sync_event *SYNC_EVENT;
  162. /**
  163. * <!-- free_Sync_event() -->
  164. *
  165. * @brief Free memory occupied by sync protocol message
  166. *
  167. * @param[in] ev event to free
  168. *
  169. *
  170. */
  171. DYNAMIC_API void free_Sync_event(SYNC_EVENT ev);
  172. /**
  173. * <!-- inject_sync_event() -->
  174. *
  175. * @brief Inject sync protocol message
  176. *
  177. * @param[in] ev event to inject
  178. * @param[in] management application defined; usually a locked queue
  179. *
  180. * @retval 0 if event could be stored successfully
  181. * @retval nonzero otherwise
  182. *
  183. * @warning if ev is SHUTDOWN then the implementation has to be synchronous
  184. * and the shutdown must be immediate
  185. *
  186. */
  187. typedef int (*inject_sync_event_t)(SYNC_EVENT ev, void *management);
  188. /**
  189. * <!-- ensure_passphrase() -->
  190. *
  191. * @brief Callee ensures correct password for (signing) key is configured in the session on
  192. * return, or returns error when it is not found
  193. *
  194. * @param[in] fpr fpr to check
  195. *
  196. * @retval PEP_STATUS_OK passphrase is configured and ready to use
  197. * @retval PEP_PASSPHRASE* If the caller runs out of passphrases to try, PEP_*PASSWORD* errors
  198. * are acceptable.
  199. * @retval **ERROR** Other errors if, for example, the key is not found
  200. * @warning The callee is responsible for iterating through passwords
  201. * to ensure signing/encryption can occur successfully.
  202. *
  203. */
  204. typedef PEP_STATUS (*ensure_passphrase_t)(PEP_SESSION session, const char* fpr);
  205. /**
  206. * <!-- init() -->
  207. *
  208. * @brief Initialize pEpEngine for a thread
  209. *
  210. * @param[out] session init() allocates session memory and
  211. * returns a pointer as a handle
  212. * @param[in] messageToSend callback for sending message by the
  213. * application
  214. * @param[in] inject_sync_event callback for injecting a sync event
  215. * @param[in] ensure_passphrase callback for ensuring correct password for key is set
  216. *
  217. * @retval PEP_STATUS_OK if init() succeeds
  218. * @retval PEP_INIT_SQLITE3_WITHOUT_MUTEX if SQLite3 was compiled with
  219. * SQLITE_THREADSAFE 0
  220. * @retval PEP_INIT_CANNOT_LOAD_CRYPTO_LIB if crypto lin cannot be found
  221. * @retval PEP_INIT_CRYPTO_LIB_INIT_FAILED if CRYPTO_LIB init fails
  222. * @retval PEP_INIT_CANNOT_OPEN_DB if user's management db cannot be
  223. * opened
  224. * @retval PEP_INIT_CANNOT_OPEN_SYSTEM_DB if system's management db cannot be
  225. * opened
  226. *
  227. * @warning THE CALLER MUST GUARD THIS CALL EXTERNALLY WITH A MUTEX. release()
  228. * should be similarly guarded.
  229. *
  230. * @warning the pointer is valid only if the return value is PEP_STATUS_OK
  231. * in other case a NULL pointer will be returned; a valid handle must
  232. * be released using release() when it's no longer needed
  233. *
  234. * @warning the caller has to guarantee that the first call to this function
  235. * will succeed before further calls can be done
  236. * messageToSend can only be null if no transport is application based
  237. * if transport system is not used it must not be NULL
  238. *
  239. * @warning ensure_refresh_key should only be NULL if the
  240. * caller can guarantee that there is only one single or zero passphrases
  241. * used in the whole of the keys database
  242. *
  243. */
  244. DYNAMIC_API PEP_STATUS init(
  245. PEP_SESSION *session,
  246. messageToSend_t messageToSend,
  247. inject_sync_event_t inject_sync_event,
  248. ensure_passphrase_t ensure_passphrase
  249. );
  250. /**
  251. * <!-- release() -->
  252. *
  253. * @brief Release thread session handle
  254. *
  255. * @param[in] session session handle to release
  256. *
  257. * @warning THE CALLER MUST GUARD THIS CALL EXTERNALLY WITH A MUTEX. init() should
  258. * be similarly guarded.
  259. *
  260. * @warning the last release() can be called only when all other release() calls
  261. * are done
  262. *
  263. */
  264. DYNAMIC_API void release(PEP_SESSION session);
  265. /**
  266. * <!-- config_passive_mode() -->
  267. *
  268. * @brief Enable passive mode
  269. *
  270. * @param[in] session session handle
  271. * @param[in] enable flag if enabled or disabled
  272. *
  273. *
  274. */
  275. DYNAMIC_API void config_passive_mode(PEP_SESSION session, bool enable);
  276. /**
  277. * <!-- config_unencrypted_subject() -->
  278. *
  279. * @brief Disable subject encryption
  280. *
  281. * @param[in] session session handle
  282. * @param[in] enable flag if enabled or disabled
  283. *
  284. *
  285. */
  286. DYNAMIC_API void config_unencrypted_subject(PEP_SESSION session, bool enable);
  287. /**
  288. * <!-- config_use_only_own_private_keys() -->
  289. *
  290. * @brief Enable passive mode
  291. *
  292. * @param[in] session session handle
  293. * @param[in] enable flag if enabled or disabled
  294. *
  295. *
  296. */
  297. DYNAMIC_API void config_use_only_own_private_keys(PEP_SESSION session, bool enable);
  298. /**
  299. * <!-- config_service_log() -->
  300. *
  301. * @brief Log more for service purposes
  302. *
  303. * session (in) session handle
  304. * enable (in) flag if enabled or disabled
  305. *
  306. *
  307. */
  308. DYNAMIC_API void config_service_log(PEP_SESSION session, bool enable);
  309. /**
  310. * @enum PEP_CIPHER_SUITE
  311. *
  312. * @brief TODO
  313. *
  314. */
  315. typedef enum {
  316. PEP_CIPHER_SUITE_DEFAULT = 0,
  317. PEP_CIPHER_SUITE_CV25519 = 1,
  318. PEP_CIPHER_SUITE_P256 = 2,
  319. PEP_CIPHER_SUITE_P384 = 3,
  320. PEP_CIPHER_SUITE_P521 = 4,
  321. PEP_CIPHER_SUITE_RSA2K = 5,
  322. PEP_CIPHER_SUITE_RSA3K = 6,
  323. PEP_CIPHER_SUITE_RSA4K = 7,
  324. PEP_CIPHER_SUITE_RSA8K = 8
  325. } PEP_CIPHER_SUITE;
  326. /**
  327. * <!-- config_cipher_suite() -->
  328. *
  329. * @brief Cipher suite being used when encrypting
  330. *
  331. * @param[in] session session handle
  332. * @param[in] cipher_suite cipher suite to use
  333. *
  334. * @retval PEP_STATUS_OK cipher suite configured
  335. * @retval PEP_CANNOT_CONFIG configuration failed; falling back to default
  336. *
  337. * @warning the default ciphersuite for a crypt tech implementation is implementation defined
  338. *
  339. */
  340. DYNAMIC_API PEP_STATUS config_cipher_suite(PEP_SESSION session,
  341. PEP_CIPHER_SUITE suite);
  342. /**
  343. * <!-- decrypt_and_verify() -->
  344. *
  345. * @brief Decrypt and/or verify a message
  346. *
  347. * @param[in] session session handle
  348. * @param[in] ctext cipher text to decrypt and/or verify
  349. * @param[in] csize size of cipher text
  350. * @param[in] dsigtext if extant, *detached* signature text for this
  351. * message (or NULL if not)
  352. * @param[in] dsize size of *detached* signature text for this
  353. * message (0, if no detached sig exists)
  354. * @param[out] ptext pointer to internal buffer with plain text
  355. * @param[out] psize size of plain text
  356. * @param[out] keylist list of key ids which where used to encrypt
  357. * @param[out] filename_ptr mails produced by certain PGP implementations
  358. * may return a decrypted filename here for attachments.
  359. * Externally, this can generally be NULL, and is an optional
  360. * parameter.
  361. *
  362. * @retval PEP_UNENCRYPTED message was unencrypted and not signed
  363. * @retval PEP_VERIFIED message was unencrypted, signature matches
  364. * @retval PEP_DECRYPTED message is decrypted now, no signature
  365. * @retval PEP_DECRYPTED_AND_VERIFIED message is decrypted now and verified
  366. * @retval PEP_DECRYPT_WRONG_FORMAT message has wrong format to handle
  367. * @retval PEP_DECRYPT_NO_KEY key not available to decrypt and/or verify
  368. * @retval PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH wrong signature
  369. *
  370. * @warning the ownerships of ptext as well as keylist are going to the caller
  371. * the caller must use free() (or an Windoze pEp_free()) and
  372. * free_stringlist() to free them
  373. *
  374. * @note if this function fails an error message may be the first element of
  375. * keylist and the other elements may be the keys used for encryption
  376. *
  377. */
  378. DYNAMIC_API PEP_STATUS decrypt_and_verify(
  379. PEP_SESSION session, const char *ctext, size_t csize,
  380. const char *dsigtext, size_t dsigsize,
  381. char **ptext, size_t *psize, stringlist_t **keylist,
  382. char ** filename_ptr
  383. );
  384. /**
  385. * <!-- verify_text() -->
  386. *
  387. * @brief Verfy plain text with a digital signature
  388. *
  389. * @param[in] session session handle
  390. * @param[in] text text to verify
  391. * @param[in] size size of text
  392. * @param[in] signature signature text
  393. * @param[in] sig_size size of signature
  394. * @param[out] keylist list of key ids which where used to encrypt or NULL on
  395. * error
  396. *
  397. * @retval PEP_VERIFIED message was unencrypted, signature matches
  398. * @retval PEP_DECRYPT_NO_KEY key not available to decrypt and/or verify
  399. * @retval PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH wrong signature
  400. *
  401. *
  402. */
  403. DYNAMIC_API PEP_STATUS verify_text(
  404. PEP_SESSION session, const char *text, size_t size,
  405. const char *signature, size_t sig_size, stringlist_t **keylist
  406. );
  407. /**
  408. * <!-- encrypt_and_sign() -->
  409. *
  410. * @brief Encrypt and sign a message
  411. *
  412. * @param[in] session session handle
  413. * @param[in] keylist list of key ids to encrypt with as C strings
  414. * @param[in] ptext plain text to decrypt and/or verify
  415. * @param[in] psize size of plain text
  416. * @param[out] ctext pointer to internal buffer with cipher text
  417. * @param[out] csize size of cipher text
  418. *
  419. * @retval PEP_STATUS_OK encryption and signing succeeded
  420. * @retval PEP_KEY_NOT_FOUND at least one of the recipient keys
  421. * could not be found
  422. * @retval PEP_KEY_HAS_AMBIG_NAME at least one of the recipient keys has
  423. * an ambiguous name
  424. * @retval PEP_GET_KEY_FAILED cannot retrieve key
  425. *
  426. * @warning the ownership of ctext goes to the caller
  427. * the caller is responsible to free() it (on Windoze use pEp_free())
  428. * the first key in keylist is being used to sign the message
  429. * this implies there has to be a private key for that keypair
  430. *
  431. */
  432. DYNAMIC_API PEP_STATUS encrypt_and_sign(
  433. PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
  434. size_t psize, char **ctext, size_t *csize
  435. );
  436. /**
  437. * <!-- set_debug_color() -->
  438. *
  439. * @brief TODO
  440. *
  441. * @param[in] session PEP_SESSION
  442. * @param[in] ansi_color int
  443. *
  444. */
  445. DYNAMIC_API void set_debug_color(PEP_SESSION session, int ansi_color);
  446. /**
  447. * <!-- log_event() -->
  448. *
  449. * @brief Log a user defined event defined by UTF-8 encoded strings into
  450. * management log
  451. *
  452. * @param[in] session session handle
  453. * @param[in] title C string with event name
  454. * @param[in] entity C string with name of entity which is logging
  455. * @param[in] description C string with long description for event or NULL if
  456. * omitted
  457. * @param[in] comment C string with user defined comment or NULL if
  458. * omitted
  459. *
  460. * @retval PEP_STATUS_OK log entry created
  461. *
  462. *
  463. */
  464. DYNAMIC_API PEP_STATUS log_event(
  465. PEP_SESSION session,
  466. const char *title,
  467. const char *entity,
  468. const char *description,
  469. const char *comment
  470. );
  471. /**
  472. * <!-- log_service() -->
  473. *
  474. * @brief TODO
  475. *
  476. * @param[in] session PEP_SESSION
  477. * @param[in] *title constchar
  478. * @param[in] *entity constchar
  479. * @param[in] *description constchar
  480. * @param[in] *comment constchar
  481. *
  482. */
  483. DYNAMIC_API PEP_STATUS log_service(PEP_SESSION session, const char *title,
  484. const char *entity, const char *description, const char *comment);
  485. #define _STR_(x) #x
  486. #define _D_STR_(x) _STR_(x)
  487. #define S_LINE _D_STR_(__LINE__)
  488. #define SERVICE_LOG(session, title, entity, desc) \
  489. log_service((session), (title), (entity), (desc), "service " __FILE__ ":" S_LINE)
  490. /**
  491. * <!-- _service_error_log() -->
  492. *
  493. * @brief TODO
  494. *
  495. * @param[in] session PEP_SESSION
  496. * @param[in] *entity constchar
  497. * @param[in] status PEP_STATUS
  498. * @param[in] *where constchar
  499. *
  500. */
  501. DYNAMIC_API void _service_error_log(PEP_SESSION session, const char *entity,
  502. PEP_STATUS status, const char *where);
  503. #define SERVICE_ERROR_LOG(session, entity, status) \
  504. _service_error_log((session), (entity), (status), __FILE__ ":" S_LINE)
  505. /**
  506. * <!-- trustword() -->
  507. *
  508. * @brief Get the corresponding trustword for a 16 bit value
  509. *
  510. * @param[in] session session handle
  511. * @param[in] value value to find a trustword for
  512. * @param[in] lang C string with ISO 639-1 language code
  513. * @param[out] word pointer to C string with trustword UTF-8 encoded;
  514. * NULL if language is not supported or trustword
  515. * wordlist is damaged or unavailable
  516. * @param[out] wsize length of trustword
  517. *
  518. * @retval PEP_STATUS_OK trustword retrieved
  519. * @retval PEP_TRUSTWORD_NOT_FOUND trustword not found
  520. *
  521. * @warning the word pointer goes to the ownership of the caller
  522. * the caller is responsible to free() it (on Windoze use pEp_free())
  523. *
  524. */
  525. DYNAMIC_API PEP_STATUS trustword(
  526. PEP_SESSION session, uint16_t value, const char *lang,
  527. char **word, size_t *wsize
  528. );
  529. /**
  530. * <!-- trustwords() -->
  531. *
  532. * @brief Get trustwords for a string of hex values of a fingerprint
  533. *
  534. * @param[in] session session handle
  535. * @param[in] fingerprint C string with hex values to find trustwords for
  536. * @param[in] lang C string with ISO 639-1 language code
  537. * @param[out] words pointer to C string with trustwords UTF-8 encoded,
  538. * separated by a blank each;
  539. * NULL if language is not supported or trustword
  540. * wordlist is damaged or unavailable
  541. * @param[out] wsize length of trustwords string
  542. * @param[in] max_words only generate a string with max_words;
  543. * if max_words == 0 there is no such limit
  544. *
  545. * @retval PEP_STATUS_OK trustwords retrieved
  546. * @retval PEP_OUT_OF_MEMORY out of memory
  547. * @retval PEP_TRUSTWORD_NOT_FOUND at least one trustword not found
  548. *
  549. * @warning the word pointer goes to the ownership of the caller
  550. * the caller is responsible to free() it (on Windoze use pEp_free())
  551. *
  552. * @warning DON'T USE THIS FUNCTION FROM HIGH LEVEL LANGUAGES!
  553. * Better implement a simple one in the adapter yourself using trustword(), and
  554. * return a list of trustwords.
  555. *
  556. * @warning This function is provided for being used by C and C++ programs only.
  557. *
  558. */
  559. DYNAMIC_API PEP_STATUS trustwords(
  560. PEP_SESSION session, const char *fingerprint, const char *lang,
  561. char **words, size_t *wsize, int max_words
  562. );
  563. // TODO: increase versions in pEp.asn1 if rating changes
  564. /**
  565. * @enum PEP_comm_type
  566. *
  567. * @brief TODO
  568. *
  569. */
  570. typedef enum _PEP_comm_type {
  571. PEP_ct_unknown = 0,
  572. // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
  573. PEP_ct_no_encryption = 0x01, // generic
  574. PEP_ct_no_encrypted_channel = 0x02,
  575. PEP_ct_key_not_found = 0x03,
  576. PEP_ct_key_expired = 0x04,
  577. PEP_ct_key_revoked = 0x05,
  578. PEP_ct_key_b0rken = 0x06,
  579. PEP_ct_key_expired_but_confirmed = 0x07, // NOT with confirmed bit. Just retaining info here in case of renewal.
  580. PEP_ct_my_key_not_included = 0x09,
  581. PEP_ct_security_by_obscurity = 0x0a,
  582. PEP_ct_b0rken_crypto = 0x0b,
  583. PEP_ct_key_too_short = 0x0c,
  584. PEP_ct_compromised = 0x0e, // known compromised connection
  585. PEP_ct_compromized = 0x0e, // deprecated misspelling
  586. PEP_ct_mistrusted = 0x0f, // known mistrusted key
  587. // range 0x10 to 0x3f: unconfirmed encryption
  588. PEP_ct_unconfirmed_encryption = 0x10, // generic
  589. PEP_ct_OpenPGP_weak_unconfirmed = 0x11, // RSA 1024 is weak
  590. PEP_ct_to_be_checked = 0x20, // generic
  591. PEP_ct_SMIME_unconfirmed = 0x21,
  592. PEP_ct_CMS_unconfirmed = 0x22,
  593. PEP_ct_strong_but_unconfirmed = 0x30, // generic
  594. PEP_ct_OpenPGP_unconfirmed = 0x38, // key at least 2048 bit RSA or EC
  595. PEP_ct_OTR_unconfirmed = 0x3a,
  596. // range 0x40 to 0x7f: unconfirmed encryption and anonymization
  597. PEP_ct_unconfirmed_enc_anon = 0x40, // generic
  598. PEP_ct_pEp_unconfirmed = 0x7f,
  599. PEP_ct_confirmed = 0x80, // this bit decides if trust is confirmed
  600. // range 0x81 to 0x8f: reserved
  601. // range 0x90 to 0xbf: confirmed encryption
  602. PEP_ct_confirmed_encryption = 0x90, // generic
  603. PEP_ct_OpenPGP_weak = 0x91, // RSA 1024 is weak (unused)
  604. PEP_ct_to_be_checked_confirmed = 0xa0, // generic
  605. PEP_ct_SMIME = 0xa1,
  606. PEP_ct_CMS = 0xa2,
  607. PEP_ct_strong_encryption = 0xb0, // generic
  608. PEP_ct_OpenPGP = 0xb8, // key at least 2048 bit RSA or EC
  609. PEP_ct_OTR = 0xba,
  610. // range 0xc0 to 0xff: confirmed encryption and anonymization
  611. PEP_ct_confirmed_enc_anon = 0xc0, // generic
  612. PEP_ct_pEp = 0xff
  613. } PEP_comm_type;
  614. /**
  615. * @enum identity_flags
  616. *
  617. * @brief TODO
  618. *
  619. */
  620. typedef enum _identity_flags {
  621. // the first octet flags are app defined settings
  622. PEP_idf_not_for_sync = 0x0001, // don't use this identity for sync
  623. PEP_idf_list = 0x0002, // identity of list of persons
  624. // the second octet flags are calculated
  625. PEP_idf_devicegroup = 0x0100 // identity of a device group member
  626. } identity_flags;
  627. typedef unsigned int identity_flags_t;
  628. // typedef enum _keypair_flags {
  629. // } keypair_flags;
  630. typedef unsigned int keypair_flags_t;
  631. /**
  632. * @struct pEp_identity
  633. *
  634. * @brief TODO
  635. *
  636. */
  637. typedef struct _pEp_identity {
  638. char *address; // C string with address UTF-8 encoded
  639. char *fpr; // C string with fingerprint UTF-8 encoded
  640. char *user_id; // C string with user ID UTF-8 encoded
  641. // user_id MIGHT be set to "pEp_own_userId"
  642. // (use PEP_OWN_USERID preprocessor define)
  643. // if this is own user's identity.
  644. // But it is not REQUIRED to be.
  645. char *username; // C string with user name UTF-8 encoded
  646. PEP_comm_type comm_type; // type of communication with this ID
  647. char lang[3]; // language of conversation
  648. // ISO 639-1 ALPHA-2, last byte is 0
  649. bool me; // if this is the local user herself/himself
  650. unsigned int major_ver; // highest version of pEp message received, if any
  651. unsigned int minor_ver; // highest version of pEp message received, if any
  652. PEP_enc_format enc_format; // Last specified format we encrypted to for this identity
  653. identity_flags_t flags; // identity_flag1 | identity_flag2 | ...
  654. } pEp_identity;
  655. /**
  656. * @struct identity_list
  657. *
  658. * @brief TODO
  659. *
  660. */
  661. typedef struct _identity_list {
  662. pEp_identity *ident;
  663. struct _identity_list *next;
  664. } identity_list;
  665. /**
  666. * <!-- new_identity() -->
  667. *
  668. * @brief Allocate memory and set the string and size fields
  669. *
  670. * @param[in] address UTF-8 string or NULL
  671. * @param[in] fpr UTF-8 string or NULL
  672. * @param[in] user_id UTF-8 string or NULL
  673. * @param[in] username UTF-8 string or NULL
  674. *
  675. * @retval pEp_identity duplicate identity struct
  676. * @retval NULL if out of memory
  677. *
  678. * @warning the strings are copied; the original strings are still being owned by
  679. * the caller
  680. *
  681. */
  682. DYNAMIC_API pEp_identity *new_identity(
  683. const char *address, const char *fpr, const char *user_id,
  684. const char *username
  685. );
  686. /**
  687. * <!-- identity_dup() -->
  688. *
  689. * @brief Allocate memory and duplicate
  690. *
  691. * @param[in] src identity to duplicate
  692. *
  693. * @retval pEp_identity duplicate identity struct
  694. * @retval NULL if out of memory
  695. *
  696. * @warning the strings are copied; the original strings are still being owned by
  697. * the caller
  698. *
  699. */
  700. DYNAMIC_API pEp_identity *identity_dup(const pEp_identity *src);
  701. /**
  702. * <!-- free_identity() -->
  703. *
  704. * @brief Free all memory being occupied by a pEp_identity struct
  705. *
  706. * @param[in] identity struct to release
  707. *
  708. * @warning not only the struct but also all string memory referenced by the
  709. * struct is being freed; all pointers inside are invalid afterwards
  710. *
  711. */
  712. DYNAMIC_API void free_identity(pEp_identity *identity);
  713. /**
  714. * <!-- get_identity() -->
  715. *
  716. * @brief Get identity information
  717. *
  718. * @param[in] session session handle
  719. * @param[in] address C string with communication address, UTF-8 encoded
  720. * @param[in] user_id unique C string to identify person that identity
  721. * is refering to
  722. * @param[out] identity pointer to pEp_identity structure with results or
  723. * NULL if failure
  724. *
  725. * @warning address and user_id are being copied; the original strings remains in
  726. * the ownership of the caller
  727. * the resulting pEp_identity structure goes to the ownership of the
  728. * caller and has to be freed with free_identity() when not in use any
  729. * more
  730. *
  731. */
  732. DYNAMIC_API PEP_STATUS get_identity(
  733. PEP_SESSION session,
  734. const char *address,
  735. const char *user_id,
  736. pEp_identity **identity
  737. );
  738. /**
  739. * <!-- replace_identities_fpr() -->
  740. *
  741. * @brief TODO
  742. *
  743. * @param[in] session PEP_SESSION
  744. * @param[in] *old_fpr constchar
  745. * @param[in] *new_fpr constchar
  746. *
  747. */
  748. PEP_STATUS replace_identities_fpr(PEP_SESSION session,
  749. const char* old_fpr,
  750. const char* new_fpr);
  751. /**
  752. * <!-- set_identity() -->
  753. *
  754. * @brief Set identity information
  755. *
  756. * @param[in] session session handle
  757. * @param[in] identity pointer to pEp_identity structure
  758. *
  759. * @retval PEP_STATUS_OK encryption and signing succeeded
  760. * @retval PEP_CANNOT_SET_PERSON writing to table person failed
  761. * @retval PEP_CANNOT_SET_PGP_KEYPAIR writing to table pgp_keypair failed
  762. * @retval PEP_CANNOT_SET_IDENTITY writing to table identity failed
  763. * @retval PEP_COMMIT_FAILED SQL commit failed
  764. *
  765. * @warning address, fpr, user_id and username must be given
  766. *
  767. */
  768. DYNAMIC_API PEP_STATUS set_identity(
  769. PEP_SESSION session, const pEp_identity *identity
  770. );
  771. /**
  772. * <!-- get_default_own_userid() -->
  773. *
  774. * @brief Get the user_id of the own user
  775. *
  776. * @param[in] session session handle
  777. * @param[out] userid own user id (if it exists)
  778. *
  779. * @retval PEP_STATUS_OK userid was found
  780. * @retval PEP_CANNOT_FIND_IDENTITY no own_user found in the DB
  781. * @retval PEP_UNKNOWN_ERROR results were returned, but no ID
  782. * found (no reason this should ever
  783. * occur)
  784. *
  785. * @warning userid will be NULL if not found; otherwise, returned string
  786. * belongs to the caller.
  787. *
  788. */
  789. DYNAMIC_API PEP_STATUS get_default_own_userid(
  790. PEP_SESSION session,
  791. char** userid
  792. );
  793. /**
  794. * <!-- get_userid_alias_default() -->
  795. *
  796. * @brief Get the default user_id which corresponds
  797. * to an alias
  798. *
  799. * @param[in] session session handle
  800. * @param[in] alias_id the user_id which may be an alias for a default id
  801. * @param[out] default_id the default id for this alias, if the alias
  802. * is in the DB as an alias, else NULL
  803. *
  804. * @retval PEP_STATUS_OK userid was found
  805. * @retval PEP_CANNOT_FIND_ALIAS this userid is not listed as an
  806. * alias in the DB
  807. * @retval PEP_UNKNOWN_ERROR results were returned, but no ID
  808. * found (no reason this should ever
  809. * occur)
  810. *
  811. * @warning default_id will be NULL if not found; otherwise, returned string
  812. * belongs to the caller.
  813. * also, current implementation does NOT check to see if this userid
  814. * IS a default.
  815. *
  816. */
  817. DYNAMIC_API PEP_STATUS get_userid_alias_default(
  818. PEP_SESSION session,
  819. const char* alias_id,
  820. char** default_id);
  821. /**
  822. * <!-- set_userid_alias() -->
  823. *
  824. * @brief Set an alias to correspond to a default id
  825. *
  826. * @param[in] session session handle
  827. * @param[in] default_id the default id for this alias. This must
  828. * correspond to the default user_id for an
  829. * entry in the person (user) table.
  830. * @param[in] alias_id the alias to be set for this default id
  831. *
  832. * @retval PEP_STATUS_OK userid was found
  833. * @retval PEP_CANNOT_SET_ALIAS there was an error setting this
  834. *
  835. *
  836. */
  837. DYNAMIC_API PEP_STATUS set_userid_alias (
  838. PEP_SESSION session,
  839. const char* default_id,
  840. const char* alias_id);
  841. /**
  842. * <!-- set_identity_flags() -->
  843. *
  844. * @brief Update identity flags on existing identity
  845. *
  846. * @param[in] session session handle
  847. * identity (in,out) pointer to pEp_identity structure
  848. * @param[in] flags new value for flags
  849. *
  850. * @retval PEP_STATUS_OK encryption and signing succeeded
  851. * @retval PEP_CANNOT_SET_IDENTITY update of identity failed
  852. *
  853. * @warning address and user_id must be given in identity
  854. *
  855. */
  856. DYNAMIC_API PEP_STATUS set_identity_flags(
  857. PEP_SESSION session,
  858. pEp_identity *identity,
  859. identity_flags_t flags
  860. );
  861. /**
  862. * <!-- unset_identity_flags() -->
  863. *
  864. * @brief Update identity flags on existing identity
  865. *
  866. * @param[in] session session handle
  867. * identity (in,out) pointer to pEp_identity structure
  868. * @param[in] flags new value for flags
  869. *
  870. * @retval PEP_STATUS_OK encryption and signing succeeded
  871. * @retval PEP_CANNOT_SET_IDENTITY update of identity failed
  872. *
  873. * @warning address and user_id must be given in identity
  874. *
  875. */
  876. DYNAMIC_API PEP_STATUS unset_identity_flags(
  877. PEP_SESSION session,
  878. pEp_identity *identity,
  879. identity_flags_t flags
  880. );
  881. /**
  882. * <!-- mark_as_compromised() -->
  883. *
  884. * @brief Mark key in trust db as compromised
  885. *
  886. * @param[in] session session handle
  887. * @param[in] fpr fingerprint of key to mark
  888. *
  889. *
  890. */
  891. DYNAMIC_API PEP_STATUS mark_as_compromised(
  892. PEP_SESSION session,
  893. const char *fpr
  894. );
  895. /**
  896. * <!-- mark_as_compromized() -->
  897. *
  898. * @brief Deprecated to fix misspelling. Please move to
  899. * mark_as_compromised();
  900. *
  901. *
  902. */
  903. DYNAMIC_API PEP_STATUS mark_as_compromized(
  904. PEP_SESSION session,
  905. const char *fpr
  906. );
  907. /**
  908. * <!-- generate_keypair() -->
  909. *
  910. * @brief Generate a new key pair and add it to the key ring
  911. *
  912. * @param[in] session session handle
  913. * @param[in,out] identity pointer to pEp_identity structure
  914. *
  915. * @retval PEP_STATUS_OK encryption and signing succeeded
  916. * @retval PEP_ILLEGAL_VALUE illegal values for identity fields given
  917. * @retval PEP_CANNOT_CREATE_KEY key engine is on strike
  918. *
  919. * @warning address must be set to UTF-8 string
  920. * the fpr field must be set to NULL
  921. * username field must either be NULL or be a UTF8-string conforming
  922. * to RFC4880 for PGP uid usernames
  923. *
  924. * @note this function allocates a string and sets set fpr field of identity
  925. * the caller is responsible to call free() for that string or use
  926. * free_identity() on the struct
  927. *
  928. */
  929. DYNAMIC_API PEP_STATUS generate_keypair(
  930. PEP_SESSION session, pEp_identity *identity
  931. );
  932. /**
  933. * <!-- delete_keypair() -->
  934. *
  935. * @brief Delete a public key or a key pair from the key ring
  936. *
  937. * @param[in] session session handle
  938. * @param[in] fpr C string with key id or fingerprint of the
  939. * public key
  940. *
  941. * @retval PEP_STATUS_OK key was successfully deleted
  942. * @retval PEP_KEY_NOT_FOUND key not found
  943. * @retval PEP_ILLEGAL_VALUE not a valid key id or fingerprint
  944. * @retval PEP_KEY_HAS_AMBIG_NAME fpr does not uniquely identify a key
  945. * @retval PEP_OUT_OF_MEMORY out of memory
  946. *
  947. *
  948. */
  949. DYNAMIC_API PEP_STATUS delete_keypair(PEP_SESSION session, const char *fpr);
  950. /**
  951. * <!-- import_key() -->
  952. *
  953. * @brief Import key from data
  954. *
  955. * @param[in] session session handle
  956. * @param[in] key_data key data, i.e. ASCII armored OpenPGP key
  957. * @param[in] size amount of data to handle
  958. * @param[out] private_keys list of identities containing the
  959. * private keys that have been imported
  960. *
  961. * @retval PEP_STATUS_OK key was successfully imported
  962. * @retval PEP_OUT_OF_MEMORY out of memory
  963. * @retval PEP_ILLEGAL_VALUE there is no key data to import
  964. *
  965. * @warning private_keys goes to the ownership of the caller
  966. * private_keys can be left NULL, it is then ignored
  967. *
  968. */
  969. DYNAMIC_API PEP_STATUS import_key(
  970. PEP_SESSION session,
  971. const char *key_data,
  972. size_t size,
  973. identity_list **private_keys
  974. );
  975. /**
  976. * <!-- _import_key_with_fpr_return() -->
  977. *
  978. * @brief INTERNAL FUNCTION - import keys from data, return optional list
  979. * of fprs imported
  980. *
  981. * @param[in] session session handle
  982. * @param[in] key_data key data, i.e. ASCII armored OpenPGP key
  983. * @param[in] size amount of data to handle
  984. * @param[out] private_keys list of identities containing the
  985. * private keys that have been imported
  986. * @param[out] imported_keys if non-NULL, list of actual keys imported
  987. * @param[out] changed_public_keys if non-NULL AND imported_keys is non-NULL:
  988. * bitvector - corresponds to the first 64 keys
  989. * imported. If nth bit is set, import changed a
  990. * key corresponding to the nth element in
  991. * imported keys (i.e. key was in DB and was
  992. * changed by import)
  993. *
  994. * @retval PEP_STATUS_OK key was successfully imported
  995. * @retval PEP_OUT_OF_MEMORY out of memory
  996. * @retval PEP_ILLEGAL_VALUE there is no key data to import, or imported keys was NULL and
  997. * changed_public_keys was not
  998. *
  999. * @warning private_keys and imported_keys goes to the ownership of the caller
  1000. * private_keys and imported_keys can be left NULL, it is then ignored
  1001. * *** THIS IS THE ACTUAL FUNCTION IMPLEMENTED BY CRYPTOTECH "import_key" ***
  1002. *
  1003. */
  1004. PEP_STATUS _import_key_with_fpr_return(
  1005. PEP_SESSION session,
  1006. const char *key_data,
  1007. size_t size,
  1008. identity_list** private_keys,
  1009. stringlist_t** imported_keys,
  1010. uint64_t* changed_public_keys // use as bit field for the first 64 changed keys
  1011. );
  1012. /**
  1013. * <!-- export_key() -->
  1014. *
  1015. * @brief Export ascii armored key
  1016. *
  1017. * @param[in] session session handle
  1018. * @param[in] fpr key id or fingerprint of key
  1019. * @param[out] key_data ASCII armored OpenPGP key
  1020. * @param[out] size amount of data to handle
  1021. *
  1022. * @retval PEP_STATUS_OK key was successfully exported
  1023. * @retval PEP_OUT_OF_MEMORY out of memory
  1024. * @retval PEP_KEY_NOT_FOUND key not found
  1025. *
  1026. * @warning the key_data goes to the ownership of the caller
  1027. * the caller is responsible to free() it (on Windoze use pEp_free())
  1028. *
  1029. */
  1030. DYNAMIC_API PEP_STATUS export_key(
  1031. PEP_SESSION session, const char *fpr, char **key_data, size_t *size
  1032. );
  1033. /**
  1034. * <!-- export_secret_key() -->
  1035. *
  1036. * @brief Export secret key ascii armored
  1037. *
  1038. * @param[in] session session handle
  1039. * @param[in] fpr fingerprint of key, at least 16 hex digits
  1040. * @param[out] key_data ASCII armored OpenPGP secret key
  1041. * @param[out] size amount of data to handle
  1042. *
  1043. * @retval PEP_STATUS_OK key was successfully exported
  1044. * @retval PEP_OUT_OF_MEMORY out of memory
  1045. * @retval PEP_KEY_NOT_FOUND key not found
  1046. * @retval PEP_CANNOT_EXPORT_KEY cannot export secret key (i.e. it's on an HKS)
  1047. *
  1048. * @warning the key_data goes to the ownership of the caller
  1049. * the caller is responsible to free() it (on Windoze use pEp_free())
  1050. * beware of leaking secret key data - overwrite it in memory after use
  1051. *
  1052. */
  1053. DYNAMIC_API PEP_STATUS export_secret_key(
  1054. PEP_SESSION session, const char *fpr, char **key_data, size_t *size
  1055. );
  1056. /**
  1057. * <!-- export_secrect_key() -->
  1058. *
  1059. * @brief Deprecated misspelled function. Please replace with
  1060. * export_secret_key
  1061. *
  1062. * @deprecated
  1063. */
  1064. DYNAMIC_API PEP_STATUS export_secrect_key(
  1065. PEP_SESSION session, const char *fpr, char **key_data, size_t *size
  1066. );
  1067. /**
  1068. * <!-- recv_key() -->
  1069. *
  1070. * @brief Update key(s) from keyserver
  1071. *
  1072. * @param[in] session session handle
  1073. * @param[in] pattern key id, user id or address to search for as
  1074. * UTF-8 string
  1075. *
  1076. *
  1077. */
  1078. DYNAMIC_API PEP_STATUS recv_key(PEP_SESSION session, const char *pattern);
  1079. /**
  1080. * <!-- find_keys() -->
  1081. *
  1082. * @brief Find keys in keyring
  1083. *
  1084. * @param[in] session session handle
  1085. * @param[in] pattern key id, user id or address to search for as
  1086. * UTF-8 string
  1087. * @param[out] keylist list of fingerprints found or NULL on error
  1088. *
  1089. * @warning the ownership of keylist and its elements go to the caller
  1090. * the caller must use free_stringlist() to free it
  1091. *
  1092. */
  1093. DYNAMIC_API PEP_STATUS find_keys(
  1094. PEP_SESSION session, const char *pattern, stringlist_t **keylist
  1095. );
  1096. /**
  1097. * <!-- send_key() -->
  1098. *
  1099. * @brief Send key(s) to keyserver
  1100. *
  1101. * @param[in] session session handle
  1102. * @param[in] pattern key id, user id or address to search for as
  1103. * UTF-8 string
  1104. *
  1105. *
  1106. */
  1107. DYNAMIC_API PEP_STATUS send_key(PEP_SESSION session, const char *pattern);
  1108. /**
  1109. * <!-- pEp_free() -->
  1110. *
  1111. * @brief Free memory allocated by pEp engine
  1112. *
  1113. * @param[in] p pointer to free <br>
  1114. * The reason for this function is that heap management can be a pretty
  1115. * complex task with Windoze. This free() version calls the free()
  1116. * implementation of the C runtime library which was used to build pEp engine,
  1117. * so you're using the correct heap. For more information, see:
  1118. * <http://msdn.microsoft.com/en-us/library/windows/desktop/aa366711(v=vs.85).aspx>
  1119. *
  1120. *
  1121. */
  1122. DYNAMIC_API void pEp_free(void *p);
  1123. /**
  1124. * <!-- pEp_realloc() -->
  1125. *
  1126. * @brief Reallocate memory allocated by pEp engine
  1127. *
  1128. * @param[in] p pointer to free
  1129. * @param[in] size new memory size
  1130. *
  1131. * @retval pointer to allocated memory
  1132. *
  1133. * @note The reason for this function is that heap management can be a pretty
  1134. * complex task with Windoze. This realloc() version calls the realloc()
  1135. * implementation of the C runtime library which was used to build pEp engine,
  1136. * so you're using the correct heap. For more information, see:
  1137. * <http://msdn.microsoft.com/en-us/library/windows/desktop/aa366711(v=vs.85).aspx>
  1138. *
  1139. *
  1140. */
  1141. DYNAMIC_API void *pEp_realloc(void *p, size_t size);
  1142. /**
  1143. * <!-- get_trust() -->
  1144. *
  1145. * @brief Get the trust level a key has for a person
  1146. *
  1147. * @param[in] session session handle
  1148. * @param[in,out] identity user_id and fpr to check as UTF-8 strings (in)
  1149. * comm_type as result (out)
  1150. * this function modifies the given identity struct; the struct remains in
  1151. * the ownership of the caller
  1152. * if the trust level cannot be determined identity->comm_type is set
  1153. * to PEP_ct_unknown
  1154. *
  1155. *
  1156. */
  1157. DYNAMIC_API PEP_STATUS get_trust(PEP_SESSION session, pEp_identity *identity);
  1158. /**
  1159. * <!-- set_trust() -->
  1160. *
  1161. * @brief TODO
  1162. *
  1163. * @param[in] session PEP_SESSION
  1164. * @param[in] *identity pEp_identity
  1165. *
  1166. */
  1167. PEP_STATUS set_trust(PEP_SESSION session,
  1168. pEp_identity* identity);
  1169. /**
  1170. * <!-- update_trust_for_fpr() -->
  1171. *
  1172. * @brief TODO
  1173. *
  1174. * @param[in] session PEP_SESSION
  1175. * @param[in] *fpr constchar
  1176. * @param[in] comm_type PEP_comm_type
  1177. *
  1178. */
  1179. PEP_STATUS update_trust_for_fpr(PEP_SESSION session,
  1180. const char* fpr,
  1181. PEP_comm_type comm_type);
  1182. /**
  1183. * <!-- least_trust() -->
  1184. *
  1185. * @brief Get the least known trust level for a key in the database
  1186. *
  1187. * @param[in] session session handle
  1188. * @param[in] fpr fingerprint of key to check
  1189. * @param[out] comm_type least comm_type as result (out)
  1190. * if the trust level cannot be determined comm_type is set to PEP_ct_unknown
  1191. *
  1192. *
  1193. */
  1194. DYNAMIC_API PEP_STATUS least_trust(
  1195. PEP_SESSION session,
  1196. const char *fpr,
  1197. PEP_comm_type *comm_type
  1198. );
  1199. /**
  1200. * <!-- get_key_rating() -->
  1201. *
  1202. * @brief Get the rating a bare key has
  1203. *
  1204. * @param[in] session session handle
  1205. * @param[in] fpr unique identifyer for key as UTF-8 string
  1206. * @param[out] comm_type key rating
  1207. * if an error occurs, *comm_type is set to PEP_ct_unknown and an error
  1208. * is returned
  1209. *
  1210. *
  1211. */
  1212. DYNAMIC_API PEP_STATUS get_key_rating(
  1213. PEP_SESSION session,
  1214. const char *fpr,
  1215. PEP_comm_type *comm_type
  1216. );
  1217. /**
  1218. * <!-- renew_key() -->
  1219. *
  1220. * @brief Renew an expired key
  1221. *
  1222. * @param[in] session session handle
  1223. * @param[in] fpr ID of key to renew as UTF-8 string
  1224. * @param[in] ts timestamp when key should expire or NULL for
  1225. * default
  1226. *
  1227. *
  1228. */
  1229. DYNAMIC_API PEP_STATUS renew_key(
  1230. PEP_SESSION session,
  1231. const char *fpr,
  1232. const timestamp *ts
  1233. );
  1234. /**
  1235. * <!-- revoke_key() -->
  1236. *
  1237. * @brief Revoke a key
  1238. *
  1239. * @param[in] session session handle
  1240. * @param[in] fpr ID of key to revoke as UTF-8 string
  1241. * @param[in] reason text with reason for revoke as UTF-8 string
  1242. * or NULL if reason unknown
  1243. *
  1244. * @warning reason text must not include empty lines
  1245. * this function is meant for internal use only; better use
  1246. * key_mistrusted() of keymanagement API
  1247. *
  1248. */
  1249. DYNAMIC_API PEP_STATUS revoke_key(
  1250. PEP_SESSION session,
  1251. const char *fpr,
  1252. const char *reason
  1253. );
  1254. /**
  1255. * <!-- key_expired() -->
  1256. *
  1257. * @brief Flags if a key is already expired
  1258. *
  1259. * @param[in] session session handle
  1260. * @param[in] fpr ID of key to check as UTF-8 string
  1261. * @param[in] when UTC time of when should expiry be considered
  1262. * @param[out] expired flag if key expired
  1263. *
  1264. *
  1265. */
  1266. DYNAMIC_API PEP_STATUS key_expired(
  1267. PEP_SESSION session,
  1268. const char *fpr,
  1269. const time_t when,
  1270. bool *expired
  1271. );
  1272. /**
  1273. * <!-- key_revoked() -->
  1274. *
  1275. * @brief Flags if a key is already revoked
  1276. *
  1277. * @param[in] session session handle
  1278. * @param[in] fpr ID of key to check as UTF-8 string
  1279. * @param[out] revoked flag if key revoked
  1280. *
  1281. *
  1282. */
  1283. DYNAMIC_API PEP_STATUS key_revoked(
  1284. PEP_SESSION session,
  1285. const char *fpr,
  1286. bool *revoked
  1287. );
  1288. /**
  1289. * <!-- get_key_userids() -->
  1290. *
  1291. * @brief TODO
  1292. *
  1293. * @param[in] session PEP_SESSION
  1294. * @param[in] *fpr constchar
  1295. * @param[in] **keylist stringlist_t
  1296. *
  1297. */
  1298. PEP_STATUS get_key_userids(
  1299. PEP_SESSION session,
  1300. const char* fpr,
  1301. stringlist_t** keylist
  1302. );
  1303. /**
  1304. * <!-- get_crashdump_log() -->
  1305. *
  1306. * @brief Get the last log messages out
  1307. *
  1308. * @param[in] session session handle
  1309. * @param[in] maxlines maximum number of lines (0 for default)
  1310. * @param[out] logdata logdata as string in double quoted CSV format
  1311. * column1 is title
  1312. * column2 is entity
  1313. * column3 is description
  1314. * column4 is comment
  1315. *
  1316. * @warning the ownership of logdata goes to the caller
  1317. *
  1318. */
  1319. DYNAMIC_API PEP_STATUS get_crashdump_log(
  1320. PEP_SESSION session,
  1321. int maxlines,
  1322. char **logdata
  1323. );
  1324. /**
  1325. * <!-- get_languagelist() -->
  1326. *
  1327. * @brief Get the list of languages
  1328. *
  1329. * @param[in] session session handle
  1330. * @param[out] languages languages as string in double quoted CSV format
  1331. * column 1 is the ISO 639-1 language code
  1332. * column 2 is the name of the language
  1333. *
  1334. * @warning the ownership of languages goes to the caller
  1335. *
  1336. */
  1337. DYNAMIC_API PEP_STATUS get_languagelist(
  1338. PEP_SESSION session,
  1339. char **languages
  1340. );
  1341. /**
  1342. * <!-- get_phrase() -->
  1343. *
  1344. * @brief Get phrase in a dedicated language through i18n
  1345. *
  1346. * @param[in] session session handle
  1347. * @param[in] lang C string with ISO 639-1 language code
  1348. * @param[in] phrase_id id of phrase in i18n
  1349. * @param[out] phrase phrase as UTF-8 string
  1350. *
  1351. * @warning the ownership of phrase goes to the caller
  1352. *
  1353. */
  1354. DYNAMIC_API PEP_STATUS get_phrase(
  1355. PEP_SESSION session,
  1356. const char *lang,
  1357. int phrase_id,
  1358. char **phrase
  1359. );
  1360. /**
  1361. * <!-- sequence_value() -->
  1362. *
  1363. * @brief Raise the value of a named sequence and retrieve it
  1364. *
  1365. * @param[in] session session handle
  1366. * @param[in] name name of sequence
  1367. * @param[out] value value of sequence
  1368. *
  1369. * @retval PEP_STATUS_OK no error, not own sequence
  1370. * @retval PEP_SEQUENCE_VIOLATED if sequence violated
  1371. * @retval PEP_CANNOT_INCREASE_SEQUENCE if sequence cannot be increased
  1372. * @retval PEP_OWN_SEQUENCE if own sequence
  1373. *
  1374. *
  1375. */
  1376. DYNAMIC_API PEP_STATUS sequence_value(
  1377. PEP_SESSION session,
  1378. const char *name,
  1379. int32_t *value
  1380. );
  1381. /**
  1382. * <!-- set_revoked() -->
  1383. *
  1384. * @brief Records relation between a revoked key and its replacement
  1385. *
  1386. * @param[in] session session handle
  1387. * @param[in] revoked_fpr revoked fingerprint
  1388. * @param[in] replacement_fpr replacement key fingerprint
  1389. * @param[in] revocation_date revocation date
  1390. *
  1391. *
  1392. */
  1393. DYNAMIC_API PEP_STATUS set_revoked(
  1394. PEP_SESSION session,
  1395. const char *revoked_fpr,
  1396. const char *replacement_fpr,
  1397. const uint64_t revocation_date
  1398. );
  1399. /**
  1400. * <!-- get_revoked() -->
  1401. *
  1402. * @brief Find revoked key that may have been replaced by given key, if any
  1403. *
  1404. * @param[in] session session handle
  1405. * @param[in] fpr given fingerprint
  1406. * @param[out] revoked_fpr revoked fingerprint
  1407. * @param[out] revocation_date revocation date
  1408. *
  1409. *
  1410. */
  1411. DYNAMIC_API PEP_STATUS get_revoked(
  1412. PEP_SESSION session,
  1413. const char *fpr,
  1414. char **revoked_fpr,
  1415. uint64_t *revocation_date
  1416. );
  1417. /**
  1418. * <!-- key_created() -->
  1419. *
  1420. * @brief Get creation date of a key
  1421. *
  1422. * @param[in] session session handle
  1423. * @param[in] fpr fingerprint of key
  1424. * @param[out] created date of creation
  1425. *
  1426. *
  1427. */
  1428. PEP_STATUS key_created(
  1429. PEP_SESSION session,
  1430. const char *fpr,
  1431. time_t *created
  1432. );
  1433. /**
  1434. * <!-- find_private_keys() -->
  1435. *
  1436. * @brief Find keys in keyring
  1437. *
  1438. * @param[in] session session handle
  1439. * @param[in] pattern key id, user id or address to search for as
  1440. * UTF-8 string
  1441. * @param[out] keylist list of fingerprints found or NULL on error
  1442. *
  1443. * @warning the ownerships of keylist isgoing to the caller
  1444. * the caller must use free_stringlist() to free it
  1445. *
  1446. */
  1447. PEP_STATUS find_private_keys(PEP_SESSION session, const char* pattern,
  1448. stringlist_t **keylist);
  1449. /**
  1450. * <!-- get_engine_version() -->
  1451. *
  1452. * @brief Returns the current version of pEpEngine (this is different
  1453. * from the pEp protocol version!)
  1454. *
  1455. *
  1456. */
  1457. DYNAMIC_API const char* get_engine_version();
  1458. /**
  1459. * <!-- get_protocol_version() -->
  1460. *
  1461. * @brief Returns the pEp protocol version
  1462. *
  1463. *
  1464. */
  1465. DYNAMIC_API const char *get_protocol_version();
  1466. /**
  1467. * <!-- is_pEp_user() -->
  1468. *
  1469. * @brief Returns true if the USER corresponding to this identity
  1470. * has been listed in the *person* table as a pEp user.
  1471. *
  1472. * @param[in] identity identity containing the user_id to check (this is
  1473. * the only part of the struct we require to be set)
  1474. * @param[out] is_pEp boolean pointer - will return true or false by
  1475. * reference with respect to whether or not user is
  1476. * a known pEp user
  1477. *
  1478. * @retval PEP_STATUS_OK if user found in person table
  1479. * @retval PEP_ILLEGAL_VALUE if no user_id in input
  1480. * @retval PEP_CANNOT_FIND_PERSON if user_id doesn't exist
  1481. *
  1482. *
  1483. */
  1484. DYNAMIC_API PEP_STATUS is_pEp_user(PEP_SESSION session,
  1485. pEp_identity *identity,
  1486. bool* is_pEp);
  1487. /**
  1488. * <!-- per_user_directory() -->
  1489. *
  1490. * @brief Returns the directory for pEp management db
  1491. *
  1492. * @retval char* path to actual per user directory
  1493. * @retval NULL on failure
  1494. *
  1495. *
  1496. */
  1497. DYNAMIC_API const char *per_user_directory(void);
  1498. /**
  1499. * <!-- per_machine_directory() -->
  1500. *
  1501. * @brief Returns the directory for pEp system db
  1502. *
  1503. * @retval char* path to actual per machine directory
  1504. * @retval NULL on failure
  1505. *
  1506. *
  1507. */
  1508. DYNAMIC_API const char *per_machine_directory(void);
  1509. // FIXME: replace in canonical style
  1510. //
  1511. /**
  1512. * <!-- config_passphrase() -->
  1513. *
  1514. * @brief Configure a key passphrase for the current session.
  1515. *
  1516. * A passphrase can be configured into a pp session. Then it is used whenever a
  1517. * secret key is used which requires a passphrase.
  1518. *
  1519. * A passphrase is a string between 1 and 1024 bytes and is only ever present in
  1520. * memory. Because strings in the pp engine are UTF-8 NFC, the string is
  1521. * restricted to 250 code points in UI.
  1522. *
  1523. * This function copies the passphrase into the session. It may return
  1524. * PEP_OUT_OF_MEMORY. The behaviour of all functions which use secret keys may
  1525. * change after this is configured.
  1526. *
  1527. * Error behaviour:
  1528. *
  1529. * For any function which may trigger the use of a secret key, if an attempt
  1530. * to use a secret key which requires a passphrase occurs and no passphrase
  1531. * is configured for the current session, PEP_PASSPHRASE_REQUIRED is
  1532. * returned by this function (and thus, all functions which could trigger
  1533. * such a usage must be prepared to return this value). For any function
  1534. * which may trigger the use of a secret key, if a passphrase is configured
  1535. * and the configured passphrase is the wrong passphrase for the use of a
  1536. * given passphrase-protected secret key, PEP_WRONG_PASSPHRASE is returned
  1537. * by this function (and thus, all functions which could trigger such a
  1538. * usage must be prepared to return this value).
  1539. *
  1540. *
  1541. */
  1542. DYNAMIC_API PEP_STATUS config_passphrase(PEP_SESSION session, const char *passphrase);
  1543. // FIXME: replace in canonical style
  1544. //
  1545. /**
  1546. * <!-- config_passphrase_for_new_keys() -->
  1547. *
  1548. * @brief Passphrase enablement for newly-generated secret keys
  1549. *
  1550. * If it is desired that new pp keys are passphrase-protected, the following
  1551. * API call is used to enable the addition of passphrases to new keys during key
  1552. * generation.
  1553. *
  1554. * If enabled and a passphrase for new keys has been configured
  1555. * through this function (NOT the one above - this is a separate passphrase!),
  1556. * then anytime a secret key is generated while enabled, the configured
  1557. * passphrase will be used as the passphrase for any newly-generated secret key.
  1558. *
  1559. * If enabled and a passphrase for new keys has not been configured, then any
  1560. * function which can attempt to generate a secret key will return
  1561. * PEP_PASSPHRASE_FOR_NEW_KEYS_REQUIRED.
  1562. *
  1563. * If disabled (i.e. not enabled) and a passphrase for new keys has been
  1564. * configured, no passphrases will be used for newly-generated keys.
  1565. *
  1566. * This function copies the passphrase for new keys into a special field that is
  1567. * specifically for key generation into the session. It may return
  1568. * PEP_OUT_OF_MEMORY. The behaviour of all functions which use secret keys may
  1569. * change after this is configured.
  1570. *
  1571. */
  1572. DYNAMIC_API PEP_STATUS config_passphrase_for_new_keys(PEP_SESSION session,
  1573. bool enable,
  1574. const char *passphrase);
  1575. /**
  1576. * <!-- set_ident_enc_format() -->
  1577. *
  1578. * @brief Set the default encryption format for this identity
  1579. * (value only MIGHT be used, and only in the case where the
  1580. * message enc_format is PEP_enc_auto. It will be used
  1581. * opportunistically in the case on a first-come, first-serve
  1582. * basis in the order of to_list, cc_list, and bcc_list. We take
  1583. * the first set value we come to)
  1584. *
  1585. * @param[in] session session handle
  1586. * @param[in] identity identity->user_id and identity->address must NOT be NULL
  1587. * @param[in] format the desired default encryption format
  1588. *
  1589. *
  1590. */
  1591. DYNAMIC_API PEP_STATUS set_ident_enc_format(PEP_SESSION session,
  1592. pEp_identity *identity,
  1593. PEP_enc_format format);
  1594. /**
  1595. * <!-- _generate_keypair() -->
  1596. *
  1597. * @brief TODO
  1598. *
  1599. * @param[in] session PEP_SESSION
  1600. * @param[in] *identity pEp_identity
  1601. * @param[in] suppress_event bool
  1602. *
  1603. */
  1604. PEP_STATUS _generate_keypair(PEP_SESSION session,
  1605. pEp_identity *identity,
  1606. bool suppress_event);
  1607. /**
  1608. * <!-- reset_pEptest_hack() -->
  1609. *
  1610. * @brief TODO
  1611. *
  1612. * @param[in] session PEP_SESSION
  1613. *
  1614. */
  1615. DYNAMIC_API PEP_STATUS reset_pEptest_hack(PEP_SESSION session);
  1616. // This is used internally when there is a temporary identity to be retrieved
  1617. // that may not yet have an FPR attached. See get_identity() for functionality,
  1618. // params and caveats.
  1619. /**
  1620. * <!-- get_identity_without_trust_check() -->
  1621. *
  1622. * @brief TODO
  1623. *
  1624. * @param[in] session PEP_SESSION
  1625. * @param[in] *address constchar
  1626. * @param[in] *user_id constchar
  1627. * @param[in] **identity pEp_identity
  1628. *
  1629. */
  1630. PEP_STATUS get_identity_without_trust_check(
  1631. PEP_SESSION session,
  1632. const char *address,
  1633. const char *user_id,
  1634. pEp_identity **identity
  1635. );
  1636. /**
  1637. * <!-- get_identities_by_address() -->
  1638. *
  1639. * @brief TODO
  1640. *
  1641. * @param[in] session PEP_SESSION
  1642. * @param[in] *address constchar
  1643. * @param[in] **id_list identity_list
  1644. *
  1645. */
  1646. PEP_STATUS get_identities_by_address(
  1647. PEP_SESSION session,
  1648. const char *address,
  1649. identity_list** id_list
  1650. );
  1651. /**
  1652. * <!-- get_identities_by_userid() -->
  1653. *
  1654. * @brief TODO
  1655. *
  1656. * @param[in] session PEP_SESSION
  1657. * @param[in] *user_id constchar
  1658. * @param[in] **identities identity_list
  1659. *
  1660. */
  1661. PEP_STATUS get_identities_by_userid(
  1662. PEP_SESSION session,
  1663. const char *user_id,
  1664. identity_list **identities
  1665. );
  1666. /**
  1667. * <!-- is_own_address() -->
  1668. *
  1669. * @brief TODO
  1670. *
  1671. * @param[in] session PEP_SESSION
  1672. * @param[in] *address constchar
  1673. * @param[in] *is_own_addr bool
  1674. *
  1675. */
  1676. PEP_STATUS is_own_address(PEP_SESSION session,
  1677. const char* address,
  1678. bool* is_own_addr);
  1679. /**
  1680. * <!-- replace_userid() -->
  1681. *
  1682. * @brief TODO
  1683. *
  1684. * @param[in] session PEP_SESSION
  1685. * @param[in] *old_uid constchar
  1686. * @param[in] *new_uid constchar
  1687. *
  1688. */
  1689. PEP_STATUS replace_userid(PEP_SESSION session, const char* old_uid,
  1690. const char* new_uid);
  1691. /**
  1692. * <!-- remove_key() -->
  1693. *
  1694. * @brief TODO
  1695. *
  1696. * @param[in] session PEP_SESSION
  1697. * @param[in] *fpr constchar
  1698. *
  1699. */
  1700. PEP_STATUS remove_key(PEP_SESSION session, const char* fpr);
  1701. /**
  1702. * <!-- remove_fpr_as_default() -->
  1703. *
  1704. * @brief TODO
  1705. *
  1706. * @param[in] session PEP_SESSION
  1707. * @param[in] *fpr constchar
  1708. *
  1709. */
  1710. PEP_STATUS remove_fpr_as_default(PEP_SESSION session,
  1711. const char* fpr);
  1712. /**
  1713. * <!-- get_main_user_fpr() -->
  1714. *
  1715. * @brief TODO
  1716. *
  1717. * @param[in] session PEP_SESSION
  1718. * @param[in] *user_id constchar
  1719. * @param[in] **main_fpr char
  1720. *
  1721. */
  1722. PEP_STATUS get_main_user_fpr(PEP_SESSION session,
  1723. const char* user_id,
  1724. char** main_fpr);
  1725. /**
  1726. * <!-- replace_main_user_fpr() -->
  1727. *
  1728. * @brief TODO
  1729. *
  1730. * @param[in] session PEP_SESSION
  1731. * @param[in] *user_id constchar
  1732. * @param[in] *new_fpr constchar
  1733. *
  1734. */
  1735. PEP_STATUS replace_main_user_fpr(PEP_SESSION session, const char* user_id,
  1736. const char* new_fpr);
  1737. /**
  1738. * <!-- replace_main_user_fpr_if_equal() -->
  1739. *
  1740. * @brief TODO
  1741. *
  1742. * @param[in] session PEP_SESSION
  1743. * @param[in] *user_id constchar
  1744. * @param[in] *new_fpr constchar
  1745. * @param[in] *compare_fpr constchar
  1746. *
  1747. */
  1748. PEP_STATUS replace_main_user_fpr_if_equal(PEP_SESSION session, const char* user_id,
  1749. const char* new_fpr, const char* compare_fpr);
  1750. DYNAMIC_API PEP_STATUS get_replacement_fpr(
  1751. PEP_SESSION session,
  1752. const char *fpr,
  1753. char **revoked_fpr,
  1754. uint64_t *revocation_date
  1755. );
  1756. /**
  1757. * <!-- refresh_userid_default_key() -->
  1758. *
  1759. * @brief TODO
  1760. *
  1761. * @param[in] session PEP_SESSION
  1762. * @param[in] *user_id constchar
  1763. *
  1764. */
  1765. PEP_STATUS refresh_userid_default_key(PEP_SESSION session, const char* user_id);
  1766. // This ONLY sets the *user* flag, and creates a shell identity if necessary.
  1767. /**
  1768. * <!-- set_as_pEp_user() -->
  1769. *
  1770. * @brief TODO
  1771. *
  1772. * @param[in] session PEP_SESSION
  1773. * @param[in] *user pEp_identity
  1774. *
  1775. */
  1776. DYNAMIC_API PEP_STATUS set_as_pEp_user(PEP_SESSION session, pEp_identity* user);
  1777. // returns true (by reference) if a person with this user_id exists;
  1778. // Also replaces aliased user_ids by defaults in identity.
  1779. /**
  1780. * <!-- exists_person() -->
  1781. *
  1782. * @brief TODO
  1783. *
  1784. * @param[in] session PEP_SESSION
  1785. * @param[in] *identity pEp_identity
  1786. * @param[in] *exists bool
  1787. *
  1788. */
  1789. PEP_STATUS exists_person(PEP_SESSION session, pEp_identity* identity, bool* exists);
  1790. /**
  1791. * <!-- set_pgp_keypair() -->
  1792. *
  1793. * @brief TODO
  1794. *
  1795. * @param[in] session PEP_SESSION
  1796. * @param[in] *fpr constchar
  1797. *
  1798. */
  1799. PEP_STATUS set_pgp_keypair(PEP_SESSION session, const char* fpr);
  1800. /**
  1801. * <!-- set_pEp_version() -->
  1802. *
  1803. * @brief TODO
  1804. *
  1805. * @param[in] session PEP_SESSION
  1806. * @param[in] *ident pEp_identity
  1807. * @param[in] new_ver_major unsignedint
  1808. * @param[in] new_ver_minor unsignedint
  1809. *
  1810. */
  1811. PEP_STATUS set_pEp_version(PEP_SESSION session, pEp_identity* ident, unsigned int new_ver_major, unsigned int new_ver_minor);
  1812. /**
  1813. * <!-- clear_trust_info() -->
  1814. *
  1815. * @brief TODO
  1816. *
  1817. * @param[in] session PEP_SESSION
  1818. * @param[in] *user_id constchar
  1819. * @param[in] *fpr constchar
  1820. *
  1821. */
  1822. PEP_STATUS clear_trust_info(PEP_SESSION session,
  1823. const char* user_id,
  1824. const char* fpr);
  1825. // Generally ONLY called by set_as_pEp_user, and ONLY from < 2.0 to 2.0.
  1826. /**
  1827. * <!-- upgrade_pEp_version_by_user_id() -->
  1828. *
  1829. * @brief TODO
  1830. *
  1831. * @param[in] session PEP_SESSION
  1832. * @param[in] *ident pEp_identity
  1833. * @param[in] new_ver_major unsignedint
  1834. * @param[in] new_ver_minor unsignedint
  1835. *
  1836. */
  1837. PEP_STATUS upgrade_pEp_version_by_user_id(PEP_SESSION session,
  1838. pEp_identity* ident,
  1839. unsigned int new_ver_major,
  1840. unsigned int new_ver_minor
  1841. );
  1842. // exposed for testing
  1843. /**
  1844. * <!-- set_person() -->
  1845. *
  1846. * @brief TODO
  1847. *
  1848. * @param[in] session PEP_SESSION
  1849. * @param[in] *identity pEp_identity
  1850. * @param[in] guard_transaction bool
  1851. *
  1852. */
  1853. PEP_STATUS set_person(PEP_SESSION session, pEp_identity* identity,
  1854. bool guard_transaction);
  1855. /**
  1856. * <!-- bind_own_ident_with_contact_ident() -->
  1857. *
  1858. * @brief TODO
  1859. *
  1860. * @param[in] session PEP_SESSION
  1861. * @param[in] *own_ident pEp_identity
  1862. * @param[in] *contact_ident pEp_identity
  1863. *
  1864. */
  1865. PEP_STATUS bind_own_ident_with_contact_ident(PEP_SESSION session,
  1866. pEp_identity* own_ident,
  1867. pEp_identity* contact_ident);
  1868. /**
  1869. * <!-- get_last_contacted() -->
  1870. *
  1871. * @brief TODO
  1872. *
  1873. * @param[in] session PEP_SESSION
  1874. * @param[in] **id_list identity_list
  1875. *
  1876. */
  1877. PEP_STATUS get_last_contacted(
  1878. PEP_SESSION session,
  1879. identity_list** id_list
  1880. );
  1881. /**
  1882. * <!-- get_own_ident_for_contact_id() -->
  1883. *
  1884. * @brief TODO
  1885. *
  1886. * @param[in] session PEP_SESSION
  1887. * @param[in] *contact constpEp_identity
  1888. * @param[in] **own_ident pEp_identity
  1889. *
  1890. */
  1891. PEP_STATUS get_own_ident_for_contact_id(PEP_SESSION session,
  1892. const pEp_identity* contact,
  1893. pEp_identity** own_ident);
  1894. /**
  1895. * <!-- exists_trust_entry() -->
  1896. *
  1897. * @brief TODO
  1898. *
  1899. * @param[in] session PEP_SESSION
  1900. * @param[in] *identity pEp_identity
  1901. * @param[in] *exists bool
  1902. *
  1903. */
  1904. PEP_STATUS exists_trust_entry(PEP_SESSION session, pEp_identity* identity,
  1905. bool* exists);
  1906. /**
  1907. * <!-- is_own_key() -->
  1908. *
  1909. * @brief TODO
  1910. *
  1911. * @param[in] session PEP_SESSION
  1912. * @param[in] *fpr constchar
  1913. * @param[in] *own_key bool
  1914. *
  1915. */
  1916. PEP_STATUS is_own_key(PEP_SESSION session, const char* fpr, bool* own_key);
  1917. /**
  1918. * <!-- get_identities_by_main_key_id() -->
  1919. *
  1920. * @brief TODO
  1921. *
  1922. * @param[in] session PEP_SESSION
  1923. * @param[in] *fpr constchar
  1924. * @param[in] **identities identity_list
  1925. *
  1926. */
  1927. PEP_STATUS get_identities_by_main_key_id(
  1928. PEP_SESSION session,
  1929. const char *fpr,
  1930. identity_list **identities);
  1931. /**
  1932. * <!-- sign_only() -->
  1933. *
  1934. * @brief TODO
  1935. *
  1936. * @param[in] session PEP_SESSION
  1937. * @param[in] *data constchar
  1938. * @param[in] data_size size_t
  1939. * @param[in] *fpr constchar
  1940. * @param[in] **sign char
  1941. * @param[in] *sign_size size_t
  1942. *
  1943. */
  1944. PEP_STATUS sign_only(PEP_SESSION session,
  1945. const char *data,
  1946. size_t data_size,
  1947. const char *fpr,
  1948. char **sign,
  1949. size_t *sign_size);
  1950. /**
  1951. * <!-- set_all_userids_to_own() -->
  1952. *
  1953. * @brief TODO
  1954. *
  1955. * @param[in] session PEP_SESSION
  1956. * @param[in] *id_list identity_list
  1957. *
  1958. */
  1959. PEP_STATUS set_all_userids_to_own(PEP_SESSION session,
  1960. identity_list* id_list);
  1961. /**
  1962. * <!-- has_partner_contacted_address() -->
  1963. *
  1964. * @brief TODO
  1965. *
  1966. * @param[in] session PEP_SESSION
  1967. * @param[in] *partner_id constchar
  1968. * @param[in] *own_address constchar
  1969. * @param[in] *was_contacted bool
  1970. *
  1971. */
  1972. PEP_STATUS has_partner_contacted_address(PEP_SESSION session, const char* partner_id,
  1973. const char* own_address, bool* was_contacted);
  1974. #ifdef __cplusplus
  1975. }
  1976. #endif