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

/**
* @file key_reset.h
* @brief Functions for resetting partner key defaults and trust and mistrusting and revoking own keys,
* as well as functions to inform partners of own revoked keys and their replacements
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#ifndef KEY_RESET_H
#define KEY_RESET_H
#include "pEpEngine.h"
#include "keymanagement.h"
#include "message.h"
#include "message_api.h"
#include "cryptotech.h"
#include "keyreset_command.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* <!-- key_reset_identity() -->
*
* @brief Reset the default database status for the identity / keypair
* provided. If this corresponds to an own identity and a private key,
* also revoke the key, generate a new one, and communicate the
* reset to recently contacted pEp partners for this identity.
*
* If it does not, remove the key from the keyring; the key's
* status is completely fresh on next contact from the partner.
* If no key is provided, reset the identity default.
* Note that reset keys will be removed as defaults for all users and identities.
*
* @param[in] session session handle
* @param[in] fpr fingerprint of key to reset. If NULL, we reset the default key
* this identity if there is one, and the user default if not.
* @param[in] ident identity for which the key reset should occur. Must contain
* user_id and address. Must not be NULL.
* Note: ident->fpr field will be ignored.
*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
DYNAMIC_API PEP_STATUS key_reset_identity(
PEP_SESSION session,
pEp_identity* ident,
const char* fpr
);
/**
* <!-- key_reset_user() -->
*
* @brief Reset the default database status for the user / keypair
* provided. This will effectively perform key_reset_identity()
* each identity associated with the key and user_id, if a key is
* provided, and for each key (and all of their identities) if an fpr
* is not.
*
* If the user_id is the own user_id, an fpr MUST be provided.
* For a reset of all own user keys, call key_reset_all_own_keys() instead.
* Note that reset keys will be removed as defaults for all users and identities.
*
* @param[in] session session handle
* @param[in] user_id user_id for which the key reset should occur. If this
* is the own user_id, fpr MUST NOT be NULL.
* @param[in] fpr fingerprint of key to reset.
* If NULL, we reset all default
* keys for this user and all of its identities.
* *** However, it is forbidden to use the own user_id
* here when the fpr is NULL. For this functionality,
* call key_reset_all_own_keys ***
*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
//
DYNAMIC_API PEP_STATUS key_reset_user(
PEP_SESSION session,
const char* user_id,
const char* fpr
);
/**
* <!-- key_reset_all_own_keys() -->
*
* @brief Revoke and mistrust all own keys, generate new keys for all
* own identities, and opportunistically communicate
* key reset information to people we have recently
* contacted.
*
* @param[in] session session handle
*
* @warning HOWEVER, apps and adapters must decide if this is a reasonable state;
* since the period where no own user exists will necessarily be very short
* in most implementations, PEP_CANNOT_FIND_IDENTITY may be returned when
* there is some sort of DB corruption and we expect there to be an own user.
* Apps are responsible for deciding whether or not this is an error condition;
* one would expect that it generally is (rather than the uninitialised DB case)
*
*/
DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session);
// FIXME: Doc
// This is simply NOT SAFE for multiple passwords on the extant
// keys. Cannot be called with multiple passwords for that purpose.
/**
* <!-- key_reset_own_grouped_keys() -->
*
* @brief TODO
*
* @param[in] session session handle
*
*/
DYNAMIC_API PEP_STATUS key_reset_own_grouped_keys(PEP_SESSION session);
#ifdef __cplusplus
}
#endif
#endif