p≡p engine fork for my own dirty testing of stuff
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.

316 lines
12 KiB

10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
  1. /**
  2. * @file key_reset.h
  3. * @brief Functions for resetting partner key defaults and trust and mistrusting and revoking own keys,
  4. * as well as functions to inform partners of own revoked keys and their replacements
  5. * @license GNU General Public License 3.0 - see LICENSE.txt
  6. */
  7. #ifndef KEY_RESET_H
  8. #define KEY_RESET_H
  9. #include "pEpEngine.h"
  10. #include "keymanagement.h"
  11. #include "message.h"
  12. #include "message_api.h"
  13. #include "cryptotech.h"
  14. #include "keyreset_command.h"
  15. #ifdef __cplusplus
  16. extern "C" {
  17. #endif
  18. /**
  19. * <!-- key_reset_identity() -->
  20. *
  21. * @brief Reset the default database status for the identity / keypair
  22. * provided. If this corresponds to an own identity and a private key,
  23. * also revoke the key, generate a new one, and communicate the
  24. * reset to recently contacted pEp partners for this identity.
  25. *
  26. * If it does not, remove the key from the keyring; the key's
  27. * status is completely fresh on next contact from the partner.
  28. * If no key is provided, reset the identity default.
  29. * Note that reset keys will be removed as defaults for all users and identities.
  30. *
  31. * @param[in] session session handle
  32. * @param[in] fpr fingerprint of key to reset. If NULL, we reset the default key
  33. * this identity if there is one, and the user default if not.
  34. * @param[in] ident identity for which the key reset should occur. Must contain
  35. * user_id and address. Must not be NULL.
  36. * Note: ident->fpr field will be ignored.
  37. *
  38. *
  39. * @retval PEP_STATUS_OK
  40. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  41. * @retval PEP_OUT_OF_MEMORY out of memory
  42. * @retval any other value on error
  43. */
  44. DYNAMIC_API PEP_STATUS key_reset_identity(
  45. PEP_SESSION session,
  46. pEp_identity* ident,
  47. const char* fpr
  48. );
  49. /**
  50. * <!-- key_reset_user() -->
  51. *
  52. * @brief Reset the default database status for the user / keypair
  53. * provided. This will effectively perform key_reset_identity()
  54. * each identity associated with the key and user_id, if a key is
  55. * provided, and for each key (and all of their identities) if an fpr
  56. * is not.
  57. *
  58. * If the user_id is the own user_id, an fpr MUST be provided.
  59. * For a reset of all own user keys, call key_reset_all_own_keys() instead.
  60. * Note that reset keys will be removed as defaults for all users and identities.
  61. *
  62. * @param[in] session session handle
  63. * @param[in] user_id user_id for which the key reset should occur. If this
  64. * is the own user_id, fpr MUST NOT be NULL.
  65. * @param[in] fpr fingerprint of key to reset.
  66. * If NULL, we reset all default
  67. * keys for this user and all of its identities.
  68. * *** However, it is forbidden to use the own user_id
  69. * here when the fpr is NULL. For this functionality,
  70. * call key_reset_all_own_keys ***
  71. *
  72. *
  73. * @retval PEP_STATUS_OK
  74. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  75. * @retval PEP_OUT_OF_MEMORY out of memory
  76. * @retval any other value on error
  77. */
  78. //
  79. DYNAMIC_API PEP_STATUS key_reset_user(
  80. PEP_SESSION session,
  81. const char* user_id,
  82. const char* fpr
  83. );
  84. /**
  85. * <!-- key_reset_all_own_keys() -->
  86. *
  87. * @brief Revoke and mistrust all own keys, generate new keys for all
  88. * own identities, and opportunistically communicate
  89. * key reset information to people we have recently
  90. * contacted.
  91. *
  92. * @param[in] session session handle
  93. *
  94. * @warning HOWEVER, apps and adapters must decide if this is a reasonable state;
  95. * since the period where no own user exists will necessarily be very short
  96. * in most implementations, PEP_CANNOT_FIND_IDENTITY may be returned when
  97. * there is some sort of DB corruption and we expect there to be an own user.
  98. * Apps are responsible for deciding whether or not this is an error condition;
  99. * one would expect that it generally is (rather than the uninitialised DB case)
  100. *
  101. */
  102. DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session);
  103. // FIXME: Doc
  104. // This is simply NOT SAFE for multiple passwords on the extant
  105. // keys. Cannot be called with multiple passwords for that purpose.
  106. /**
  107. * <!-- key_reset_own_grouped_keys() -->
  108. *
  109. * @brief TODO
  110. *
  111. * @param[in] session session handle
  112. *
  113. */
  114. DYNAMIC_API PEP_STATUS key_reset_own_grouped_keys(PEP_SESSION session);
  115. /**
  116. * <!-- key_reset() -->
  117. *
  118. * @brief Reset the database status for a key, removing all trust information
  119. * and default database connections. For own keys, also revoke the key
  120. * and communicate the revocation and new key to partners we have sent
  121. * mail to recently from the specific identity (i.e. address/user_id)
  122. * that contacted them. We also in this case set up information so that
  123. * if someone we mail uses the wrong key and wasn't yet contacted,
  124. * we can send them the reset information from the right address.
  125. * For non-own keys, also remove key from the keyring.
  126. *
  127. * Can be called manually or through another protocol.
  128. *
  129. * @param[in] session session handle
  130. * @param[in] fpr fingerprint of key to reset. If NULL and ident is NULL,
  131. * we reset all keys for the own user. If NULL and ident is
  132. * an own identity, we reset the default key for that
  133. * identity. If that own identity has no default key, we
  134. * reset the user default.
  135. * if it is NULL and there is a non-own identity, we will reset
  136. * the default key for this identity if present, and user if not.
  137. * @param[in] ident identity for which the key reset should occur.
  138. * if NULL and fpr is non-NULL, we'll reset the key for all
  139. * associated identities. If both ident and fpr are NULL, see
  140. * the fpr arg documentation.
  141. * ***IF there is an ident, it must have a user_id.***
  142. * Note: ident->fpr is always ignored
  143. * Caveat: this is now used in large part for internal calls.
  144. * external apps should call key_reset_identity and key_reset_userdata
  145. * and this function should probably be removed from the dynamic api
  146. *
  147. *
  148. * @retval PEP_STATUS_OK
  149. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  150. * @retval PEP_OUT_OF_MEMORY out of memory
  151. * @retval any other value on error
  152. */
  153. PEP_STATUS key_reset(
  154. PEP_SESSION session,
  155. const char* fpr,
  156. pEp_identity* ident
  157. );
  158. /*
  159. PEP_STATUS key_reset_own_and_deliver_revocations(PEP_SESSION session,
  160. identity_list** own_identities,
  161. stringlist_t** revocations,
  162. stringlist_t** keys);
  163. */
  164. /**
  165. * <!-- has_key_reset_been_sent() -->
  166. *
  167. * @brief TODO
  168. *
  169. * @param[in] session session handle
  170. * @param[in] from_addr const char*
  171. * @param[in] user_id const char*
  172. * @param[in] revoked_fpr const char*
  173. * @param[in] contacted bool*
  174. *
  175. * @retval PEP_STATUS_OK
  176. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  177. * @retval any other value on error
  178. */
  179. PEP_STATUS has_key_reset_been_sent(
  180. PEP_SESSION session,
  181. const char* from_addr,
  182. const char* user_id,
  183. const char* revoked_fpr,
  184. bool* contacted);
  185. /**
  186. * <!-- set_reset_contact_notified() -->
  187. *
  188. * @brief TODO
  189. *
  190. * @param[in] session session handle
  191. * @param[in] own_address const char*
  192. * @param[in] revoke_fpr const char*
  193. * @param[in] contact_id const char*
  194. *
  195. * @retval PEP_STATUS_OK
  196. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  197. * @retval PEP_UNKNOWN_DB_ERROR
  198. */
  199. PEP_STATUS set_reset_contact_notified(
  200. PEP_SESSION session,
  201. const char* own_address,
  202. const char* revoke_fpr,
  203. const char* contact_id
  204. );
  205. /**
  206. * <!-- receive_key_reset() -->
  207. *
  208. * @brief TODO
  209. *
  210. * @param[in] session session handle
  211. * @param[in] reset_msg message*
  212. *
  213. *
  214. * @retval PEP_STATUS_OK
  215. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  216. * @retval PEP_OUT_OF_MEMORY out of memory
  217. * @retval PEP_MALFORMED_KEY_RESET_MSG
  218. * @retval PEP_KEY_NOT_RESET
  219. * @retval PEP_UNKNOWN_ERROR
  220. * @retval any other value on error
  221. * */
  222. PEP_STATUS receive_key_reset(PEP_SESSION session,
  223. message* reset_msg);
  224. /**
  225. * <!-- create_standalone_key_reset_message() -->
  226. *
  227. * @brief TODO
  228. *
  229. * @param[in] session session handle
  230. * @param[in] dst message**
  231. * @param[in] own_identity pEp_identity*
  232. * @param[in] recip pEp_identity*
  233. * @param[in] old_fpr const char*
  234. * @param[in] new_fpr const char*
  235. *
  236. * @retval PEP_STATUS_OK
  237. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  238. * @retval PEP_UNKNOWN_ERROR
  239. * @retval any other value on error
  240. */
  241. PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
  242. message** dst,
  243. pEp_identity* own_identity,
  244. pEp_identity* recip,
  245. const char* old_fpr,
  246. const char* new_fpr);
  247. /**
  248. * <!-- send_key_reset_to_recents() -->
  249. *
  250. * @brief TODO
  251. *
  252. * @param[in] session session handle
  253. * @param[in] from_ident pEp_identity*
  254. * @param[in] old_fpr const char*
  255. * @param[in] new_fpr const char*
  256. *
  257. * @retval PEP_STATUS_OK
  258. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  259. * @retval PEP_SYNC_NO_MESSAGE_SEND_CALLBACK
  260. * @retval any other value on error
  261. */
  262. PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
  263. pEp_identity* from_ident,
  264. const char* old_fpr,
  265. const char* new_fpr);
  266. /**
  267. * <!-- key_reset_commands_to_PER() -->
  268. *
  269. * @brief TODO
  270. *
  271. * @param[in] command_list const keyreset_command_list*
  272. * @param[in] cmds char**
  273. * @param[in] size size_t*
  274. *
  275. * @retval PEP_STATUS_OK
  276. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  277. * @retval any other value on error
  278. */
  279. PEP_STATUS key_reset_commands_to_PER(const keyreset_command_list *command_list, char **cmds, size_t *size);
  280. /**
  281. * <!-- PER_to_key_reset_commands() -->
  282. *
  283. * @brief TODO
  284. *
  285. * @param[in] cmds const char*
  286. * @param[in] size size_t
  287. * @param[in] command_list keyreset_command_list**
  288. *
  289. * @retval PEP_STATUS_OK
  290. * @retval PEP_ILLEGAL_VALUE illegal parameter values
  291. * @retval any other value on error
  292. */
  293. PEP_STATUS PER_to_key_reset_commands(const char *cmds, size_t size, keyreset_command_list **command_list);
  294. #ifdef __cplusplus
  295. }
  296. #endif
  297. #endif