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.

585 lines
22 KiB

8 years ago
7 years ago
8 years ago
1 year ago
8 years ago
8 years ago
8 years ago
1 year ago
8 years ago
1 year ago
8 years ago
7 years ago
1 year ago
7 years ago
1 year ago
8 years ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
6 years ago
6 years ago
1 year ago
1 year ago
1 year 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
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
1 year ago
8 years ago
  1. /**
  2. * @file keymanagement.h
  3. * @brief Functions to manage keys (and identities when in relation to keys)
  4. * @license GNU General Public License 3.0 - see LICENSE.txt
  5. */
  6. #ifndef KEYMANAGEMENT_H
  7. #define KEYMANAGEMENT_H
  8. #include "pEpEngine.h"
  9. #ifdef __cplusplus
  10. extern "C" {
  11. #endif
  12. /**
  13. * <!-- update_identity() -->
  14. *
  15. * @brief Update identity information
  16. *
  17. * @param[in] session session to use
  18. * @param[in,out] identity identity information of communication partner
  19. * (identity->fpr is OUT ONLY), and at least
  20. * .address must be set.
  21. * If .username is set, it will be used to set or patch
  22. * the username record for this identity.
  23. *
  24. * @retval PEP_STATUS_OK if identity could be updated,
  25. * @retval PEP_ILLEGAL_VALUE if called with illegal inputs, including an identity
  26. * with .me set or with an own user_id specified in the
  27. * *input* (see caveats)
  28. * @retval any other value on error
  29. *
  30. * @warning at least identity->address must be a non-empty UTF-8 string as input
  31. * update_identity() never writes flags; use set_identity_flags() for
  32. * writing
  33. * this function NEVER reads the incoming fpr, only writes to it.
  34. * this function will fail if called on an identity which, with its input
  35. * values, *explicitly* indicates it is an own identity (i.e. .me is set
  36. * to true on input, or a user_id is given AND it is a known own user_id).
  37. * however, it can RETURN an own identity if this is not indicated a
  38. * priori, and in fact will do so with prejudice when not faced with a
  39. * matching default (i.e. it is forced to search by address only).
  40. * if the identity is known to be an own identity (or the caller wishes
  41. * to make it one), call myself() on the identity instead.
  42. * FIXME: is this next point accurate?
  43. * if this function returns PEP_ct_unknown or PEP_ct_key_expired in
  44. * identity->comm_type, the caller must insert the identity into the
  45. * asynchronous management implementation, so retrieve_next_identity()
  46. * will return this identity later
  47. * END FIXME
  48. *
  49. */
  50. DYNAMIC_API PEP_STATUS update_identity(
  51. PEP_SESSION session, pEp_identity * identity
  52. );
  53. // TODO: remove
  54. // initialise_own_identities () - ensures that an own identity is complete
  55. //
  56. // parameters:
  57. // session (in) session to use
  58. // my_idents (inout) identities of local user to quick-set
  59. // For these, at least .address must be set.
  60. // if no .user_id is set, AND the DB doesn't contain
  61. // a default user_id, PEP_OWN_USERID will be used and
  62. // become the perennial default for the DB.
  63. //
  64. // return value:
  65. // PEP_STATUS_OK if identity could be set,
  66. // any other value on error
  67. //
  68. // caveat:
  69. // this function does NOT generate keypairs. It is intended to
  70. // precede running of the engine on actual messages. It effectively
  71. // behaves like myself(), but when there would normally be key generation
  72. // (when there is no valid key, for example),
  73. // it instead stores an identity without keys.
  74. //
  75. // N.B. to adapter devs - this function is likely unnecessary, so please
  76. // do not put work into exposing it yet. Tickets will be filed if need be.
  77. // DYNAMIC_API PEP_STATUS initialise_own_identities(PEP_SESSION session,
  78. // identity_list* my_idents);
  79. /**
  80. * <!-- myself() -->
  81. *
  82. * @brief Ensures that an own identity is complete
  83. *
  84. * @param[in] session session to use
  85. * @param[in,out] identity identity of local user
  86. * both .address and .user_id must be set.
  87. * if .fpr is set, an attempt will be made to make
  88. * that the default key for this identity after key
  89. * validation
  90. * if .fpr is not set, key retrieval is performed
  91. * If .username is set, it will be used to set or patch
  92. * the username record for this identity.
  93. *
  94. * @retval PEP_STATUS_OK if identity could be completed or was already complete,
  95. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  96. * @retval PEP_OUT_OF_MEMORY out of memory
  97. * @retval any other value on error
  98. *
  99. * @warning If an fpr was entered and is not a valid key, the reason for failure
  100. * is immediately returned in the status and, possibly, identity->comm_type
  101. * If a default own user_id exists in the database, an alias will
  102. * be created for the default for the input user_id. The ENGINE'S default
  103. * user_id is always returned in the .user_id field
  104. * myself() NEVER elects keys from the keyring; it will only choose keys
  105. * which have been set up explicitly via myself(), or which were imported
  106. * during a first time DB setup from an OpenPGP keyring (compatibility only)
  107. * this function generates a keypair on demand; because it's synchronous
  108. * it can need a decent amount of time to return
  109. * if you need to do this asynchronous, you need to return an identity
  110. * with retrieve_next_identity() where pEp_identity.me is true
  111. *
  112. */
  113. DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
  114. /**
  115. * <!-- retrieve_next_identity() -->
  116. *
  117. * @brief Callback being called by do_keymanagement()
  118. *
  119. * @param[in] management data structure to deliver (implementation defined)
  120. *
  121. * @retval identity to check or NULL to terminate do_keymanagement()
  122. * if given identity must be created with new_identity()
  123. * the identity struct is going to the ownership of this library
  124. * it must not be freed by the callee
  125. *
  126. * @warning this callback has to block until an identity or NULL can be returned
  127. * an implementation is not provided by this library; instead it has to be
  128. * implemented by the user of this library
  129. *
  130. */
  131. typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
  132. /**
  133. * <!-- examine_identity() -->
  134. *
  135. * @brief Callback for appending to queue
  136. *
  137. * @param[in] ident identity to examine
  138. * @param[in] management data structure to deliver (implementation defined)
  139. *
  140. * @retval 0 if identity was added successfully to queue or nonzero otherwise
  141. *
  142. *
  143. */
  144. typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
  145. /**
  146. * <!-- register_examine_function() -->
  147. *
  148. * @brief Register examine_identity() callback
  149. *
  150. * @param[in] session session to use
  151. * @param[in] examine_identity examine_identity() function to register
  152. * @param[in] management data structure to deliver (implementation defined)
  153. *
  154. * @retval PEP_STATUS_OK
  155. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  156. *
  157. */
  158. DYNAMIC_API PEP_STATUS register_examine_function(
  159. PEP_SESSION session,
  160. examine_identity_t examine_identity,
  161. void *management
  162. );
  163. /**
  164. * <!-- do_keymanagement() -->
  165. *
  166. * @brief Function to be run on an extra thread
  167. *
  168. * @param[in] retrieve_next_identity pointer to retrieve_next_identity()
  169. * callback which returns at least a valid
  170. * address field in the identity struct
  171. *
  172. * @retval PEP_STATUS_OK if thread has to terminate successfully
  173. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  174. * @retval PEP_OUT_OF_MEMORY out of memory
  175. * @retval any other value on failure
  176. *
  177. * @warning to ensure proper working of this library, a thread has to be started
  178. * with this function immediately after initialization
  179. * do_keymanagement() calls retrieve_next_identity(management)
  180. * messageToSend can only be null if no transport is application based
  181. * if transport system is not used it must not be NULL
  182. *
  183. */
  184. DYNAMIC_API PEP_STATUS do_keymanagement(
  185. retrieve_next_identity_t retrieve_next_identity,
  186. void *management
  187. );
  188. /**
  189. * <!-- key_mistrusted() -->
  190. *
  191. * @brief Mark key as being compromised
  192. *
  193. * @param[in] session session to use
  194. * @param[in] ident person and key which was compromised
  195. *
  196. * @warning ident is INPUT ONLY. If you want updated trust on the identity, you'll have
  197. * to call update_identity or myself respectively after this.
  198. * N.B. If you are calling this on a key that is the identity or user default,
  199. * it will be removed as the default key for ANY identity and user for which
  200. * it is the default. Please keep in mind that the undo in undo_last_mistrust
  201. * will only undo the current identity's / it's user's default, not any
  202. * other identities which may be impacted (this will not affect most use
  203. * cases)
  204. *
  205. */
  206. DYNAMIC_API PEP_STATUS key_mistrusted(
  207. PEP_SESSION session,
  208. pEp_identity *ident
  209. );
  210. /**
  211. * <!-- trust_personal_key() -->
  212. *
  213. * @brief Mark a key as trusted for a user
  214. *
  215. * @param[in] session session to use
  216. * @param[in] ident person and key to trust in - this must not be an
  217. * own_identity in which the .me flag is set or
  218. * the user_id is an own user_id.
  219. *
  220. *
  221. * @retval PEP_STATUS_OK
  222. * @retval PEP_KEY_UNSUITABLE
  223. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  224. * @retval PEP_OUT_OF_MEMORY out of memory
  225. * @retval any other value on error
  226. *
  227. * @warning the fields user_id, address and fpr must be supplied
  228. * own identities will result in a return of PEP_ILLEGAL_VALUE.
  229. * for non-own users, this will 1) set the trust bit on its comm type in the DB,
  230. * 2) set this key as the identity default if the current identity default
  231. * is not trusted, and 3) set this key as the user default if the current
  232. * user default is not trusted.
  233. *
  234. */
  235. DYNAMIC_API PEP_STATUS trust_personal_key(
  236. PEP_SESSION session,
  237. pEp_identity *ident
  238. );
  239. /**
  240. * <!-- trust_own_key() -->
  241. *
  242. * @brief Mark a key as trusted for self, generally
  243. * used when we need to trust a public key
  244. * associated with outselves for issues like
  245. * manual key import
  246. *
  247. * @param[in] session session to use
  248. * @param[in] ident own ident containing fpr to trust
  249. *
  250. * @retval PEP_STATUS_OK
  251. * @retval PEP_KEY_UNSUITABLE
  252. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  253. * @retval PEP_OUT_OF_MEMORY out of memory
  254. * @retval any other value on error
  255. *
  256. * @warning if this is a public key only, keep in mind that if
  257. * the private part of the keypair is later added,
  258. * it will not undergo separate trust evaluation. This
  259. * is fine - even desired - as long as the semantics
  260. * of this function are understood as both trusting
  261. * the key and verifying it as an own key. This will
  262. * NEVER cause replacement of or setting of a default
  263. * *alone*. However, if a private key is ever associated
  264. * with this fpr, please keep in mind that trusting it
  265. * here makes it an eligible key for selection for
  266. * encryption later. So use this function on purpose with
  267. * an understanding of what you're doing!
  268. *
  269. */
  270. DYNAMIC_API PEP_STATUS trust_own_key(
  271. PEP_SESSION session,
  272. pEp_identity *ident
  273. );
  274. /**
  275. * <!-- key_reset_trust() -->
  276. *
  277. * @brief Reset trust bit or explicitly mistrusted status for an identity and
  278. * its accompanying key/user_id pair.
  279. *
  280. * @param[in] session session to use
  281. * @param[in] ident identity for person and key whose trust status is to be reset
  282. *
  283. * @retval PEP_STATUS_OK
  284. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  285. * @retval PEP_OUT_OF_MEMORY out of memory
  286. * @retval any other value on error
  287. *
  288. * @warning ident is INPUT ONLY. If you want updated trust on the identity, you'll have
  289. * to call update_identity or myself respectively after this.
  290. * N.B. If you are calling this on a key that is the identity or user default,
  291. * it will be removed as the default key for the identity and user (but is still
  292. * available for key election, it is just not the cached default anymore)
  293. *
  294. */
  295. DYNAMIC_API PEP_STATUS key_reset_trust(
  296. PEP_SESSION session,
  297. pEp_identity *ident
  298. );
  299. /**
  300. * <!-- own_key_is_listed() -->
  301. *
  302. * @brief Returns true id key is listed as own key
  303. *
  304. * @param[in] session session to use
  305. * @param[in] fpr fingerprint of key to test
  306. * @param[out] listed flags if key is own
  307. *
  308. * @retval PEP_STATUS_OK
  309. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  310. * @retval any other value on error
  311. *
  312. */
  313. DYNAMIC_API PEP_STATUS own_key_is_listed(
  314. PEP_SESSION session,
  315. const char *fpr,
  316. bool *listed
  317. );
  318. /**
  319. * <!-- _own_identities_retrieve() -->
  320. *
  321. * @brief Retrieve all own identities
  322. *
  323. * @param[in] session session to use
  324. * @param[out] own_identities list of own identities
  325. * @param[in] excluded_flags flags to exclude from results
  326. *
  327. * @retval PEP_STATUS_OK
  328. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  329. * @retval PEP_OUT_OF_MEMORY out of memory
  330. * @retval any other value on error
  331. *
  332. * @warning the ownership of the copy of own_identities goes to the caller
  333. *
  334. */
  335. DYNAMIC_API PEP_STATUS _own_identities_retrieve(
  336. PEP_SESSION session,
  337. identity_list **own_identities,
  338. identity_flags_t excluded_flags
  339. );
  340. /**
  341. * <!-- own_identities_retrieve() -->
  342. *
  343. * @brief Retrieve all own identities
  344. *
  345. * @param[in] session session to use
  346. * @param[out] own_identities list of own identities
  347. *
  348. * @retval PEP_STATUS_OK
  349. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  350. * @retval PEP_OUT_OF_MEMORY out of memory
  351. * @retval any other value on error
  352. *
  353. * @warning the ownership of the copy of own_identities goes to the caller
  354. *
  355. */
  356. DYNAMIC_API PEP_STATUS own_identities_retrieve(
  357. PEP_SESSION session,
  358. identity_list **own_identities
  359. );
  360. /**
  361. * <!-- _own_keys_retrieve() -->
  362. *
  363. * @brief Retrieve all flagged keypair fingerprints
  364. *
  365. * @param[in] session session to use
  366. * @param[out] keylist list of fingerprints
  367. * @param[in] excluded_flags flags to exclude from results
  368. * @param[in] private_only if true, return only fprs for
  369. * which we have the secret part
  370. * @retval PEP_STATUS_OK
  371. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  372. * @retval PEP_OUT_OF_MEMORY out of memory
  373. * @retval any other value on error
  374. *
  375. * @warning the ownership of the list goes to the caller
  376. *
  377. */
  378. DYNAMIC_API PEP_STATUS _own_keys_retrieve(
  379. PEP_SESSION session,
  380. stringlist_t **keylist,
  381. identity_flags_t excluded_flags,
  382. bool private_only
  383. );
  384. /**
  385. * <!-- own_keys_retrieve() -->
  386. *
  387. * @brief Retrieve all flagged public/private keypair fingerprints
  388. *
  389. * @param[in] session session to use
  390. * @param[out] keylist list of fingerprints
  391. *
  392. * @retval PEP_STATUS_OK
  393. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  394. * @retval PEP_OUT_OF_MEMORY out of memory
  395. * @retval any other value on error
  396. *
  397. * @warning the ownership of the list goes to the caller
  398. * this function does not return keys without a private key part
  399. *
  400. */
  401. DYNAMIC_API PEP_STATUS own_keys_retrieve(
  402. PEP_SESSION session,
  403. stringlist_t **keylist
  404. );
  405. /**
  406. * <!-- set_comm_partner_key() -->
  407. *
  408. * @brief Mark a key the default for a comm partner
  409. *
  410. * @param[in] session session to use
  411. * @param[in,out] identity partner identity this key is used for
  412. * @param[in] fpr fingerprint of the key to set as the identity default
  413. *
  414. * @retval PEP_STATUS_OK
  415. * @retval PEP_KEY_UNSUITABLE
  416. * @retval PEP_ILLEGAL_VALUE illegal parameter values, including if update_identity determines this is an own identity
  417. * @retval PEP_OUT_OF_MEMORY out of memory
  418. * @retval any other value on error
  419. *
  420. * @warning the key has to be in the key ring already
  421. * identity->address must be set to valid data
  422. * update_identity() is called by this function and will create a TOFU user_id + new entry if none is indicated
  423. * and heuristic fails to match extant identity
  424. * identity->fpr will NOT be updated with the set identity fpr; it is only in,out because update_identity() is called
  425. * before setting it.
  426. *
  427. */
  428. DYNAMIC_API PEP_STATUS set_comm_partner_key(PEP_SESSION session,
  429. pEp_identity *identity,
  430. const char* fpr);
  431. /**
  432. * <!-- set_own_key() -->
  433. *
  434. * @brief Mark a key as own key
  435. *
  436. * @param[in] session session to use
  437. * @param[in,out] me own identity this key is used for
  438. * @param[in] fpr fingerprint of the key to mark as own key
  439. *
  440. * @retval PEP_STATUS_OK
  441. * @retval PEP_KEY_UNSUITABLE
  442. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  443. * @retval PEP_OUT_OF_MEMORY out of memory
  444. * @retval any other value on error
  445. *
  446. * @warning the key has to be in the key ring already
  447. * me->address, me->user_id and me->username must be set to valid data
  448. * myself() is called by set_own_key() without key generation
  449. * me->flags are ignored
  450. * me->address must not be an alias
  451. * me->fpr will be ignored and replaced by fpr, but
  452. * caller MUST surrender ownership of the me->fpr reference, because
  453. * it may be freed and replaced within the myself call. caller owns
  454. * me->fpr memory again upon return.
  455. *
  456. */
  457. DYNAMIC_API PEP_STATUS set_own_key(
  458. PEP_SESSION session,
  459. pEp_identity *me,
  460. const char *fpr
  461. );
  462. /**
  463. * <!-- set_own_imported_key() -->
  464. *
  465. * @brief Mark a key as an own default key, test to be sure the private key is
  466. * present and can be used, and set or unset the sticky bit as indicated by the boolean
  467. * value. The sticky bit is intended to tell the engine to not automatically remove this
  468. * key as a default through protocols like sync, for example.
  469. *
  470. * @param[in] session session to use
  471. * @param[in,out] me own identity this key is used for
  472. * @param[in] fpr fingerprint of the key to mark as own key
  473. * @param[in] sticky boolean, true if we should set a sticky bit so
  474. * it will not be automatically reset by sync and should
  475. * win sync key elections if no other competing key
  476. * for the same identity has its sticky bit set,
  477. * false otherwise
  478. *
  479. * @warning the key has to be in the key ring already
  480. * me->address, me->user_id and me->username must be set to valid data
  481. * myself() is called by set_own_key() from within this call without key generation
  482. * me->flags are ignored
  483. * me->address must not be an alias
  484. * me->fpr will be ignored and replaced by fpr, but
  485. * caller MUST surrender ownership of the me->fpr reference, because
  486. * it may be freed and replaced within the myself call. caller owns
  487. * me->fpr memory again upon return.
  488. * CAN GENERATE A PASSPHRASE REQUEST
  489. *
  490. */
  491. DYNAMIC_API PEP_STATUS set_own_imported_key(
  492. PEP_SESSION session,
  493. pEp_identity* me,
  494. const char* fpr,
  495. bool sticky
  496. );
  497. //
  498. // clean_own_key_defaults()
  499. //
  500. // Remove any broken, unrenewable expired, or revoked
  501. // own keys from identity and user defaults in the database.
  502. //
  503. // parameters:
  504. // session (in) session to use
  505. //
  506. // return value:
  507. // PEP_STATUS_OK if all went well
  508. // PEP_PASSPHRASE_REQUIRED if a key needs to be renewed
  509. // but cached passphrase isn't present
  510. // PEP_WRONG_PASSPHRASE if passphrase required for expired key renewal
  511. // but passphrase is the wrong one
  512. // Otherwise, database and keyring errors as appropriate
  513. //
  514. /**
  515. * <!-- clean_own_key_defaults() -->
  516. *
  517. * @brief Remove any broken, unrenewable expired, or revoked
  518. * own keys from identity and user defaults in the database.
  519. *
  520. * @param[in] session session handle
  521. *
  522. * @retval PEP_STATUS_OK if all went well
  523. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  524. *
  525. * @retval PEP_PASSPHRASE_REQUIRED if a key needs to be renewed
  526. * but cached passphrase isn't present
  527. * @retval PEP_WRONG_PASSPHRASE if passphrase required for expired key renewal
  528. * but passphrase is the wrong one
  529. * @retval Otherwise, database and keyring errors as appropriate
  530. *
  531. *
  532. */
  533. DYNAMIC_API PEP_STATUS clean_own_key_defaults(PEP_SESSION session);
  534. #ifdef __cplusplus
  535. }
  536. #endif
  537. #endif