Merge remote-tracking branch 'psa/pr/57' into feature-psa
This commit is contained in:
Gilles Peskine
itayzafrir
commit
e584ccb6fd
1 changed files with 242 additions and 207 deletions
|
|
@ -45,217 +45,252 @@ extern "C" {
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
#if defined(PSA_SUCCESS)
|
||||||
|
/* If PSA_SUCCESS is defined, assume that PSA crypto is being used
|
||||||
|
* together with PSA IPC, which also defines the identifier
|
||||||
|
* PSA_SUCCESS. We must not define PSA_SUCCESS ourselves in that case;
|
||||||
|
* the other error code names don't clash. Also define psa_status_t as
|
||||||
|
* an alias for the type used by PSA IPC. This is a temporary hack
|
||||||
|
* until we unify error reporting in PSA IPC and PSA crypo.
|
||||||
|
*
|
||||||
|
* Note that psa_defs.h must be included before this header!
|
||||||
|
*/
|
||||||
|
typedef psa_error_t psa_status_t;
|
||||||
|
|
||||||
|
#else /* defined(PSA_SUCCESS) */
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \brief Function return status.
|
* \brief Function return status.
|
||||||
*
|
*
|
||||||
* Zero indicates success, anything else indicates an error.
|
* This is either #PSA_SUCCESS (which is zero), indicating success,
|
||||||
|
* or a nonzero value indicating that an error occurred. Errors are
|
||||||
|
* encoded as one of the \c PSA_ERROR_xxx values defined here.
|
||||||
*/
|
*/
|
||||||
typedef enum {
|
typedef int32_t psa_status_t;
|
||||||
/** The action was completed successfully. */
|
|
||||||
PSA_SUCCESS = 0,
|
/** The action was completed successfully. */
|
||||||
/** The requested operation or a parameter is not supported
|
#define PSA_SUCCESS ((psa_status_t)0)
|
||||||
* by this implementation.
|
|
||||||
*
|
#endif /* !defined(PSA_SUCCESS) */
|
||||||
* Implementations should return this error code when an enumeration
|
|
||||||
* parameter such as a key type, algorithm, etc. is not recognized.
|
/** The requested operation or a parameter is not supported
|
||||||
* If a combination of parameters is recognized and identified as
|
* by this implementation.
|
||||||
* not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */
|
*
|
||||||
PSA_ERROR_NOT_SUPPORTED,
|
* Implementations should return this error code when an enumeration
|
||||||
/** The requested action is denied by a policy.
|
* parameter such as a key type, algorithm, etc. is not recognized.
|
||||||
*
|
* If a combination of parameters is recognized and identified as
|
||||||
* Implementations should return this error code when the parameters
|
* not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */
|
||||||
* are recognized as valid and supported, and a policy explicitly
|
#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)1)
|
||||||
* denies the requested operation.
|
|
||||||
*
|
/** The requested action is denied by a policy.
|
||||||
* If a subset of the parameters of a function call identify a
|
*
|
||||||
* forbidden operation, and another subset of the parameters are
|
* Implementations should return this error code when the parameters
|
||||||
* not valid or not supported, it is unspecified whether the function
|
* are recognized as valid and supported, and a policy explicitly
|
||||||
* returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or
|
* denies the requested operation.
|
||||||
* #PSA_ERROR_INVALID_ARGUMENT. */
|
*
|
||||||
PSA_ERROR_NOT_PERMITTED,
|
* If a subset of the parameters of a function call identify a
|
||||||
/** An output buffer is too small.
|
* forbidden operation, and another subset of the parameters are
|
||||||
*
|
* not valid or not supported, it is unspecified whether the function
|
||||||
* Applications can call the `PSA_xxx_SIZE` macro listed in the function
|
* returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or
|
||||||
* description to determine a sufficient buffer size.
|
* #PSA_ERROR_INVALID_ARGUMENT. */
|
||||||
*
|
#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)2)
|
||||||
* Implementations should preferably return this error code only
|
|
||||||
* in cases when performing the operation with a larger output
|
/** An output buffer is too small.
|
||||||
* buffer would succeed. However implementations may return this
|
*
|
||||||
* error if a function has invalid or unsupported parameters in addition
|
* Applications can call the `PSA_xxx_SIZE` macro listed in the function
|
||||||
* to the parameters that determine the necessary output buffer size. */
|
* description to determine a sufficient buffer size.
|
||||||
PSA_ERROR_BUFFER_TOO_SMALL,
|
*
|
||||||
/** A slot is occupied, but must be empty to carry out the
|
* Implementations should preferably return this error code only
|
||||||
* requested action.
|
* in cases when performing the operation with a larger output
|
||||||
*
|
* buffer would succeed. However implementations may return this
|
||||||
* If the slot number is invalid (i.e. the requested action could
|
* error if a function has invalid or unsupported parameters in addition
|
||||||
* not be performed even after erasing the slot's content),
|
* to the parameters that determine the necessary output buffer size. */
|
||||||
* implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
|
#define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)3)
|
||||||
PSA_ERROR_OCCUPIED_SLOT,
|
|
||||||
/** A slot is empty, but must be occupied to carry out the
|
/** A slot is occupied, but must be empty to carry out the
|
||||||
* requested action.
|
* requested action.
|
||||||
*
|
*
|
||||||
* If the slot number is invalid (i.e. the requested action could
|
* If the slot number is invalid (i.e. the requested action could
|
||||||
* not be performed even after creating appropriate content in the slot),
|
* not be performed even after erasing the slot's content),
|
||||||
* implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
|
* implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
|
||||||
PSA_ERROR_EMPTY_SLOT,
|
#define PSA_ERROR_OCCUPIED_SLOT ((psa_status_t)4)
|
||||||
/** The requested action cannot be performed in the current state.
|
|
||||||
*
|
/** A slot is empty, but must be occupied to carry out the
|
||||||
* Multipart operations return this error when one of the
|
* requested action.
|
||||||
* functions is called out of sequence. Refer to the function
|
*
|
||||||
* descriptions for permitted sequencing of functions.
|
* If the slot number is invalid (i.e. the requested action could
|
||||||
*
|
* not be performed even after creating appropriate content in the slot),
|
||||||
* Implementations shall not return this error code to indicate
|
* implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
|
||||||
* that a key slot is occupied when it needs to be free or vice versa,
|
#define PSA_ERROR_EMPTY_SLOT ((psa_status_t)5)
|
||||||
* but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
|
|
||||||
* as applicable. */
|
/** The requested action cannot be performed in the current state.
|
||||||
PSA_ERROR_BAD_STATE,
|
*
|
||||||
/** The parameters passed to the function are invalid.
|
* Multipart operations return this error when one of the
|
||||||
*
|
* functions is called out of sequence. Refer to the function
|
||||||
* Implementations may return this error any time a parameter or
|
* descriptions for permitted sequencing of functions.
|
||||||
* combination of parameters are recognized as invalid.
|
*
|
||||||
*
|
* Implementations shall not return this error code to indicate
|
||||||
* Implementations shall not return this error code to indicate
|
* that a key slot is occupied when it needs to be free or vice versa,
|
||||||
* that a key slot is occupied when it needs to be free or vice versa,
|
* but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
|
||||||
* but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
|
* as applicable. */
|
||||||
* as applicable. */
|
#define PSA_ERROR_BAD_STATE ((psa_status_t)6)
|
||||||
PSA_ERROR_INVALID_ARGUMENT,
|
|
||||||
/** There is not enough runtime memory.
|
/** The parameters passed to the function are invalid.
|
||||||
*
|
*
|
||||||
* If the action is carried out across multiple security realms, this
|
* Implementations may return this error any time a parameter or
|
||||||
* error can refer to available memory in any of the security realms. */
|
* combination of parameters are recognized as invalid.
|
||||||
PSA_ERROR_INSUFFICIENT_MEMORY,
|
*
|
||||||
/** There is not enough persistent storage.
|
* Implementations shall not return this error code to indicate
|
||||||
*
|
* that a key slot is occupied when it needs to be free or vice versa,
|
||||||
* Functions that modify the key storage return this error code if
|
* but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
|
||||||
* there is insufficient storage space on the host media. In addition,
|
* as applicable. */
|
||||||
* many functions that do not otherwise access storage may return this
|
#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)7)
|
||||||
* error code if the implementation requires a mandatory log entry for
|
|
||||||
* the requested action and the log storage space is full. */
|
/** There is not enough runtime memory.
|
||||||
PSA_ERROR_INSUFFICIENT_STORAGE,
|
*
|
||||||
/** There was a communication failure inside the implementation.
|
* If the action is carried out across multiple security realms, this
|
||||||
*
|
* error can refer to available memory in any of the security realms. */
|
||||||
* This can indicate a communication failure between the application
|
#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)8)
|
||||||
* and an external cryptoprocessor or between the cryptoprocessor and
|
|
||||||
* an external volatile or persistent memory. A communication failure
|
/** There is not enough persistent storage.
|
||||||
* may be transient or permanent depending on the cause.
|
*
|
||||||
*
|
* Functions that modify the key storage return this error code if
|
||||||
* \warning If a function returns this error, it is undetermined
|
* there is insufficient storage space on the host media. In addition,
|
||||||
* whether the requested action has completed or not. Implementations
|
* many functions that do not otherwise access storage may return this
|
||||||
* should return #PSA_SUCCESS on successful completion whenver
|
* error code if the implementation requires a mandatory log entry for
|
||||||
* possible, however functions may return #PSA_ERROR_COMMUNICATION_FAILURE
|
* the requested action and the log storage space is full. */
|
||||||
* if the requested action was completed successfully in an external
|
#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)9)
|
||||||
* cryptoprocessor but there was a breakdown of communication before
|
|
||||||
* the cryptoprocessor could report the status to the application.
|
/** There was a communication failure inside the implementation.
|
||||||
*/
|
*
|
||||||
PSA_ERROR_COMMUNICATION_FAILURE,
|
* This can indicate a communication failure between the application
|
||||||
/** There was a storage failure that may have led to data loss.
|
* and an external cryptoprocessor or between the cryptoprocessor and
|
||||||
*
|
* an external volatile or persistent memory. A communication failure
|
||||||
* This error indicates that some persistent storage is corrupted.
|
* may be transient or permanent depending on the cause.
|
||||||
* It should not be used for a corruption of volatile memory
|
*
|
||||||
* (use #PSA_ERROR_TAMPERING_DETECTED), for a communication error
|
* \warning If a function returns this error, it is undetermined
|
||||||
* between the cryptoprocessor and its external storage (use
|
* whether the requested action has completed or not. Implementations
|
||||||
* #PSA_ERROR_COMMUNICATION_FAILURE), or when the storage is
|
* should return #PSA_SUCCESS on successful completion whenver
|
||||||
* in a valid state but is full (use #PSA_ERROR_INSUFFICIENT_STORAGE).
|
* possible, however functions may return #PSA_ERROR_COMMUNICATION_FAILURE
|
||||||
*
|
* if the requested action was completed successfully in an external
|
||||||
* Note that a storage failure does not indicate that any data that was
|
* cryptoprocessor but there was a breakdown of communication before
|
||||||
* previously read is invalid. However this previously read data may no
|
* the cryptoprocessor could report the status to the application.
|
||||||
* longer be readable from storage.
|
*/
|
||||||
*
|
#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)10)
|
||||||
* When a storage failure occurs, it is no longer possible to ensure
|
|
||||||
* the global integrity of the keystore. Depending on the global
|
/** There was a storage failure that may have led to data loss.
|
||||||
* integrity guarantees offered by the implementation, access to other
|
*
|
||||||
* data may or may not fail even if the data is still readable but
|
* This error indicates that some persistent storage is corrupted.
|
||||||
* its integrity canont be guaranteed.
|
* It should not be used for a corruption of volatile memory
|
||||||
*
|
* (use #PSA_ERROR_TAMPERING_DETECTED), for a communication error
|
||||||
* Implementations should only use this error code to report a
|
* between the cryptoprocessor and its external storage (use
|
||||||
* permanent storage corruption. However application writers should
|
* #PSA_ERROR_COMMUNICATION_FAILURE), or when the storage is
|
||||||
* keep in mind that transient errors while reading the storage may be
|
* in a valid state but is full (use #PSA_ERROR_INSUFFICIENT_STORAGE).
|
||||||
* reported using this error code. */
|
*
|
||||||
PSA_ERROR_STORAGE_FAILURE,
|
* Note that a storage failure does not indicate that any data that was
|
||||||
/** A hardware failure was detected.
|
* previously read is invalid. However this previously read data may no
|
||||||
*
|
* longer be readable from storage.
|
||||||
* A hardware failure may be transient or permanent depending on the
|
*
|
||||||
* cause. */
|
* When a storage failure occurs, it is no longer possible to ensure
|
||||||
PSA_ERROR_HARDWARE_FAILURE,
|
* the global integrity of the keystore. Depending on the global
|
||||||
/** A tampering attempt was detected.
|
* integrity guarantees offered by the implementation, access to other
|
||||||
*
|
* data may or may not fail even if the data is still readable but
|
||||||
* If an application receives this error code, there is no guarantee
|
* its integrity canont be guaranteed.
|
||||||
* that previously accessed or computed data was correct and remains
|
*
|
||||||
* confidential. Applications should not perform any security function
|
* Implementations should only use this error code to report a
|
||||||
* and should enter a safe failure state.
|
* permanent storage corruption. However application writers should
|
||||||
*
|
* keep in mind that transient errors while reading the storage may be
|
||||||
* Implementations may return this error code if they detect an invalid
|
* reported using this error code. */
|
||||||
* state that cannot happen during normal operation and that indicates
|
#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)11)
|
||||||
* that the implementation's security guarantees no longer hold. Depending
|
|
||||||
* on the implementation architecture and on its security and safety goals,
|
/** A hardware failure was detected.
|
||||||
* the implementation may forcibly terminate the application.
|
*
|
||||||
*
|
* A hardware failure may be transient or permanent depending on the
|
||||||
* This error code is intended as a last resort when a security breach
|
* cause. */
|
||||||
* is detected and it is unsure whether the keystore data is still
|
#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)12)
|
||||||
* protected. Implementations shall only return this error code
|
|
||||||
* to report an alarm from a tampering detector, to indicate that
|
/** A tampering attempt was detected.
|
||||||
* the confidentiality of stored data can no longer be guaranteed,
|
*
|
||||||
* or to indicate that the integrity of previously returned data is now
|
* If an application receives this error code, there is no guarantee
|
||||||
* considered compromised. Implementations shall not use this error code
|
* that previously accessed or computed data was correct and remains
|
||||||
* to indicate a hardware failure that merely makes it impossible to
|
* confidential. Applications should not perform any security function
|
||||||
* perform the requested operation (use #PSA_ERROR_COMMUNICATION_FAILURE,
|
* and should enter a safe failure state.
|
||||||
* #PSA_ERROR_STORAGE_FAILURE, #PSA_ERROR_HARDWARE_FAILURE,
|
*
|
||||||
* #PSA_ERROR_INSUFFICIENT_ENTROPY or other applicable error code
|
* Implementations may return this error code if they detect an invalid
|
||||||
* instead).
|
* state that cannot happen during normal operation and that indicates
|
||||||
*
|
* that the implementation's security guarantees no longer hold. Depending
|
||||||
* This error indicates an attack against the application. Implementations
|
* on the implementation architecture and on its security and safety goals,
|
||||||
* shall not return this error code as a consequence of the behavior of
|
* the implementation may forcibly terminate the application.
|
||||||
* the application itself. */
|
*
|
||||||
PSA_ERROR_TAMPERING_DETECTED,
|
* This error code is intended as a last resort when a security breach
|
||||||
/** There is not enough entropy to generate random data needed
|
* is detected and it is unsure whether the keystore data is still
|
||||||
* for the requested action.
|
* protected. Implementations shall only return this error code
|
||||||
*
|
* to report an alarm from a tampering detector, to indicate that
|
||||||
* This error indicates a failure of a hardware random generator.
|
* the confidentiality of stored data can no longer be guaranteed,
|
||||||
* Application writers should note that this error can be returned not
|
* or to indicate that the integrity of previously returned data is now
|
||||||
* only by functions whose purpose is to generate random data, such
|
* considered compromised. Implementations shall not use this error code
|
||||||
* as key, IV or nonce generation, but also by functions that execute
|
* to indicate a hardware failure that merely makes it impossible to
|
||||||
* an algorithm with a randomized result, as well as functions that
|
* perform the requested operation (use #PSA_ERROR_COMMUNICATION_FAILURE,
|
||||||
* use randomization of intermediate computations as a countermeasure
|
* #PSA_ERROR_STORAGE_FAILURE, #PSA_ERROR_HARDWARE_FAILURE,
|
||||||
* to certain attacks.
|
* #PSA_ERROR_INSUFFICIENT_ENTROPY or other applicable error code
|
||||||
*
|
* instead).
|
||||||
* Implementations should avoid returning this error after psa_crypto_init()
|
*
|
||||||
* has succeeded. Implementations should generate sufficient
|
* This error indicates an attack against the application. Implementations
|
||||||
* entropy during initialization and subsequently use a cryptographically
|
* shall not return this error code as a consequence of the behavior of
|
||||||
* secure pseudorandom generator (PRNG). However implementations may return
|
* the application itself. */
|
||||||
* this error at any time if a policy requires the PRNG to be reseeded
|
#define PSA_ERROR_TAMPERING_DETECTED ((psa_status_t)13)
|
||||||
* during normal operation. */
|
|
||||||
PSA_ERROR_INSUFFICIENT_ENTROPY,
|
/** There is not enough entropy to generate random data needed
|
||||||
/** The signature, MAC or hash is incorrect.
|
* for the requested action.
|
||||||
*
|
*
|
||||||
* Verification functions return this error if the verification
|
* This error indicates a failure of a hardware random generator.
|
||||||
* calculations completed successfully, and the value to be verified
|
* Application writers should note that this error can be returned not
|
||||||
* was determined to be incorrect.
|
* only by functions whose purpose is to generate random data, such
|
||||||
*
|
* as key, IV or nonce generation, but also by functions that execute
|
||||||
* If the value to verify has an invalid size, implementations may return
|
* an algorithm with a randomized result, as well as functions that
|
||||||
* either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */
|
* use randomization of intermediate computations as a countermeasure
|
||||||
PSA_ERROR_INVALID_SIGNATURE,
|
* to certain attacks.
|
||||||
/** The decrypted padding is incorrect.
|
*
|
||||||
*
|
* Implementations should avoid returning this error after psa_crypto_init()
|
||||||
* \warning In some protocols, when decrypting data, it is essential that
|
* has succeeded. Implementations should generate sufficient
|
||||||
* the behavior of the application does not depend on whether the padding
|
* entropy during initialization and subsequently use a cryptographically
|
||||||
* is correct, down to precise timing. Applications should prefer
|
* secure pseudorandom generator (PRNG). However implementations may return
|
||||||
* protocols that use authenticated encryption rather than plain
|
* this error at any time if a policy requires the PRNG to be reseeded
|
||||||
* encryption. If the application must perform a decryption of
|
* during normal operation. */
|
||||||
* unauthenticated data, the application writer should take care not
|
#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)14)
|
||||||
* to reveal whether the padding is invalid.
|
|
||||||
*
|
/** The signature, MAC or hash is incorrect.
|
||||||
* Implementations should strive to make valid and invalid padding
|
*
|
||||||
* as close as possible to indistinguishable to an external observer.
|
* Verification functions return this error if the verification
|
||||||
* In particular, the timing of a decryption operation should not
|
* calculations completed successfully, and the value to be verified
|
||||||
* depend on the validity of the padding. */
|
* was determined to be incorrect.
|
||||||
PSA_ERROR_INVALID_PADDING,
|
*
|
||||||
/** An error occurred that does not correspond to any defined
|
* If the value to verify has an invalid size, implementations may return
|
||||||
* failure cause.
|
* either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */
|
||||||
*
|
#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)15)
|
||||||
* Implementations may use this error code if none of the other standard
|
|
||||||
* error codes are applicable. */
|
/** The decrypted padding is incorrect.
|
||||||
PSA_ERROR_UNKNOWN_ERROR,
|
*
|
||||||
} psa_status_t;
|
* \warning In some protocols, when decrypting data, it is essential that
|
||||||
|
* the behavior of the application does not depend on whether the padding
|
||||||
|
* is correct, down to precise timing. Applications should prefer
|
||||||
|
* protocols that use authenticated encryption rather than plain
|
||||||
|
* encryption. If the application must perform a decryption of
|
||||||
|
* unauthenticated data, the application writer should take care not
|
||||||
|
* to reveal whether the padding is invalid.
|
||||||
|
*
|
||||||
|
* Implementations should strive to make valid and invalid padding
|
||||||
|
* as close as possible to indistinguishable to an external observer.
|
||||||
|
* In particular, the timing of a decryption operation should not
|
||||||
|
* depend on the validity of the padding. */
|
||||||
|
#define PSA_ERROR_INVALID_PADDING ((psa_status_t)16)
|
||||||
|
|
||||||
|
/** An error occurred that does not correspond to any defined
|
||||||
|
* failure cause.
|
||||||
|
*
|
||||||
|
* Implementations may use this error code if none of the other standard
|
||||||
|
* error codes are applicable. */
|
||||||
|
#define PSA_ERROR_UNKNOWN_ERROR ((psa_status_t)17)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \brief Library initialization.
|
* \brief Library initialization.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue