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.

1956 lines
65 KiB

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