|
|
CryptoKeyKeyStore_PSA driver header.
============================================================================
This file contains the APIs to import, export, copy, and destroy key store CryptoKeys. Key store CryptoKeys reference keying material stored in flash or RAM using a key identifier. These CryptoKeys are subject to enforced usage restrictions as defined by the key attributes assigned during key import. This file provides defintions that are common between the secure and non-secure elements of a secure processing environment.
After calling the key store initialization function, a CryptoKey must be imported into the key store before it can be used for a crypto operation APIs which takes a CryptoKey as an input.
#include <third_party/mbedtls/include/psa/crypto.h>
Go to the source code of this file.
Data Structures | |
| struct | KeyStore_PreProvisionedKeyMetaData |
| Structure for storing pre-provisioned key's meta data. More... | |
| struct | KeyStore_preProvisionedKeyStorageFormat |
| Structure for storing pre-provisioned keys and its meta data. More... | |
| struct | KeyStore_PSA_preProvisionedKeyIDs |
| Structure for storing IDs of pre-provisioned keys. More... | |
Typedefs | |
| typedef psa_key_usage_t | KeyStore_PSA_KeyUsage |
| Encoding of permitted usage on a key. More... | |
| typedef psa_key_lifetime_t | KeyStore_PSA_KeyLifetime |
| typedef psa_key_type_t | KeyStore_PSA_KeyType |
| Encoding of a key type. More... | |
| typedef psa_algorithm_t | KeyStore_PSA_Algorithm |
| Encoding of a cryptographic algorithm. More... | |
| typedef psa_key_file_id_t | KeyStore_PSA_KeyFileId |
| typedef psa_key_attributes_t | KeyStore_PSA_KeyAttributes |
Functions | |
| void | KeyStore_PSA_setKeyId (KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyFileId key) |
| Declare a key as persistent and set its key identifier. More... | |
| void | KeyStore_PSA_setKeyLifetime (KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyLifetime lifetime) |
| Set the location of a persistent key. More... | |
| KeyStore_PSA_KeyFileId | KeyStore_PSA_getKeyId (KeyStore_PSA_KeyAttributes *attributes) |
| Retrieve the key identifier from key attributes. More... | |
| KeyStore_PSA_KeyLifetime | KeyStore_PSA_getKeyLifetime (KeyStore_PSA_KeyAttributes *attributes) |
| Retrieve the lifetime from key attributes. More... | |
| void | KeyStore_PSA_setKeyUsageFlags (KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyUsage usage_flags) |
| Declare usage flags for a key. More... | |
| KeyStore_PSA_KeyUsage | KeyStore_PSA_getKeyUsageFlags (KeyStore_PSA_KeyAttributes *attributes) |
| Retrieve the usage flags from key attributes. More... | |
| void | KeyStore_PSA_setKeyAlgorithm (KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_Algorithm alg) |
| Declare the permitted algorithm policy for a key. More... | |
| KeyStore_PSA_Algorithm | KeyStore_PSA_getKeyAlgorithm (KeyStore_PSA_KeyAttributes *attributes) |
| Retrieve the algorithm policy from key attributes. More... | |
| void | KeyStore_PSA_setKeyType (KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyType type) |
| Declare the type of a key. More... | |
| void | KeyStore_PSA_setKeyBits (KeyStore_PSA_KeyAttributes *attributes, size_t bits) |
| Declare the size of a key. More... | |
| KeyStore_PSA_KeyType | KeyStore_PSA_getKeyType (KeyStore_PSA_KeyAttributes *attributes) |
| Retrieve the key type from key attributes. More... | |
| size_t | KeyStore_PSA_getKeyBits (KeyStore_PSA_KeyAttributes *attributes) |
| Retrieve the key size from key attributes. More... | |
| void | KeyStore_PSA_resetKeyAttributes (KeyStore_PSA_KeyAttributes *attributes) |
| Reset a key attribute structure to a freshly initialized state. More... | |
| int_fast16_t | KeyStore_PSA_exportCertificate (KeyStore_PSA_KeyFileId key, uint8_t *data, size_t dataSize, size_t *dataLength) |
| Export a certificate in binary format. More... | |
| int_fast16_t | KeyStore_PSA_exportPublicKey (KeyStore_PSA_KeyFileId key, uint8_t *data, size_t dataSize, size_t *dataLength) |
| Export a public key or the public part of a key pair in binary format. More... | |
| int_fast16_t | KeyStore_PSA_exportKey (KeyStore_PSA_KeyFileId key, uint8_t *data, size_t dataSize, size_t *dataLength) |
| Export a key in binary format. More... | |
| int_fast16_t | KeyStore_PSA_importCertificate (KeyStore_PSA_KeyAttributes *attributes, KeyStore_PSA_KeyFileId *key, uint8_t *data, size_t dataLength) |
| Import a certificate in binary format. More... | |
| int_fast16_t | KeyStore_PSA_importKey (KeyStore_PSA_KeyAttributes *attributes, uint8_t *data, size_t dataLength, KeyStore_PSA_KeyFileId *key) |
| Import a key in binary format. More... | |
| int_fast16_t | KeyStore_PSA_getKeyAttributes (KeyStore_PSA_KeyFileId key, KeyStore_PSA_KeyAttributes *attributes) |
| Retrieve the attributes of a key. More... | |
| int_fast16_t | KeyStore_PSA_purgeKey (KeyStore_PSA_KeyFileId key) |
| Remove non-essential copies of key material from memory. More... | |
| int_fast16_t | KeyStore_PSA_destroyCertificate (KeyStore_PSA_KeyFileId key) |
| Destroy a certificate associated with a key. More... | |
| int_fast16_t | KeyStore_PSA_destroyKey (KeyStore_PSA_KeyFileId key) |
| Destroy a key. More... | |
| #define KEYSTORE_PSA_STATUS_SUCCESS ((int_fast16_t)PSA_SUCCESS) |
The action was completed successfully.
| #define KEYSTORE_PSA_STATUS_GENERIC_ERROR ((int_fast16_t)PSA_ERROR_GENERIC_ERROR) |
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 KEYSTORE_PSA_STATUS_NOT_SUPPORTED ((int_fast16_t)PSA_ERROR_NOT_SUPPORTED) |
The requested operation or a parameter is not supported by this implementation.
Implementations should return this error code when an enumeration parameter such as a key type, algorithm, etc. is not recognized. If a combination of parameters is recognized and identified as not valid, return KEYSTORE_PSA_STATUS_INVALID_ARGUMENT instead.
| #define KEYSTORE_PSA_STATUS_NOT_PERMITTED ((int_fast16_t)PSA_ERROR_NOT_PERMITTED) |
The requested action is denied by a policy.
Implementations should return this error code when the parameters are recognized as valid and supported, and a policy explicitly denies the requested operation.
If a subset of the parameters of a function call identify a forbidden operation, and another subset of the parameters are not valid or not supported, it is unspecified whether the function returns KEYSTORE_PSA_STATUS_NOT_PERMITTED, KEYSTORE_PSA_STATUS_NOT_SUPPORTED or KEYSTORE_PSA_STATUS_INVALID_ARGUMENT.
| #define KEYSTORE_PSA_STATUS_INVALID_KEY_ID ((int_fast16_t)PSA_ERROR_INVALID_HANDLE) |
The key ID is not valid or does not exist.
| #define KEYSTORE_PSA_STATUS_BUFFER_TOO_SMALL ((int_fast16_t)PSA_ERROR_BUFFER_TOO_SMALL) |
An output buffer is too small.
Applications can call the PSA_xxx_SIZE macro listed in the function description to determine a sufficient buffer size.
Implementations should preferably return this error code only in cases when performing the operation with a larger output buffer would succeed. However implementations may return this error if a function has invalid or unsupported parameters in addition to the parameters that determine the necessary output buffer size.
| #define KEYSTORE_PSA_STATUS_ALREADY_EXISTS ((int_fast16_t)PSA_ERROR_ALREADY_EXISTS) |
Asking for an item that already exists
Implementations should return this error, when attempting to write an item (like a key) that already exists.
| #define KEYSTORE_PSA_STATUS_DOES_NOT_EXIST ((int_fast16_t)PSA_ERROR_DOES_NOT_EXIST) |
Asking for an item that doesn't exist
Implementations should return this error, if a requested item (like a key) does not exist.
| #define KEYSTORE_PSA_STATUS_BAD_STATE ((int_fast16_t)PSA_ERROR_BAD_STATE) |
The requested action cannot be performed in the current state.
Multipart operations return this error when one of the functions is called out of sequence. Refer to the function descriptions for permitted sequencing of functions.
Implementations shall not return this error code to indicate that a key either exists or not, but shall instead return KEYSTORE_PSA_STATUS_ALREADY_EXISTS or KEYSTORE_PSA_STATUS_DOES_NOT_EXIST as applicable.
Implementations shall not return this error code to indicate that a key ID is invalid, but shall return KEYSTORE_PSA_STATUS_INVALID_KEY_ID instead.
| #define KEYSTORE_PSA_STATUS_INVALID_ARGUMENT ((int_fast16_t)PSA_ERROR_INVALID_ARGUMENT) |
The parameters passed to the function are invalid.
Implementations may return this error any time a parameter or combination of parameters are recognized as invalid.
Implementations shall not return this error code to indicate that a key ID is invalid, but shall return KEYSTORE_PSA_STATUS_INVALID_KEY_ID instead.
| #define KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY ((int_fast16_t)PSA_ERROR_INSUFFICIENT_MEMORY) |
There is not enough runtime memory.
If the action is carried out across multiple security realms, this error can refer to available memory in any of the security realms.
| #define KEYSTORE_PSA_STATUS_INSUFFICIENT_STORAGE ((int_fast16_t)PSA_ERROR_INSUFFICIENT_STORAGE) |
There is not enough persistent storage.
Functions that modify the key storage return this error code if there is insufficient storage space on the host media. In addition, many functions that do not otherwise access storage may return this error code if the implementation requires a mandatory log entry for the requested action and the log storage space is full.
| #define KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE ((int_fast16_t)PSA_ERROR_COMMUNICATION_FAILURE) |
There was a communication failure inside the implementation.
This can indicate a communication failure between the application and an external cryptoprocessor or between the cryptoprocessor and an external volatile or persistent memory. A communication failure may be transient or permanent depending on the cause.
| #define KEYSTORE_PSA_STATUS_STORAGE_FAILURE ((int_fast16_t)PSA_ERROR_STORAGE_FAILURE) |
There was a storage failure that may have led to data loss.
This error indicates that some persistent storage is corrupted. It should not be used for a corruption of volatile memory (use KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED), for a communication error between the cryptoprocessor and its external storage (use KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE), or when the storage is in a valid state but is full (use KEYSTORE_PSA_STATUS_INSUFFICIENT_STORAGE).
Note that a storage failure does not indicate that any data that was previously read is invalid. However this previously read data may no longer be readable from storage.
When a storage failure occurs, it is no longer possible to ensure the global integrity of the keystore. Depending on the global integrity guarantees offered by the implementation, access to other data may or may not fail even if the data is still readable but its integrity cannot be guaranteed.
Implementations should only use this error code to report a permanent storage corruption. However application writers should keep in mind that transient errors while reading the storage may be reported using this error code.
| #define KEYSTORE_PSA_STATUS_HARDWARE_FAILURE ((int_fast16_t)PSA_ERROR_HARDWARE_FAILURE) |
A hardware failure was detected.
A hardware failure may be transient or permanent depending on the cause.
| #define KEYSTORE_PSA_STATUS_INSUFFICIENT_ENTROPY ((int_fast16_t)PSA_ERROR_INSUFFICIENT_ENTROPY) |
There is not enough entropy to generate random data needed for the requested action.
This error indicates a failure of a hardware random generator. Application writers should note that this error can be returned not only by functions whose purpose is to generate random data, such as key, IV or nonce generation, but also by functions that execute an algorithm with a randomized result, as well as functions that use randomization of intermediate computations as a countermeasure to certain attacks.
Implementations should avoid returning this error after KeyStore_PSA_init() has succeeded. Implementations should generate sufficient entropy during initialization and subsequently use a cryptographically secure pseudorandom generator (PRNG). However implementations may return this error at any time if a policy requires the PRNG to be reseeded during normal operation.
| #define KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED ((int_fast16_t)PSA_ERROR_CORRUPTION_DETECTED) |
A tampering attempt was detected.
If an application receives this error code, there is no guarantee that previously accessed or computed data was correct and remains confidential. Applications should not perform any security function and should enter a safe failure state.
Implementations may return this error code if they detect an invalid state that cannot happen during normal operation and that indicates that the implementation's security guarantees no longer hold. Depending on the implementation architecture and on its security and safety goals, the implementation may forcibly terminate the application.
This error code is intended as a last resort when a security breach is detected and it is unsure whether the keystore data is still protected. Implementations shall only return this error code to report an alarm from a tampering detector, to indicate that the confidentiality of stored data can no longer be guaranteed, or to indicate that the integrity of previously returned data is now considered compromised. Implementations shall not use this error code to indicate a hardware failure that merely makes it impossible to perform the requested operation (use KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE, KEYSTORE_PSA_STATUS_STORAGE_FAILURE, KEYSTORE_PSA_STATUS_HARDWARE_FAILURE or other applicable error code instead).
This error indicates an attack against the application. Implementations shall not return this error code as a consequence of the behavior of the application itself.
| #define KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-250) |
An error status code returned if the hardware or software resource is currently unavailable.
KeyStore driver implementation may have limitations on how many clients can simultaneously perform operations on the same key. This status code is returned if the mutual exclusion mechanism signals that an operation cannot currently be performed.
| #define KEYSTORE_PSA_KEY_TYPE_RAW_DATA ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_RAW_DATA) |
Raw data.
A "key" of this type cannot be used for any cryptographic operation. Applications may use this type to store arbitrary data in the keystore.
| #define KEYSTORE_PSA_KEY_TYPE_HMAC ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_HMAC) |
HMAC key.
The key policy determines which underlying hash algorithm the key can be used for.
HMAC keys should generally have the same size as the underlying hash.
| #define KEYSTORE_PSA_KEY_TYPE_DERIVE ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_DERIVE) |
A secret for key derivation.
The key policy determines which key derivation algorithm the key can be used for.
| #define KEYSTORE_PSA_KEY_TYPE_AES ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_AES) |
Key for a cipher, AEAD or MAC algorithm based on the AES block cipher.
The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or 32 bytes (AES-256).
| #define KEYSTORE_PSA_KEY_TYPE_DES ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_DES) |
Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).
The size of the key can be 64 bits (single DES), 128 bits (2-key 3DES) or 192 bits (3-key 3DES).
Note that single DES and 2-key 3DES are weak and strongly deprecated and should only be used to decrypt legacy data. 3-key 3DES is weak and deprecated and should only be used in legacy protocols.
| #define KEYSTORE_PSA_KEY_TYPE_CAMELLIA ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_CAMELLIA) |
Key for a cipher, AEAD or MAC algorithm based on the Camellia block cipher.
| #define KEYSTORE_PSA_KEY_TYPE_ARC4 ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_ARC4) |
Key for the RC4 stream cipher.
Note that RC4 is weak and deprecated and should only be used in legacy protocols.
| #define KEYSTORE_PSA_KEY_TYPE_CHACHA20 ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_CHACHA20) |
Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.
ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539.
Implementations must support 12-byte nonces, may support 8-byte nonces, and should reject other sizes.
| #define KEYSTORE_PSA_KEY_TYPE_RSA_PUBLIC_KEY ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_RSA_PUBLIC_KEY) |
RSA public key.
The size of an RSA key is the bit size of the modulus.
| #define KEYSTORE_PSA_KEY_TYPE_RSA_KEY_PAIR ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_RSA_KEY_PAIR) |
RSA key pair (private and public key).
The size of an RSA key is the bit size of the modulus.
| #define PSA_KEY_TYPE_IS_RSA | ( | type | ) | (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY) |
Whether a key type is an RSA key (pair or public-only).
| #define KEYSTORE_PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) |
| #define KEYSTORE_PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((KeyStore_PSA_KeyType)PSA_KEY_TYPE_ECC_KEY_PAIR_BASE) |
| #define KEYSTORE_PSA_ALG_SHA_224 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_224) |
SHA2-224
| #define KEYSTORE_PSA_ALG_SHA_256 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_256) |
SHA2-256
| #define KEYSTORE_PSA_ALG_SHA_384 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_384) |
SHA2-384
| #define KEYSTORE_PSA_ALG_SHA_512 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_512) |
SHA2-512
| #define KEYSTORE_PSA_ALG_SHA_512_224 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_512_224) |
SHA2-512/224
| #define KEYSTORE_PSA_ALG_SHA_512_256 ((KeyStore_PSA_Algorithm)PSA_ALG_SHA_512_256) |
SHA2-512/256
| #define KEYSTORE_PSA_ALG_CBC_MAC ((KeyStore_PSA_Algorithm)PSA_ALG_CBC_MAC) |
The CBC-MAC construction over a block cipher
| #define KEYSTORE_PSA_ALG_CMAC ((KeyStore_PSA_Algorithm)PSA_ALG_CMAC) |
The CMAC construction over a block cipher
| #define KEYSTORE_PSA_ALG_CTR ((KeyStore_PSA_Algorithm)PSA_ALG_CTR) |
The CTR stream cipher mode.
CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the key type. For example, to use AES-128-CTR, use this algorithm with a key of type KEYSTORE_PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes).
| #define KEYSTORE_PSA_ALG_CBC_NO_PADDING ((KeyStore_PSA_Algorithm)PSA_ALG_CBC_NO_PADDING) |
The CBC block cipher chaining mode, with no padding.
The underlying block cipher is determined by the key type.
This symmetric cipher mode can only be used with messages whose lengths are whole number of blocks for the chosen block cipher.
| #define KEYSTORE_PSA_ALG_CCM ((KeyStore_PSA_Algorithm)PSA_ALG_CCM) |
The CCM authenticated encryption algorithm.
The underlying block cipher is determined by the key type.
| #define KEYSTORE_PSA_ALG_GCM ((KeyStore_PSA_Algorithm)PSA_ALG_GCM) |
The GCM authenticated encryption algorithm.
The underlying block cipher is determined by the key type.
| #define KEYSTORE_PSA_ALG_CHACHA20_POLY1305 ((KeyStore_PSA_Algorithm)PSA_ALG_CHACHA20_POLY1305) |
The Chacha20-Poly1305 AEAD algorithm.
The ChaCha20_Poly1305 construction is defined in RFC 7539.
Implementations must support 12-byte nonces, may support 8-byte nonces, and should reject other sizes.
Implementations must support 16-byte tags and should reject other sizes.
| #define KEYSTORE_PSA_ALG_ECDH ((KeyStore_PSA_Algorithm)PSA_ALG_ECDH) |
The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm.
The shared secret produced by key agreement is the x-coordinate of the shared secret point. It is always ceiling(m / 8) bytes long where m is the bit size associated with the curve, i.e. the bit size of the order of the curve's coordinate field. When m is not a multiple of 8, the byte containing the most significant bit of the shared secret is padded with zero bits. The byte order is either little-endian or big-endian depending on the curve type.
PSA_ECC_FAMILY_CURVEXXX), the shared secret is the x-coordinate of d_A Q_B = d_B Q_A in little-endian byte order. The bit size is 448 for Curve448 and 255 for Curve25519.PSA_ECC_FAMILY_SECPXXX and PSA_ECC_FAMILY_BRAINPOOL_PXXX), the shared secret is the x-coordinate of d_A Q_B = d_B Q_A in big-endian byte order. The bit size is m = ceiling(log_2(p)) for the field F_p.PSA_ECC_FAMILY_SECTXXX), the shared secret is the x-coordinate of d_A Q_B = d_B Q_A in big-endian byte order. The bit size is m for the field F_{2^m}. | #define KEYSTORE_PSA_ECC_CURVE_SECT163K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT163K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT163R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT163R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT163R2 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT163R2) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT193R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT193R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT193R2 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT193R2) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT233K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT233K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT233R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT233R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT239K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT239K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT283K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT283K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT283R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT283R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT409K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT409K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT409R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT409R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT571K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT571K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECT571R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECT571R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP160K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP160K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP160R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP160R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP160R2 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP160R2) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP192K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP192K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP192R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP192R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP224K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP224K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP224R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP224R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP256K1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP256K1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP256R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP256R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP384R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP384R1) |
| #define KEYSTORE_PSA_ECC_CURVE_SECP521R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_SECP521R1) |
| #define KEYSTRORE_ECC_CURVE_BRAINPOOL_P256R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_BRAINPOOL_P256R1) |
| #define KEYSTRORE_ECC_CURVE_BRAINPOOL_P384R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_BRAINPOOL_P384R1) |
| #define KEYSTRORE_ECC_CURVE_BRAINPOOL_P512R1 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_BRAINPOOL_P512R1) |
| #define KEYSTORE_PSA_ECC_CURVE_CURVE25519 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_CURVE25519) |
Cur KEYSTRORE_ECC_CURVE_SECPv((KeyStore_PSA_KeyType)e25519.
This is the curve defined in Bernstein et al., Curve25519: new Diffie-Hellman speed records, LNCS 3958, 2006. The algorithm KEYSTORE_PSA_ALG_ECDH performs X25519 when used with this curve.
| #define KEYSTORE_PSA_ECC_CURVE_CURVE448 ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_CURVE448) |
Curve448
This is the curve defined in Hamburg, Ed448-Goldilocks, a new elliptic curve, NIST ECC Workshop, 2015. The algorithm KEYSTORE_PSA_ALG_ECDH performs X448 when used with this curve.
| #define KEYSTORE_PSA_ECC_CURVE_VENDOR_MIN ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_VENDOR_MIN) |
Minimum value for a vendor-defined ECC curve identifier
The range for vendor-defined curve identifiers is a subset of the IANA registry private use range, 0xfe00 - 0xfeff.
| #define KEYSTORE_PSA_ECC_CURVE_VENDOR_MAX ((KeyStore_PSA_KeyType)PSA_ECC_CURVE_VENDOR_MAX) |
Maximum value for a vendor-defined ECC curve identifier
The range for vendor-defined curve identifiers is a subset of the IANA registry private use range, 0xfe00 - 0xfeff.
| #define KEYSTORE_PSA_MAX_VOLATILE_KEY_ID PSA_KEY_SLOT_COUNT |
| #define MEMBER_SIZE | ( | type, | |
| member | |||
| ) | sizeof(((type *)0)->member) |
| #define KEYSTORE_PSA_PREPROVISIONED_AREA_ADDR 0x0000 |
Starting address of Pre-provisioned keys.
The Immutable platform Root of Trust stores the pre-provisioned key's programmed at production. SKS implementation will read this address to obtain the KeyStore_PSA_KeyFileId and other relevant meta data of all the pre-provisioned keys stored at this address
| #define KEYSTORE_PSA_PREPROVISIONED_AREA_SIZE (0x700) /* 1792 B */ |
Area size for pre-provisioned keys, 2KB - 256B (reserved for attestation data)
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_EXPORT_FLAG 0xAAAA |
Exportable pre-provisioned key prefix.
Prefix the plaintext key in pre-provisioned key that can be exported to the non-secure application with this flag
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_EXPORT_FLAG_LENGTH (sizeof(KEYSTORE_PSA_PRE_PROVISIONED_KEY_EXPORT_FLAG)) |
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_NO_EXPORT_FLAG 0xA5A5 |
| #define KEYSTORE_PSA_PREPROVISIONED_KEYS_EMPTY 0xFFFF |
Macro to indicate empty pre-provisioned key memory.
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_MAGIC_HEADER "HUK\0KEY" |
Pre-provisioned key storage magic header.
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEYS_END 0 |
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_MAGIC_HEADER_LENGTH (sizeof(KEYSTORE_PSA_PRE_PROVISIONED_KEY_MAGIC_HEADER)) |
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEYS_END_LENGTH (sizeof(KEYSTORE_PSA_PRE_PROVISIONED_KEYS_END)) |
| #define KEYSTORE_PSA_MAX_PREPROVISIONED_KEYS 0x10 |
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_VALID_LIFETIME 0xAAAA |
Pre-provisioned key Lifetime.
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_INVALID_LIFETIME 0x8888 |
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_ID_MAX 0x40 |
Admissible key ID range for Pre-provisioned keys.
0x21 - 0x40 is reserved to store pre-provisioned keys. Correspondingly, 0x10000021 - 0x10000040 is reserved for any associated certificates.
| #define KEYSTORE_PSA_PRE_PROVISIONED_KEY_ID_MIN 0x21 |
| #define KEYSTORE_PSA_PRE_PROVISIONED_CERTIFICATE_ID_MAX (KEYSTORE_PSA_PRE_PROVISIONED_KEY_ID_MAX | KEYSTORE_PSA_KEY_ID_CERTIFICATE_BIT) |
| #define KEYSTORE_PSA_PRE_PROVISIONED_CERTIFICATE_ID_MIN (KEYSTORE_PSA_PRE_PROVISIONED_KEY_ID_MIN | KEYSTORE_PSA_KEY_ID_CERTIFICATE_BIT) |
| #define KEYSTORE_PSA_PRE_PROVISIONED_ATTESTATION_PUB_KEY_ID 0x40 |
Reserved pre-provisioned key IDs.
Some known pre-provisioned key used by attestation service have reserved key IDs in the admissible range for pre-provisioned keys
| #define KEYSTORE_PSA_PRE_PROVISIONED_ATTESTATION_PRI_KEY_ID 0X3F |
| #define KEYSTORE_PSA_PRE_PROVISIONED_ATTESTATION_CERTIFICATE_ID (KEYSTORE_PSA_PRE_PROVISIONED_ATTESTATION_PUB_KEY_ID | KEYSTORE_PSA_KEY_ID_CERTIFICATE_BIT) |
| #define KEYSTORE_PRE_PROVISIONED_KEY_METADATA_SIZE sizeof(KeyStore_PreProvisionedKeyMetaData) |
Size of the meta data associated with the pre-provisoned key.
| #define KEYSTORE_PSA_PREPROVISIONED_KEY_FORMAT_INIT |
Initialize a KeyStore_preProvisionedKeyStorageFormat struct variable.
| typedef psa_key_usage_t KeyStore_PSA_KeyUsage |
Encoding of permitted usage on a key.
| typedef psa_key_lifetime_t KeyStore_PSA_KeyLifetime |
Encoding of key lifetimes.
The lifetime of a key indicates where it is stored and what system actions may create and destroy it.
Keys with the lifetime KEYSTORE_PSA_KEY_LIFETIME_VOLATILE are automatically destroyed when the application terminates or on a power reset.
Keys with a lifetime other than KEYSTORE_PSA_KEY_LIFETIME_VOLATILE are said to be persistent. Persistent keys are preserved if the application or the system restarts.
| typedef psa_key_type_t KeyStore_PSA_KeyType |
Encoding of a key type.
| typedef psa_algorithm_t KeyStore_PSA_Algorithm |
Encoding of a cryptographic algorithm.
For algorithms that can be applied to multiple key types, this type does not encode the key type. For example, for symmetric ciphers based on a block cipher, KeyStore_PSA_Algorithm encodes the block cipher mode and the padding mode while the block cipher itself is encoded via KeyStore_PSA_KeyType.
| typedef psa_key_file_id_t KeyStore_PSA_KeyFileId |
A Key owner is a PSA partition identifier. This definition follow 'psa_key_owner_id_t' from crypto_platform.h
| void KeyStore_PSA_setKeyId | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| KeyStore_PSA_KeyFileId | key | ||
| ) |
Declare a key as persistent and set its key identifier.
If the attribute structure currently declares the key as volatile (which is the default content of an attribute structure), this function sets the lifetime attribute to KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT.
This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as KeyStore_PSA_import_key(), KeyStore_PSA_generate_key(), KeyStore_PSA_key_derivation_output_key() or KeyStore_PSA_copy_key().
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
| [out] | attributes | The attribute structure to write to. |
| key | The persistent identifier for the key. |
| void KeyStore_PSA_setKeyLifetime | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| KeyStore_PSA_KeyLifetime | lifetime | ||
| ) |
Set the location of a persistent key.
To make a key persistent, you must give it a persistent key identifier with KeyStore_PSA_setKeyId(). By default, a key that has a persistent identifier is stored in the default storage area identifier by KEYSTORE_PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage area, or to explicitly declare the key as volatile.
This function does not access storage, it merely stores the given value in the structure. The persistent key will be written to storage when the attribute structure is passed to a key creation function such as KeyStore_PSA_import_key(), KeyStore_PSA_generate_key(), KeyStore_PSA_key_derivation_output_key() or KeyStore_PSA_copy_key().
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
| [out] | attributes | The attribute structure to write to. |
| lifetime | The lifetime for the key. If this is KEYSTORE_PSA_KEY_LIFETIME_VOLATILE, the key will be volatile, and the key identifier attribute is reset to 0. |
| KeyStore_PSA_KeyFileId KeyStore_PSA_getKeyId | ( | KeyStore_PSA_KeyAttributes * | attributes | ) |
Retrieve the key identifier from key attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
| [in] | attributes | The key attribute structure to query. |
| KeyStore_PSA_KeyLifetime KeyStore_PSA_getKeyLifetime | ( | KeyStore_PSA_KeyAttributes * | attributes | ) |
Retrieve the lifetime from key attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
| [in] | attributes | The key attribute structure to query. |
| void KeyStore_PSA_setKeyUsageFlags | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| KeyStore_PSA_KeyUsage | usage_flags | ||
| ) |
Declare usage flags for a key.
Usage flags are part of a key's usage policy. They encode what kind of operations are permitted on the key. For more details, refer to the documentation of the type KeyStore_PSA_KeyUsage.
This function overwrites any usage flags previously set in attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
| [out] | attributes | The attribute structure to write to. |
| usage_flags | The usage flags to write. |
| KeyStore_PSA_KeyUsage KeyStore_PSA_getKeyUsageFlags | ( | KeyStore_PSA_KeyAttributes * | attributes | ) |
Retrieve the usage flags from key attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
| [in] | attributes | The key attribute structure to query. |
| void KeyStore_PSA_setKeyAlgorithm | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| KeyStore_PSA_Algorithm | alg | ||
| ) |
Declare the permitted algorithm policy for a key.
The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key. The following algorithm policies are supported:
This function overwrites any algorithm policy previously set in attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
| [out] | attributes | The attribute structure to write to. |
| alg | The permitted algorithm policy to write. |
| KeyStore_PSA_Algorithm KeyStore_PSA_getKeyAlgorithm | ( | KeyStore_PSA_KeyAttributes * | attributes | ) |
Retrieve the algorithm policy from key attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
| [in] | attributes | The key attribute structure to query. |
| void KeyStore_PSA_setKeyType | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| KeyStore_PSA_KeyType | type | ||
| ) |
Declare the type of a key.
This function overwrites any key type previously set in attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
| [out] | attributes | The attribute structure to write to. |
| type | The key type to write. If this is 0, the key type in attributes becomes unspecified. |
| void KeyStore_PSA_setKeyBits | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| size_t | bits | ||
| ) |
Declare the size of a key.
This function overwrites any key size previously set in attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate each of its arguments exactly once.
| [out] | attributes | The attribute structure to write to. |
| bits | The key size in bits. If this is 0, the key size in attributes becomes unspecified. Keys of size 0 are not supported. |
| KeyStore_PSA_KeyType KeyStore_PSA_getKeyType | ( | KeyStore_PSA_KeyAttributes * | attributes | ) |
Retrieve the key type from key attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
| [in] | attributes | The key attribute structure to query. |
| size_t KeyStore_PSA_getKeyBits | ( | KeyStore_PSA_KeyAttributes * | attributes | ) |
Retrieve the key size from key attributes.
This function may be declared as static (i.e. without external linkage). This function may be provided as a function-like macro, but in this case it must evaluate its argument exactly once.
| [in] | attributes | The key attribute structure to query. |
| void KeyStore_PSA_resetKeyAttributes | ( | KeyStore_PSA_KeyAttributes * | attributes | ) |
Reset a key attribute structure to a freshly initialized state.
You must initialize the attribute structure as described in the documentation of the type KeyStore_PSA_KeyAttributes before calling this function. Once the structure has been initialized, you may call this function at any time.
This function frees any auxiliary resources that the structure may contain.
| [in,out] | attributes | The attribute structure to reset. |
| int_fast16_t KeyStore_PSA_exportCertificate | ( | KeyStore_PSA_KeyFileId | key, |
| uint8_t * | data, | ||
| size_t | dataSize, | ||
| size_t * | dataLength | ||
| ) |
Export a certificate in binary format.
The output of this function can be passed to KeyStore_PSA_importCertificate() to create an equivalent object.
| [in] | key | Key file ID of the key associated with the certificate to export. |
| [out] | data | Buffer where the certificate data is to be written. |
| [in] | dataSize | Size of the data buffer in bytes. |
| [out] | dataLength | On success, the number of bytes that make up the certificate data. |
| KEYSTORE_PSA_STATUS_SUCCESS | |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | The key identifier does not exist. |
| KEYSTORE_PSA_STATUS_NOT_SUPPORTED | |
| KEYSTORE_PSA_STATUS_BUFFER_TOO_SMALL | The size of the data buffer is too small. |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY | |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_exportPublicKey | ( | KeyStore_PSA_KeyFileId | key, |
| uint8_t * | data, | ||
| size_t | dataSize, | ||
| size_t * | dataLength | ||
| ) |
Export a public key or the public part of a key pair in binary format.
The output of this function can be passed to KeyStore_PSA_importKey() to create an object that is equivalent to the public key.
This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format.
PSA_ECC_CURVE_CURVEXXX), isx_P as a ceiling(m/8)-byte string, little-endian;PSA_ECC_CURVE_SECTXXX, PSA_ECC_CURVE_SECPXXX and PSA_ECC_CURVE_BRAINPOOL_PXXX), is the uncompressed representation defined by SEC1 §2.3.3 as the content of an ECPoint. Let m be the bit size associated with the curve, i.e. the bit size of q for a curve over F_q. The representation consists of:x_P as a ceiling(m/8)-byte string, big-endian;y_P as a ceiling(m/8)-byte string, big-endian.y = g^x mod p as a big-endian byte string. The length of the byte string is the length of the base prime p in bytes.Exporting a public key object or the public part of a key pair is always permitted, regardless of the key's usage flags.
| [in] | key | Key file ID of the key to export. |
| [out] | data | Buffer where the key data is to be written. |
| [in] | dataSize | Size of the data buffer in bytes. |
| [out] | dataLength | On success, the number of bytes that make up the key data. |
| KEYSTORE_PSA_STATUS_SUCCESS | |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | |
| KEYSTORE_PSA_STATUS_INVALID_ARGUMENT | The key is neither a public key nor a key pair. |
| KEYSTORE_PSA_STATUS_NOT_SUPPORTED | |
| KEYSTORE_PSA_STATUS_BUFFER_TOO_SMALL | The size of the data buffer is too small. |
| KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE | |
| KEYSTORE_PSA_STATUS_HARDWARE_FAILURE | |
| KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED | |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY | |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_exportKey | ( | KeyStore_PSA_KeyFileId | key, |
| uint8_t * | data, | ||
| size_t | dataSize, | ||
| size_t * | dataLength | ||
| ) |
Export a key in binary format.
The key must designated as exportable. The output of this function can be passed to KeyStore_PSA_importKey() to create an equivalent object.
If the implementation of KeyStore_PSA_importKey() supports other formats beyond the format specified here, the output from KeyStore_PSA_exportKey() must use the representation specified here, not the original representation.
For standard key types, the output format is as follows:
ceiling(m/8)-byte string where m is the bit size associated with the curve, i.e. the bit size of the order of the curve's coordinate field. This byte string is in little-endian order for Montgomery curves (curve types PSA_ECC_CURVE_CURVEXXX), and in big-endian order for Weierstrass curves (curve types PSA_ECC_CURVE_SECTXXX, PSA_ECC_CURVE_SECPXXX and PSA_ECC_CURVE_BRAINPOOL_PXXX). This is the content of the privateKey field of the ECPrivateKey format defined by RFC 5915.x as a big-endian byte string. The length of the byte string is the private key size in bytes (leading zeroes are not stripped).The policy on the key must have the usage flag KEYSTORE_PSA_KEY_USAGE_EXPORT set.
| [in] | key | Key file ID of the key to export. |
| [out] | data | Buffer where the key data is to be written. |
| [in] | dataSize | Size of the data buffer in bytes. |
| [out] | dataLength | On success, the number of bytes that make up the key data. |
| KEYSTORE_PSA_STATUS_SUCCESS | |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | The key identifier does not exist. |
| KEYSTORE_PSA_STATUS_NOT_PERMITTED | The key does not have the KEYSTORE_PSA_KEY_USAGE_EXPORT flag. |
| KEYSTORE_PSA_STATUS_NOT_SUPPORTED | |
| KEYSTORE_PSA_STATUS_BUFFER_TOO_SMALL | The size of the data buffer is too small. |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY | |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_importCertificate | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| KeyStore_PSA_KeyFileId * | key, | ||
| uint8_t * | data, | ||
| size_t | dataLength | ||
| ) |
Import a certificate in binary format.
This function supports the output from KeyStore_PSA_exportCertificate().
Multiple certificates cannot be imported for the same key ID. If an additional certificate needs to be associated with a particular key pair or public key, that key data must be imported again with a different key ID. Additionally, the key store does not interpret the contents of the certificate and cannot verify that the key embedded within the certificate matches the associated key.
Implementations must reject an attempt to import a certificate of size 0.
| [in] | attributes | The attributes for the new certificate. The certificate size is always determined from the data buffer. If the certificate size in attributes is nonzero, it must be equal to the size from data. |
| [out] | key | On success, the key file ID of the previously imported key associated with the certificate. 0 on failure. |
| [in] | data | Buffer containing the certificate data in binary format. |
| [in] | dataLength | Size of the data buffer in bytes. |
| KEYSTORE_PSA_STATUS_SUCCESS | Success. If the certificate is persistent, the certificate material and the certificate's metadata have been saved to persistent storage. |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_ALREADY_EXISTS | This is an attempt to create a certificate, and there is already a certificate with the given identifier. |
| KEYSTORE_PSA_STATUS_NOT_SUPPORTED | The certificate type or certificate size is not supported, either by the implementation in general or in this particular persistent location. |
| KEYSTORE_PSA_STATUS_INVALID_ARGUMENT | The certificate attributes, as a whole, are invalid. |
| KEYSTORE_PSA_STATUS_INVALID_ARGUMENT | The certificate data is not correctly formatted. |
| KEYSTORE_PSA_STATUS_INVALID_ARGUMENT | The size in attributes is nonzero and does not match the size of the certificate data. |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY | |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_STORAGE | |
| KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE | |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | |
| KEYSTORE_PSA_STATUS_HARDWARE_FAILURE | |
| KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED | |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_importKey | ( | KeyStore_PSA_KeyAttributes * | attributes, |
| uint8_t * | data, | ||
| size_t | dataLength, | ||
| KeyStore_PSA_KeyFileId * | key | ||
| ) |
Import a key in binary format.
This function supports any output from KeyStore_PSA_exportKey(). Refer to the documentation of KeyStore_PSA_exportPublicKey() for the format of public keys and to the documentation of KeyStore_PSA_exportKey() for the format for other key types.
The dataLength determines the key size. The attributes may optionally specify a key size; in this case it must match the dataLength. A key size of 0 in attributes indicates that the key size is solely determined by the key data.
Implementations must reject an attempt to import a key of size 0.
This specification supports a single format for each key type. Implementations may support other formats as long as the standard format is supported. Implementations that support other formats should ensure that the formats are clearly unambiguous so as to minimize the risk that an invalid input is accidentally interpreted according to a different format.
| [in] | attributes | The attributes for the new key. The key size is always determined from the data buffer. If the key size in attributes is nonzero, it must be equal to the size from data. |
| [in] | data | Buffer containing the key data. The content of this buffer is interpreted according to the type declared in attributes. All implementations must support at least the format described in the documentation of KeyStore_PSA_exportKey() or KeyStore_PSA_exportPublicKey() for the chosen type. Implementations may allow other formats, but should be conservative: implementations should err on the side of rejecting content if it may be erroneous (e.g. wrong type or truncated data). |
| [in] | dataLength | Size of the data buffer in bytes. |
| [out] | key | On success, the key file ID of the newly created key. 0 on failure. |
| KEYSTORE_PSA_STATUS_SUCCESS | Success. If the key is persistent, the key material and the key's metadata have been saved to persistent storage. |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_ALREADY_EXISTS | This is an attempt to create a key, and there is already a key with the given key file identifier. |
| KEYSTORE_PSA_STATUS_NOT_SUPPORTED | The key type or key size is not supported, either by the implementation in general or in this particular persistent location. |
| KEYSTORE_PSA_STATUS_INVALID_ARGUMENT | The key attributes, as a whole, are invalid. |
| KEYSTORE_PSA_STATUS_INVALID_ARGUMENT | The key data is not correctly formatted. |
| KEYSTORE_PSA_STATUS_INVALID_ARGUMENT | The size in attributes is nonzero and does not match the size of the key data. |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY | |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_STORAGE | |
| KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE | |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | |
| KEYSTORE_PSA_STATUS_HARDWARE_FAILURE | |
| KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED | |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_getKeyAttributes | ( | KeyStore_PSA_KeyFileId | key, |
| KeyStore_PSA_KeyAttributes * | attributes | ||
| ) |
Retrieve the attributes of a key.
This function first resets the attribute structure as with KeyStore_PSA_resetKeyAttributes(). It then copies the attributes of the given key into the given attribute structure.
| [in] | key | Identifier of the key to query. |
| [in,out] | attributes | On success, the attributes of the key. On failure, equivalent to a freshly-initialized structure. |
| KEYSTORE_PSA_STATUS_SUCCESS | |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | |
| KEYSTORE_PSA_STATUS_INSUFFICIENT_MEMORY | |
| KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE | |
| KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED | |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_purgeKey | ( | KeyStore_PSA_KeyFileId | key | ) |
Remove non-essential copies of key material from memory.
An implementation is permitted to make additional copies of key material for keys that have been created with the cache policy, an implementation is permitted to make additional copies of the key material that are not in storage and not for the purpose of ongoing operations. This function will remove these extra copies of the key material from memory.
This function is not required to remove key material from memory in any of the following situations:
| [in] | key | Key handle to close. . If this is 0, do nothing and return KEYSTORE_PSA_STATUS_SUCCESS. |
| KEYSTORE_PSA_STATUS_SUCCESS | Handle was valid and the key material that it referred to has been closed. Alternatively, Handle is 0. |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | handle is not a valid handle nor 0. |
| KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE | There was an failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor. |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | The storage is corrupted. Implementations shall make a best effort to erase key material even in this stage, however applications should be aware that it may be impossible to guarantee that the key material is not recoverable in such cases. |
| KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED | An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised. |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_destroyCertificate | ( | KeyStore_PSA_KeyFileId | key | ) |
Destroy a certificate associated with a key.
This function destroys a certificate from both volatile memory and, if applicable, non-volatile storage.
This function also erases any metadata such as policies and frees resources associated with the certificate.
| [in] | key | Key file ID of the key associated with certificate to erase. If key ID portion is 0, do nothing and return KEYSTORE_PSA_STATUS_SUCCESS. |
| KEYSTORE_PSA_STATUS_SUCCESS | ID was a valid ID and the certificate material that it referred to has been erased. Alternatively, ID is 0. |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_NOT_PERMITTED | The certificate cannot be erased because it is read-only, either due to a policy or due to physical restrictions. |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | ID is not a validI D. |
| KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE | There was an failure in communication with the cryptoprocessor. The certificate material may still be present in the cryptoprocessor. |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | The storage is corrupted. Implementations shall make a best effort to erase certificate material even in this stage, however applications should be aware that it may be impossible to guarantee that the certificate material is not recoverable in such cases. |
| KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED | An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised. |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_destroyKey | ( | KeyStore_PSA_KeyFileId | key | ) |
Destroy a key.
This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations shall make a best effort to ensure that that the key material cannot be recovered.
If the key has an associated certificate, KeyStore_PSA_destroyCertificate() must be called to destroy the certificate before destroying the key.
This function also erases any metadata such as policies and frees resources associated with the key.
Destroying the key makes the ID invalid, and the key ID must not be used again by the application.
If a key is currently in use in a multipart operation, then destroying the key will cause the multipart operation to fail.
After a volatile key is destroyed, it is recommended that the implementation does not immediately reuse the same key ID value for a different key. This reduces the risk of an attack that is able to exploit a key identifier reuse vulnerability within an application.
| [in] | key | Key file ID of the key to erase. If key ID portion is 0, do nothing and return KEYSTORE_PSA_STATUS_SUCCESS. |
| KEYSTORE_PSA_STATUS_SUCCESS | ID was a valid ID and the key material that it referred to has been erased. Alternatively, ID is 0. |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_NOT_PERMITTED | The key cannot be erased because it has an associated certificate or is read-only, either due to a policy or due to physical restrictions. |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | ID is not a valid ID. |
| KEYSTORE_PSA_STATUS_COMMUNICATION_FAILURE | There was an failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor. |
| KEYSTORE_PSA_STATUS_STORAGE_FAILURE | The storage is corrupted. Implementations shall make a best effort to erase key material even in this stage, however applications should be aware that it may be impossible to guarantee that the key material is not recoverable in such cases. |
| KEYSTORE_PSA_STATUS_CORRUPTION_DETECTED | An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised. |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |