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.

129 lines
4.7 KiB

1 year ago
1 year ago
1 year 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. #ifdef __cplusplus
  116. }
  117. #endif
  118. #endif