File crypto.h

Platform Security Architecture cryptography module.

Defines

PSA_CRYPTO_API_VERSION_MAJOR: The major version of this implementation of the PSA Crypto API

PSA_CRYPTO_API_VERSION_MINOR: The minor version of this implementation of the PSA Crypto API

PSA_KEY_DERIVATION_UNLIMITED_CAPACITY

Use the maximum possible capacity for a key derivation operation.

Use this value as the capacity argument when setting up a key derivation to indicate that the operation should have the maximum possible capacity. The value of the maximum possible capacity depends on the key derivation algorithm.

Typedefs

typedef struct psa_hash_operation_s psa_hash_operation_t

The type of the state data structure for multipart hash operations.

Before calling any function on a hash operation object, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:

psa_hash_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the structure to logical zero values, for example:
```
psa_hash_operation_t operation = {0};
```
Initialize the structure to the initializer PSA_HASH_OPERATION_INIT, for example:
```
psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
```
Assign the result of the function psa_hash_operation_init() to the structure, for example:
```
psa_hash_operation_t operation;
operation = psa_hash_operation_init();
```

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

typedef struct psa_mac_operation_s psa_mac_operation_t

The type of the state data structure for multipart MAC operations.

Before calling any function on a MAC operation object, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:

psa_mac_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the structure to logical zero values, for example:
```
psa_mac_operation_t operation = {0};
```
Initialize the structure to the initializer PSA_MAC_OPERATION_INIT, for example:
```
psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
```
Assign the result of the function psa_mac_operation_init() to the structure, for example:
```
psa_mac_operation_t operation;
operation = psa_mac_operation_init();
```

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

typedef struct psa_cipher_operation_s psa_cipher_operation_t

The type of the state data structure for multipart cipher operations.

Before calling any function on a cipher operation object, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:

psa_cipher_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the structure to logical zero values, for example:
```
psa_cipher_operation_t operation = {0};
```
Initialize the structure to the initializer PSA_CIPHER_OPERATION_INIT, for example:
```
psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
```
Assign the result of the function psa_cipher_operation_init() to the structure, for example:
```
psa_cipher_operation_t operation;
operation = psa_cipher_operation_init();
```

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

typedef struct psa_aead_operation_s psa_aead_operation_t

The type of the state data structure for multipart AEAD operations.

Before calling any function on an AEAD operation object, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:

psa_aead_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the structure to logical zero values, for example:
```
psa_aead_operation_t operation = {0};
```
Initialize the structure to the initializer PSA_AEAD_OPERATION_INIT, for example:
```
psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
```
Assign the result of the function psa_aead_operation_init() to the structure, for example:
```
psa_aead_operation_t operation;
operation = psa_aead_operation_init();
```

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

typedef struct psa_key_derivation_s psa_key_derivation_operation_t

The type of the state data structure for key derivation operations.

Before calling any function on a key derivation operation object, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:

psa_key_derivation_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the structure to logical zero values, for example:
```
psa_key_derivation_operation_t operation = {0};
```
Initialize the structure to the initializer PSA_KEY_DERIVATION_OPERATION_INIT, for example:
```
psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
```
Assign the result of the function psa_key_derivation_operation_init() to the structure, for example:
```
psa_key_derivation_operation_t operation;
operation = psa_key_derivation_operation_init();
```

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

typedef struct psa_sign_hash_interruptible_operation_s psa_sign_hash_interruptible_operation_t

The type of the state data structure for interruptible hash signing operations.

Before calling any function on a sign hash operation object, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:

psa_sign_hash_interruptible_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the structure to logical zero values, for example:

psa_sign_hash_interruptible_operation_t operation = {0};

Initialize the structure to the initializer PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT, for example:

psa_sign_hash_interruptible_operation_t operation =
PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT;

Assign the result of the function psa_sign_hash_interruptible_operation_init() to the structure, for example:

psa_sign_hash_interruptible_operation_t operation;
operation = psa_sign_hash_interruptible_operation_init();

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

typedef struct psa_verify_hash_interruptible_operation_s psa_verify_hash_interruptible_operation_t

The type of the state data structure for interruptible hash verification operations.

Before calling any function on a sign hash operation object, the application must initialize it by any of the following means:

Set the structure to all-bits-zero, for example:

psa_verify_hash_interruptible_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the structure to logical zero values, for example:

psa_verify_hash_interruptible_operation_t operation = {0};

Initialize the structure to the initializer PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT, for example:

psa_verify_hash_interruptible_operation_t operation =
PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT;

Assign the result of the function psa_verify_hash_interruptible_operation_init() to the structure, for example:

psa_verify_hash_interruptible_operation_t operation;
operation = psa_verify_hash_interruptible_operation_init();

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

Functions

psa_status_t psa_crypto_init(void)

Library initialization.

Applications must call this function before calling any other function in this module.

Applications may call this function more than once. Once a call succeeds, subsequent calls are guaranteed to succeed.

If the application calls other functions before calling psa_crypto_init(), the behavior is undefined. Implementations are encouraged to either perform the operation as if the library had been initialized or to return PSA_ERROR_BAD_STATE or some other applicable error. In particular, implementations should not return a success status if the lack of initialization may have security implications, for example due to improper seeding of the random number generator.

Return values

PSA_SUCCESS –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_DATA_CORRUPT –

static psa_key_attributes_t psa_key_attributes_init(void): Return an initial value for a key attributes structure.

static void psa_set_key_id(psa_key_attributes_t *attributes, mbedtls_svc_key_id_t 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 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 psa_import_key(), psa_generate_key(), psa_generate_key_ext(), psa_key_derivation_output_key(), psa_key_derivation_output_key_ext() or 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.

Parameters

attributes – [out] The attribute structure to write to.
key – The persistent identifier for the key.

static void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes, mbedtls_key_owner_id_t owner)

Set the owner identifier of a key.

When key identifiers encode key owner identifiers, psa_set_key_id() does not allow to define in key attributes the owner of volatile keys as psa_set_key_id() enforces the key to be persistent.

This function allows to set in key attributes the owner identifier of a key. It is intended to be used for volatile keys. For persistent keys, it is recommended to use the PSA Cryptography API psa_set_key_id() to define the owner of a key.

Parameters

attributes – [out] The attribute structure to write to.
owner – The key owner identifier.

static void psa_set_key_lifetime(psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)

Set the location of a persistent key.

To make a key persistent, you must give it a persistent key identifier with psa_set_key_id(). By default, a key that has a persistent identifier is stored in the default storage area identifier by 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 psa_import_key(), psa_generate_key(), psa_generate_key_ext(), psa_key_derivation_output_key(), psa_key_derivation_output_key_ext() or 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.

Parameters

attributes – [out] The attribute structure to write to.
lifetime – The lifetime for the key. If this is PSA_KEY_LIFETIME_VOLATILE, the key will be volatile, and the key identifier attribute is reset to 0.

static mbedtls_svc_key_id_t psa_get_key_id(const psa_key_attributes_t *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.

Parameters: attributes – [in] The key attribute structure to query.
Returns: The persistent identifier stored in the attribute structure. This value is unspecified if the attribute structure declares the key as volatile.

static psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t *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.

Parameters: attributes – [in] The key attribute structure to query.
Returns: The lifetime value stored in the attribute structure.

static void psa_set_key_usage_flags(psa_key_attributes_t *attributes, psa_key_usage_t 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 psa_key_usage_t.

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.

Parameters

attributes – [out] The attribute structure to write to.
usage_flags – The usage flags to write.

static psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *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.

Parameters: attributes – [in] The key attribute structure to query.
Returns: The usage flags stored in the attribute structure.

static void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t 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:

0 does not allow any cryptographic operation with the key. The key may be used for non-cryptographic actions such as exporting (if permitted by the usage flags).
An algorithm value permits this particular algorithm.
An algorithm wildcard built from PSA_ALG_ANY_HASH allows the specified signature scheme with any hash algorithm.
An algorithm built from PSA_ALG_AT_LEAST_THIS_LENGTH_MAC allows any MAC algorithm from the same base class (e.g. CMAC) which generates/verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm.
An algorithm built from PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG allows any AEAD algorithm from the same base class (e.g. CCM) which generates/verifies a tag length greater than or equal to the length encoded in the wildcard algorithm.

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.

Parameters

attributes – [out] The attribute structure to write to.
alg – The permitted algorithm policy to write.

static psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t *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.

Parameters: attributes – [in] The key attribute structure to query.
Returns: The algorithm stored in the attribute structure.

static void psa_set_key_type(psa_key_attributes_t *attributes, psa_key_type_t 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.

Parameters

attributes – [out] The attribute structure to write to.
type – The key type to write. If this is 0, the key type in attributes becomes unspecified.

static void psa_set_key_bits(psa_key_attributes_t *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.

Parameters

attributes – [out] 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.

static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *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.

Parameters: attributes – [in] The key attribute structure to query.
Returns: The key type stored in the attribute structure.

static size_t psa_get_key_bits(const psa_key_attributes_t *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.

Parameters: attributes – [in] The key attribute structure to query.
Returns: The key size stored in the attribute structure, in bits.

psa_status_t psa_get_key_attributes(mbedtls_svc_key_id_t key, psa_key_attributes_t *attributes)

Retrieve the attributes of a key.

This function first resets the attribute structure as with psa_reset_key_attributes(). It then copies the attributes of the given key into the given attribute structure.

Note

This function may allocate memory or other resources. Once you have called this function on an attribute structure, you must call psa_reset_key_attributes() to free these resources.

Parameters

key – [in] Identifier of the key to query.
attributes – [inout] On success, the attributes of the key. On failure, equivalent to a freshly-initialized structure.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

void psa_reset_key_attributes(psa_key_attributes_t *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 psa_key_attributes_t 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.

Parameters: attributes – [inout] The attribute structure to reset.

psa_status_t psa_purge_key(mbedtls_svc_key_id_t key)

Remove non-essential copies of key material from memory.

If the key identifier designates a volatile key, this functions does not do anything and returns successfully.

If the key identifier designates a persistent key, then this function will free all resources associated with the key in volatile memory. The key data in persistent storage is not affected and the key can still be used.

Parameters

key – Identifier of the key to purge.

Return values

PSA_SUCCESS – The key material will have been removed from memory if it is not currently required.
PSA_ERROR_INVALID_ARGUMENT – key is not a valid key identifier.
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_copy_key(mbedtls_svc_key_id_t source_key, const psa_key_attributes_t *attributes, mbedtls_svc_key_id_t *target_key)

Make a copy of a key.

Copy key material from one location to another.

This function is primarily useful to copy a key from one location to another, since it populates a key using the material from another key which may have a different lifetime.

This function may be used to share a key with a different party, subject to implementation-defined restrictions on key sharing.

The policy on the source key must have the usage flag PSA_KEY_USAGE_COPY set. This flag is sufficient to permit the copy if the key has the lifetime PSA_KEY_LIFETIME_VOLATILE or PSA_KEY_LIFETIME_PERSISTENT. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags PSA_KEY_USAGE_COPY and PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element.

The resulting key may only be used in a way that conforms to both the policy of the original key and the policy specified in the attributes parameter:

The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in attributes.
If both allow the same algorithm or wildcard-based algorithm policy, the resulting key has the same algorithm policy.
If either of the policies allows an algorithm and the other policy allows a wildcard-based algorithm policy that includes this algorithm, the resulting key allows the same algorithm.
If the policies do not allow any algorithm in common, this function fails with the status PSA_ERROR_INVALID_ARGUMENT.

The effect of this function on implementation-defined attributes is implementation-defined.

Parameters

source_key – The key to copy. It must allow the usage PSA_KEY_USAGE_COPY. If a private or secret key is being copied outside of a secure element it must also allow PSA_KEY_USAGE_EXPORT.
attributes – [in] The attributes for the new key. They are used as follows:
- The key type and size may be 0. If either is nonzero, it must match the corresponding attribute of the source key.
- The key location (the lifetime and, for persistent keys, the key identifier) is used directly.
- The policy constraints (usage flags and algorithm policy) are combined from the source key and attributes so that both sets of restrictions apply, as described in the documentation of this function.
target_key – [out] On success, an identifier for the newly created key. For persistent keys, this is the key identifier defined in attributes. 0 on failure.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE – source_key is invalid.
PSA_ERROR_ALREADY_EXISTS – This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT – The lifetime or identifier in attributes are invalid, or the policy constraints on the source and specified in attributes are incompatible, or attributes specifies a key type or key size which does not match the attributes of the source key.
PSA_ERROR_NOT_PERMITTED – The source key does not have the PSA_KEY_USAGE_COPY usage flag, or the source key is not exportable and its lifetime does not allow copying it to the target’s lifetime.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_destroy_key(mbedtls_svc_key_id_t 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 the key material cannot be recovered.

This function also erases any metadata such as policies and frees resources associated with the key.

If a key is currently in use in a multipart operation, then destroying the key will cause the multipart operation to fail.

Warning

We can only guarantee that the the key material will eventually be wiped from memory. With threading enabled and during concurrent execution, copies of the key material may still exist until all threads have finished using the key.

Parameters

key – Identifier of the key to erase. If this is 0, do nothing and return PSA_SUCCESS.

Return values

PSA_SUCCESS – key was a valid identifier and the key material that it referred to has been erased. Alternatively, key is 0.
PSA_ERROR_NOT_PERMITTED – The key cannot be erased because it is read-only, either due to a policy or due to physical restrictions.
PSA_ERROR_INVALID_HANDLE – key is not a valid identifier nor 0.
PSA_ERROR_COMMUNICATION_FAILURE – There was a failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor.
PSA_ERROR_DATA_INVALID – This error is typically a result of either storage corruption on a cleartext storage backend, or an attempt to read data that was written by an incompatible version of the library.
PSA_ERROR_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.
PSA_ERROR_CORRUPTION_DETECTED – An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised.
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_import_key(const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, mbedtls_svc_key_id_t *key)

Import a key in binary format.

This function supports any output from psa_export_key(). Refer to the documentation of psa_export_public_key() for the format of public keys and to the documentation of psa_export_key() for the format for other key types.

The key data determines the key size. The attributes may optionally specify a key size; in this case it must match the size determined from the key data. 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.

Parameters

attributes – [in] 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.
key – [out] On success, an identifier to the newly created key. For persistent keys, this is the key identifier defined in attributes. 0 on failure.
data – [in] 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 psa_export_key() or psa_export_public_key() 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).
data_length – Size of the data buffer in bytes.

Return values

PSA_SUCCESS – Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_ALREADY_EXISTS – This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_NOT_SUPPORTED – The key type or key size is not supported, either by the implementation in general or in this particular persistent location.
PSA_ERROR_INVALID_ARGUMENT – The key attributes, as a whole, are invalid, or the key data is not correctly formatted, or the size in attributes is nonzero and does not match the size of the key data.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_export_key(mbedtls_svc_key_id_t key, uint8_t *data, size_t data_size, size_t *data_length)

Export a key in binary format.

The output of this function can be passed to psa_import_key() to create an equivalent object.

If the implementation of psa_import_key() supports other formats beyond the format specified here, the output from psa_export_key() must use the representation specified here, not the original representation.

For standard key types, the output format is as follows:

For symmetric keys (including MAC keys), the format is the raw bytes of the key.
For DES, the key data consists of 8 bytes. The parity bits must be correct.
For Triple-DES, the format is the concatenation of the two or three DES keys.

For RSA key pairs (PSA_KEY_TYPE_RSA_KEY_PAIR), the format is the non-encrypted DER encoding of the representation defined by PKCS#1 (RFC 8017) as RSAPrivateKey, version 0.

RSAPrivateKey ::= SEQUENCE {
    version             INTEGER,  -- must be 0
    modulus             INTEGER,  -- n
    publicExponent      INTEGER,  -- e
    privateExponent     INTEGER,  -- d
    prime1              INTEGER,  -- p
    prime2              INTEGER,  -- q
    exponent1           INTEGER,  -- d mod (p-1)
    exponent2           INTEGER,  -- d mod (q-1)
    coefficient         INTEGER,  -- (inverse of q) mod p
}

For elliptic curve key pairs (key types for which PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is a representation of the private value as a 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_FAMILY_CURVEXXX), and in big-endian order for Weierstrass curves (curve types PSA_ECC_FAMILY_SECTXXX, PSA_ECC_FAMILY_SECPXXX and PSA_ECC_FAMILY_BRAINPOOL_PXXX). For Weierstrass curves, this is the content of the privateKey field of the ECPrivateKey format defined by RFC 5915. For Montgomery curves, the format is defined by RFC 7748, and output is masked according to §5. For twisted Edwards curves, the private key is as defined by RFC 8032 (a 32-byte string for Edwards25519, a 57-byte string for Edwards448).
For Diffie-Hellman key exchange key pairs (key types for which PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the format is the representation of the private key 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).
For public keys (key types for which PSA_KEY_TYPE_IS_PUBLIC_KEY is true), the format is the same as for psa_export_public_key().

The policy on the key must have the usage flag PSA_KEY_USAGE_EXPORT set.

Parameters

key – Identifier of the key to export. It must allow the usage PSA_KEY_USAGE_EXPORT, unless it is a public key.
data – [out] Buffer where the key data is to be written.
data_size – Size of the data buffer in bytes.
data_length – [out] On success, the number of bytes that make up the key data.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED – The key does not have the PSA_KEY_USAGE_EXPORT flag.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_BUFFER_TOO_SMALL – The size of the data buffer is too small. You can determine a sufficient buffer size by calling PSA_EXPORT_KEY_OUTPUT_SIZE(type, bits) where type is the key type and bits is the key size in bits.
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_export_public_key(mbedtls_svc_key_id_t key, uint8_t *data, size_t data_size, size_t *data_length)

Export a public key or the public part of a key pair in binary format.

The output of this function can be passed to psa_import_key() 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.

For standard key types, the output format is as follows:

For RSA public keys (PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of the representation defined by RFC 3279 2.3.1 as RSAPublicKey.

RSAPublicKey ::= SEQUENCE {
   modulus            INTEGER,    -- n
   publicExponent     INTEGER  }  -- e

For elliptic curve keys on a twisted Edwards curve (key types for which PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true and PSA_KEY_TYPE_ECC_GET_FAMILY returns PSA_ECC_FAMILY_TWISTED_EDWARDS), the public key is as defined by RFC 8032 (a 32-byte string for Edwards25519, a 57-byte string for Edwards448).
For other elliptic curve public keys (key types for which PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format 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:
- The byte 0x04;
- x_P as a ceiling(m/8)-byte string, big-endian;
- y_P as a ceiling(m/8)-byte string, big-endian.
For Diffie-Hellman key exchange public keys (key types for which PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true), the format is the representation of the public key 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.

Parameters

key – Identifier of the key to export.
data – [out] Buffer where the key data is to be written.
data_size – Size of the data buffer in bytes.
data_length – [out] On success, the number of bytes that make up the key data.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_INVALID_ARGUMENT – The key is neither a public key nor a key pair.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_BUFFER_TOO_SMALL – The size of the data buffer is too small. You can determine a sufficient buffer size by calling PSA_EXPORT_KEY_OUTPUT_SIZE(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type), bits) where type is the key type and bits is the key size in bits.
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_hash_compute(psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)

Calculate the hash (digest) of a message.

Note

To verify the hash of a message against an expected value, use psa_hash_compare() instead.

Parameters

alg – The hash algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true).
input – [in] Buffer containing the message to hash.
input_length – Size of the input buffer in bytes.
hash – [out] Buffer where the hash is to be written.
hash_size – Size of the hash buffer in bytes.
hash_length – [out] On success, the number of bytes that make up the hash value. This is always PSA_HASH_LENGTH(alg).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a hash algorithm.
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_BUFFER_TOO_SMALL – hash_size is too small
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_hash_compare(psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *hash, size_t hash_length)

Calculate the hash (digest) of a message and compare it with a reference value.

Parameters

alg – The hash algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true).
input – [in] Buffer containing the message to hash.
input_length – Size of the input buffer in bytes.
hash – [out] Buffer containing the expected hash value.
hash_length – Size of the hash buffer in bytes.

Return values

PSA_SUCCESS – The expected hash is identical to the actual hash of the input.
PSA_ERROR_INVALID_SIGNATURE – The hash of the message was calculated successfully, but it differs from the expected hash.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a hash algorithm.
PSA_ERROR_INVALID_ARGUMENT – input_length or hash_length do not match the hash size for alg
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

static psa_hash_operation_t psa_hash_operation_init(void): Return an initial value for a hash operation object.

psa_status_t psa_hash_setup(psa_hash_operation_t *operation, psa_algorithm_t alg)

Set up a multipart hash operation.

The sequence of operations to calculate a hash (message digest) is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Call psa_hash_setup() to specify the algorithm.
Call psa_hash_update() zero, one or more times, passing a fragment of the message each time. The hash that is calculated is the hash of the concatenation of these messages in order.
To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call psa_hash_verify().

If an error occurs at any step after a call to psa_hash_setup(), the operation will need to be reset by a call to psa_hash_abort(). The application may call psa_hash_abort() at any time after the operation has been initialized.

After a successful call to psa_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_hash_finish() or psa_hash_verify().
A call to psa_hash_abort().

Parameters

operation – [inout] The operation object to set up. It must have been initialized as per the documentation for psa_hash_operation_t and not yet in use.
alg – The hash algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_NOT_SUPPORTED – alg is not a supported hash algorithm.
PSA_ERROR_INVALID_ARGUMENT – alg is not a hash algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_hash_update(psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)

Add a message fragment to a multipart hash operation.

The application must call psa_hash_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Parameters

operation – [inout] Active hash operation.
input – [in] Buffer containing the message fragment to hash.
input_length – Size of the input buffer in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_hash_finish(psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)

Finish the calculation of the hash of a message.

The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Warning

Applications should not call this function if they expect a specific value for the hash. Call psa_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as memcmp is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.

Parameters

operation – [inout] Active hash operation.
hash – [out] Buffer where the hash is to be written.
hash_size – Size of the hash buffer in bytes.
hash_length – [out] On success, the number of bytes that make up the hash value. This is always PSA_HASH_LENGTH(alg) where alg is the hash algorithm that is calculated.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the hash buffer is too small. You can determine a sufficient buffer size by calling PSA_HASH_LENGTH(alg) where alg is the hash algorithm that is calculated.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_hash_verify(psa_hash_operation_t *operation, const uint8_t *hash, size_t hash_length)

Finish the calculation of the hash of a message and compare it with an expected value.

The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update(). It then compares the calculated hash with the expected hash passed as a parameter to this function.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Note

Implementations shall make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.

Parameters

operation – [inout] Active hash operation.
hash – [in] Buffer containing the expected hash value.
hash_length – Size of the hash buffer in bytes.

Return values

PSA_SUCCESS – The expected hash is identical to the actual hash of the message.
PSA_ERROR_INVALID_SIGNATURE – The hash of the message was calculated successfully, but it differs from the expected hash.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_hash_abort(psa_hash_operation_t *operation)

Abort a hash operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_hash_setup() again.

You may call this function any time after the operation object has been initialized by one of the methods described in psa_hash_operation_t.

In particular, calling psa_hash_abort() after the operation has been terminated by a call to psa_hash_abort(), psa_hash_finish() or psa_hash_verify() is safe and has no effect.

Parameters

operation – [inout] Initialized hash operation.

Return values

PSA_SUCCESS –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)

Clone a hash operation.

This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling psa_hash_setup() on target_operation with the same algorithm that source_operation was set up for, then psa_hash_update() on target_operation with the same input that that was passed to source_operation. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.

Parameters

source_operation – [in] The active hash operation to clone.
target_operation – [inout] The operation object to set up. It must be initialized but not active.

Return values

PSA_SUCCESS –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_BAD_STATE – The source_operation state is not valid (it must be active), or the target_operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_mac_compute(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length)

Calculate the MAC (message authentication code) of a message.

Note

To verify the MAC of a message against an expected value, use psa_mac_verify() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as memcmp is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.

Parameters

key – Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg – The MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).
input – [in] Buffer containing the input message.
input_length – Size of the input buffer in bytes.
mac – [out] Buffer where the MAC value is to be written.
mac_size – Size of the mac buffer in bytes.
mac_length – [out] On success, the number of bytes that make up the MAC value.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a MAC algorithm.
PSA_ERROR_BUFFER_TOO_SMALL – mac_size is too small
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE – The key could not be retrieved from storage.
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_mac_verify(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *mac, size_t mac_length)

Calculate the MAC of a message and compare it with a reference value.

Parameters

key – Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg – The MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).
input – [in] Buffer containing the input message.
input_length – Size of the input buffer in bytes.
mac – [out] Buffer containing the expected MAC value.
mac_length – Size of the mac buffer in bytes.

Return values

PSA_SUCCESS – The expected MAC is identical to the actual MAC of the input.
PSA_ERROR_INVALID_SIGNATURE – The MAC of the message was calculated successfully, but it differs from the expected value.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a MAC algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE – The key could not be retrieved from storage.
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

static psa_mac_operation_t psa_mac_operation_init(void): Return an initial value for a MAC operation object.

psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set up a multipart MAC calculation operation.

This function sets up the calculation of the MAC (message authentication code) of a byte string. To verify the MAC of a message against an expected value, use psa_mac_verify_setup() instead.

The sequence of operations to calculate a MAC is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Call psa_mac_sign_setup() to specify the algorithm and key.
Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and retrieve it.

If an error occurs at any step after a call to psa_mac_sign_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.

After a successful call to psa_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods:

A successful call to psa_mac_sign_finish().
A call to psa_mac_abort().

Parameters

operation – [inout] The operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
key – Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg – The MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a MAC algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE – The key could not be retrieved from storage.
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set up a multipart MAC verification operation.

This function sets up the verification of the MAC (message authentication code) of a byte string against an expected value.

The sequence of operations to verify a MAC is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Call psa_mac_verify_setup() to specify the algorithm and key.
Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
At the end of the message, call psa_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value.

If an error occurs at any step after a call to psa_mac_verify_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.

After a successful call to psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:

A successful call to psa_mac_verify_finish().
A call to psa_mac_abort().

Parameters

operation – [inout] The operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
key – Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg – The MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a MAC algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE – The key could not be retrieved from storage.
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_mac_update(psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)

Add a message fragment to a multipart MAC operation.

The application must call psa_mac_sign_setup() or psa_mac_verify_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Parameters

operation – [inout] Active MAC operation.
input – [in] Buffer containing the message fragment to add to the MAC calculation.
input_length – Size of the input buffer in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length)

Finish the calculation of the MAC of a message.

The application must call psa_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Warning

Applications should not call this function if they expect a specific value for the MAC. Call psa_mac_verify_finish() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as memcmp is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.

Parameters

operation – [inout] Active MAC operation.
mac – [out] Buffer where the MAC value is to be written.
mac_size – Size of the mac buffer in bytes.
mac_length – [out] On success, the number of bytes that make up the MAC value. This is always PSA_MAC_LENGTH(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of the key and alg is the MAC algorithm that is calculated.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the mac buffer is too small. You can determine a sufficient buffer size by calling PSA_MAC_LENGTH().
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be an active mac sign operation), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)

Finish the calculation of the MAC of a message and compare it with an expected value.

The application must call psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update(). It then compares the calculated MAC with the expected MAC passed as a parameter to this function.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Note

Implementations shall make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.

Parameters

operation – [inout] Active MAC operation.
mac – [in] Buffer containing the expected MAC value.
mac_length – Size of the mac buffer in bytes.

Return values

PSA_SUCCESS – The expected MAC is identical to the actual MAC of the message.
PSA_ERROR_INVALID_SIGNATURE – The MAC of the message was calculated successfully, but it differs from the expected MAC.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be an active mac verify operation), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_mac_abort(psa_mac_operation_t *operation)

Abort a MAC operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_mac_sign_setup() or psa_mac_verify_setup() again.

You may call this function any time after the operation object has been initialized by one of the methods described in psa_mac_operation_t.

In particular, calling psa_mac_abort() after the operation has been terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or psa_mac_verify_finish() is safe and has no effect.

Parameters

operation – [inout] Initialized MAC operation.

Return values

PSA_SUCCESS –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_encrypt(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)

Encrypt a message using a symmetric cipher.

This function encrypts a message with a random IV (initialization vector). Use the multipart operation interface with a psa_cipher_operation_t object to provide other forms of IV.

Parameters

key – Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg – The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
input – [in] Buffer containing the message to encrypt.
input_length – Size of the input buffer in bytes.
output – [out] Buffer where the output is to be written. The output contains the IV followed by the ciphertext proper.
output_size – Size of the output buffer in bytes.
output_length – [out] On success, the number of bytes that make up the output.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a cipher algorithm.
PSA_ERROR_BUFFER_TOO_SMALL –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_decrypt(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)

Decrypt a message using a symmetric cipher.

This function decrypts a message encrypted with a symmetric cipher.

Parameters

key – Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg – The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).
input – [in] Buffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper.
input_length – Size of the input buffer in bytes.
output – [out] Buffer where the plaintext is to be written.
output_size – Size of the output buffer in bytes.
output_length – [out] On success, the number of bytes that make up the output.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a cipher algorithm.
PSA_ERROR_BUFFER_TOO_SMALL –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

static psa_cipher_operation_t psa_cipher_operation_init(void): Return an initial value for a cipher operation object.

psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart symmetric encryption operation.

The sequence of operations to encrypt a message with a symmetric cipher is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
Call psa_cipher_encrypt_setup() to specify the algorithm and key.
Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to generate or set the IV (initialization vector). You should use psa_cipher_generate_iv() unless the protocol you are implementing requires a specific IV value.
Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
Call psa_cipher_finish().

If an error occurs at any step after a call to psa_cipher_encrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application may call psa_cipher_abort() at any time after the operation has been initialized.

After a successful call to psa_cipher_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_cipher_finish().
A call to psa_cipher_abort().

Parameters

operation – [inout] The operation object to set up. It must have been initialized as per the documentation for psa_cipher_operation_t and not yet in use.
key – Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg – The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a cipher algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart symmetric decryption operation.

The sequence of operations to decrypt a message with a symmetric cipher is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Call psa_cipher_set_iv() with the IV (initialization vector) for the decryption. If the IV is prepended to the ciphertext, you can call psa_cipher_update() on a buffer containing the IV followed by the beginning of the message.
Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
Call psa_cipher_finish().

If an error occurs at any step after a call to psa_cipher_decrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application may call psa_cipher_abort() at any time after the operation has been initialized.

After a successful call to psa_cipher_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_cipher_finish().
A call to psa_cipher_abort().

Parameters

operation – [inout] The operation object to set up. It must have been initialized as per the documentation for psa_cipher_operation_t and not yet in use.
key – Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg – The cipher algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_CIPHER(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a cipher algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, uint8_t *iv, size_t iv_size, size_t *iv_length)

Generate an IV for a symmetric encryption operation.

This function generates a random IV (initialization vector), nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size.

The application must call psa_cipher_encrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters

operation – [inout] Active cipher operation.
iv – [out] Buffer where the generated IV is to be written.
iv_size – Size of the iv buffer in bytes.
iv_length – [out] On success, the number of bytes of the generated IV.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the iv buffer is too small.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active, with no IV set), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length)

Set the IV for a symmetric encryption or decryption operation.

This function sets the IV (initialization vector), nonce or initial counter value for the encryption or decryption operation.

The application must call psa_cipher_encrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Note

When encrypting, applications should use psa_cipher_generate_iv() instead of this function, unless implementing a protocol that requires a non-random IV.

Parameters

operation – [inout] Active cipher operation.
iv – [in] Buffer containing the IV to use.
iv_length – Size of the IV in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – The size of iv is not acceptable for the chosen algorithm, or the chosen algorithm does not use an IV.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be an active cipher encrypt operation, with no IV set), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)

Encrypt or decrypt a message fragment in an active cipher operation.

Before calling this function, you must:

Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
If the algorithm requires an IV, call psa_cipher_generate_iv() (recommended when encrypting) or psa_cipher_set_iv().

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters

operation – [inout] Active cipher operation.
input – [in] Buffer containing the message fragment to encrypt or decrypt.
input_length – Size of the input buffer in bytes.
output – [out] Buffer where the output is to be written.
output_size – Size of the output buffer in bytes.
output_length – [out] On success, the number of bytes that make up the returned output.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the output buffer is too small.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active, with an IV set if required for the algorithm), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length)

Finish encrypting or decrypting a message in a cipher operation.

The application must call psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input.

This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to psa_cipher_update().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters

operation – [inout] Active cipher operation.
output – [out] Buffer where the output is to be written.
output_size – Size of the output buffer in bytes.
output_length – [out] On success, the number of bytes that make up the returned output.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – The total input size passed to this operation is not valid for this particular algorithm. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.
PSA_ERROR_INVALID_PADDING – This is a decryption operation for an algorithm that includes padding, and the ciphertext does not contain valid padding.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the output buffer is too small.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active, with an IV set if required for the algorithm), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation)

Abort a cipher operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.

You may call this function any time after the operation object has been initialized as described in psa_cipher_operation_t.

In particular, calling psa_cipher_abort() after the operation has been terminated by a call to psa_cipher_abort() or psa_cipher_finish() is safe and has no effect.

Parameters

operation – [inout] Initialized cipher operation.

Return values

PSA_SUCCESS –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_encrypt(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)

Process an authenticated encryption operation.

Parameters

key – Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg – The AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
nonce – [in] Nonce or IV to use.
nonce_length – Size of the nonce buffer in bytes.
additional_data – [in] Additional data that will be authenticated but not encrypted.
additional_data_length – Size of additional_data in bytes.
plaintext – [in] Data that will be authenticated and encrypted.
plaintext_length – Size of plaintext in bytes.
ciphertext – [out] Output buffer for the authenticated and encrypted data. The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data.
ciphertext_size – Size of the ciphertext buffer in bytes. This must be appropriate for the selected algorithm and key:
- A sufficient output size is PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) where key_type is the type of key.
- PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) evaluates to the maximum ciphertext size of any supported AEAD encryption.
ciphertext_length – [out] On success, the size of the output in the ciphertext buffer.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not an AEAD algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_BUFFER_TOO_SMALL – ciphertext_size is too small. PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) or PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) can be used to determine the required buffer size.
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_decrypt(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)

Process an authenticated decryption operation.

Parameters

key – Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg – The AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
nonce – [in] Nonce or IV to use.
nonce_length – Size of the nonce buffer in bytes.
additional_data – [in] Additional data that has been authenticated but not encrypted.
additional_data_length – Size of additional_data in bytes.
ciphertext – [in] Data that has been authenticated and encrypted. For algorithms where the encrypted data and the authentication tag are defined as separate inputs, the buffer must contain the encrypted data followed by the authentication tag.
ciphertext_length – Size of ciphertext in bytes.
plaintext – [out] Output buffer for the decrypted data.
plaintext_size – Size of the plaintext buffer in bytes. This must be appropriate for the selected algorithm and key:
- A sufficient output size is PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) where key_type is the type of key.
- PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) evaluates to the maximum plaintext size of any supported AEAD decryption.
plaintext_length – [out] On success, the size of the output in the plaintext buffer.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_INVALID_SIGNATURE – The ciphertext is not authentic.
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not an AEAD algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_BUFFER_TOO_SMALL – plaintext_size is too small. PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) or PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) can be used to determine the required buffer size.
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

static psa_aead_operation_t psa_aead_operation_init(void): Return an initial value for an AEAD operation object.

psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart authenticated encryption operation.

The sequence of operations to encrypt a message with authentication is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
Call psa_aead_encrypt_setup() to specify the algorithm and key.
If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details.
Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or set the nonce. You should use psa_aead_generate_nonce() unless the protocol you are implementing requires a specific nonce value.
Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
Call psa_aead_update() zero, one or more times, passing a fragment of the message to encrypt each time.
Call psa_aead_finish().

If an error occurs at any step after a call to psa_aead_encrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized.

After a successful call to psa_aead_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_aead_finish().
A call to psa_aead_abort().

Parameters

operation – [inout] The operation object to set up. It must have been initialized as per the documentation for psa_aead_operation_t and not yet in use.
key – Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg – The AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init().
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not an AEAD algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)

Set the key for a multipart authenticated decryption operation.

The sequence of operations to decrypt a message with authentication is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
Call psa_aead_decrypt_setup() to specify the algorithm and key.
If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details.
Call psa_aead_set_nonce() with the nonce for the decryption.
Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
Call psa_aead_update() zero, one or more times, passing a fragment of the ciphertext to decrypt each time.
Call psa_aead_verify().

If an error occurs at any step after a call to psa_aead_decrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized.

After a successful call to psa_aead_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_aead_verify().
A call to psa_aead_abort().

Parameters

operation – [inout] The operation object to set up. It must have been initialized as per the documentation for psa_aead_operation_t and not yet in use.
key – Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg – The AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not an AEAD algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation, uint8_t *nonce, size_t nonce_size, size_t *nonce_length)

Generate a random nonce for an authenticated encryption operation.

This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.

The application must call psa_aead_encrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Parameters

operation – [inout] Active AEAD operation.
nonce – [out] Buffer where the generated nonce is to be written.
nonce_size – Size of the nonce buffer in bytes.
nonce_length – [out] On success, the number of bytes of the generated nonce.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the nonce buffer is too small.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be an active aead encrypt operation, with no nonce set), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_length)

Set the nonce for an authenticated encryption or decryption operation.

This function sets the nonce for the authenticated encryption or decryption operation.

The application must call psa_aead_encrypt_setup() or psa_aead_decrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Note

When encrypting, applications should use psa_aead_generate_nonce() instead of this function, unless implementing a protocol that requires a non-random IV.

Parameters

operation – [inout] Active AEAD operation.
nonce – [in] Buffer containing the nonce to use.
nonce_length – Size of the nonce in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – The size of nonce is not acceptable for the chosen algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active, with no nonce set), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length)

Declare the lengths of the message and additional data for AEAD.

The application must call this function before calling psa_aead_update_ad() or psa_aead_update() if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.

You may call this function before or after setting the nonce with psa_aead_set_nonce() or psa_aead_generate_nonce().

For PSA_ALG_CCM, calling this function is required.
For the other AEAD algorithms defined in this specification, calling this function is not required.
For vendor-defined algorithm, refer to the vendor documentation.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Parameters

operation – [inout] Active AEAD operation.
ad_length – Size of the non-encrypted additional authenticated data in bytes.
plaintext_length – Size of the plaintext to encrypt in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – At least one of the lengths is not acceptable for the chosen algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active, and psa_aead_update_ad() and psa_aead_update() must not have been called yet), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation, const uint8_t *input, size_t input_length)

Pass additional data to an active AEAD operation.

Additional data is authenticated, but not encrypted.

You may call this function multiple times to pass successive fragments of the additional data. You may not call this function after passing data to encrypt or decrypt with psa_aead_update().

Before calling this function, you must:

Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Warning

When decrypting, until psa_aead_verify() has returned PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned PSA_SUCCESS, treat the input as untrusted and prepare to undo any action that depends on the input if psa_aead_verify() returns an error status.

Parameters

operation – [inout] Active AEAD operation.
input – [in] Buffer containing the fragment of additional data.
input_length – Size of the input buffer in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – The total input length overflows the additional data length that was previously specified with psa_aead_set_lengths().
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active, have a nonce set, have lengths set if required by the algorithm, and psa_aead_update() must not have been called yet), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_update(psa_aead_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)

Encrypt or decrypt a message fragment in an active AEAD operation.

Before calling this function, you must:

Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
Call psa_aead_update_ad() to pass all the additional data.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it may delay the end of the corresponding output until a subsequent call to psa_aead_update(), psa_aead_finish() or psa_aead_verify() provides sufficient input. The amount of data that can be delayed in this way is bounded by PSA_AEAD_UPDATE_OUTPUT_SIZE.

Warning

When decrypting, until psa_aead_verify() has returned PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned PSA_SUCCESS:

Do not use the output in any way other than storing it in a confidential location. If you take any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out not to be valid. Furthermore, if an adversary can observe that this action took place (for example through timing), they may be able to use this fact as an oracle to decrypt any message encrypted with the same key.
In particular, do not copy the output anywhere but to a memory or storage space that you have exclusive access to.

Parameters

operation – [inout] Active AEAD operation.
input – [in] Buffer containing the message fragment to encrypt or decrypt.
input_length – Size of the input buffer in bytes.
output – [out] Buffer where the output is to be written.
output_size – Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key:
- A sufficient output size is PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
- PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) evaluates to the maximum output size of any supported AEAD algorithm.
output_length – [out] On success, the number of bytes that make up the returned output.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the output buffer is too small. PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) or PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) can be used to determine the required buffer size.
PSA_ERROR_INVALID_ARGUMENT – The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(), or the total input length overflows the plaintext length that was previously specified with psa_aead_set_lengths().
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active, have a nonce set, and have lengths set if required by the algorithm), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_finish(psa_aead_operation_t *operation, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length, uint8_t *tag, size_t tag_size, size_t *tag_length)

Finish encrypting a message in an AEAD operation.

The operation must have been set up with psa_aead_encrypt_setup().

This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to psa_aead_update().

This function has two output buffers:

ciphertext contains trailing ciphertext that was buffered from preceding calls to psa_aead_update().
tag contains the authentication tag.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Parameters

operation – [inout] Active AEAD operation.
ciphertext – [out] Buffer where the last part of the ciphertext is to be written.
ciphertext_size – Size of the ciphertext buffer in bytes. This must be appropriate for the selected algorithm and key:
- A sufficient output size is PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
- PSA_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.
ciphertext_length – [out] On success, the number of bytes of returned ciphertext.
tag – [out] Buffer where the authentication tag is to be written.
tag_size – Size of the tag buffer in bytes. This must be appropriate for the selected algorithm and key:
- The exact tag size is PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size of the key, and alg is the algorithm that were used in the call to psa_aead_encrypt_setup().
- PSA_AEAD_TAG_MAX_SIZE evaluates to the maximum tag size of any supported AEAD algorithm.
tag_length – [out] On success, the number of bytes that make up the returned tag.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the ciphertext or tag buffer is too small. PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) or PSA_AEAD_FINISH_OUTPUT_MAX_SIZE can be used to determine the required ciphertext buffer size. PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) or PSA_AEAD_TAG_MAX_SIZE can be used to determine the required tag buffer size.
PSA_ERROR_INVALID_ARGUMENT – The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(), or the total length of input to psa_aead_update() so far is less than the plaintext length that was previously specified with psa_aead_set_lengths().
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be an active encryption operation with a nonce set), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_verify(psa_aead_operation_t *operation, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length, const uint8_t *tag, size_t tag_length)

Finish authenticating and decrypting a message in an AEAD operation.

The operation must have been set up with psa_aead_decrypt_setup().

This function finishes the authenticated decryption of the message components:

The additional data consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update_ad().
The ciphertext consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update().
The tag passed to this function call.

If the authentication tag is correct, this function outputs any remaining plaintext and reports success. If the authentication tag is not correct, this function returns PSA_ERROR_INVALID_SIGNATURE.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Note

Implementations shall make the best effort to ensure that the comparison between the actual tag and the expected tag is performed in constant time.

Parameters

operation – [inout] Active AEAD operation.
plaintext – [out] Buffer where the last part of the plaintext is to be written. This is the remaining data from previous calls to psa_aead_update() that could not be processed until the end of the input.
plaintext_size – Size of the plaintext buffer in bytes. This must be appropriate for the selected algorithm and key:
- A sufficient output size is PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
- PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.
plaintext_length – [out] On success, the number of bytes of returned plaintext.
tag – [in] Buffer containing the authentication tag.
tag_length – Size of the tag buffer in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_SIGNATURE – The calculations were successful, but the authentication tag is not correct.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the plaintext buffer is too small. PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) or PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE can be used to determine the required buffer size.
PSA_ERROR_INVALID_ARGUMENT – The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(), or the total length of input to psa_aead_update() so far is less than the plaintext length that was previously specified with psa_aead_set_lengths().
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be an active decryption operation with a nonce set), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_aead_abort(psa_aead_operation_t *operation)

Abort an AEAD operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.

You may call this function any time after the operation object has been initialized as described in psa_aead_operation_t.

In particular, calling psa_aead_abort() after the operation has been terminated by a call to psa_aead_abort(), psa_aead_finish() or psa_aead_verify() is safe and has no effect.

Parameters

operation – [inout] Initialized AEAD operation.

Return values

PSA_SUCCESS –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_sign_message(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.

Note

To perform a multi-part hash-and-sign signature algorithm, first use a multi-part hash operation and then pass the resulting hash to psa_sign_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.

Parameters

key – [in] Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg – [in] An asymmetric signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_MESSAGE(alg) is true), that is compatible with the type of key.
input – [in] The input message to sign.
input_length – [in] Size of the input buffer in bytes.
signature – [out] Buffer where the signature is to be written.
signature_size – [in] Size of the signature buffer in bytes. This must be appropriate for the selected algorithm and key:
- The required signature size is PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
- PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.
signature_length – [out] On success, the number of bytes that make up the returned signature value.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED – The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the signature buffer is too small. You can determine a sufficient buffer size by calling PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_verify_message(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)

Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.

Note

To perform a multi-part hash-and-sign signature verification algorithm, first use a multi-part hash operation to hash the message and then pass the resulting hash to psa_verify_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.

Parameters

key – [in] Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg – [in] An asymmetric signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_MESSAGE(alg) is true), that is compatible with the type of key.
input – [in] The message whose signature is to be verified.
input_length – [in] Size of the input buffer in bytes.
signature – [out] Buffer containing the signature to verify.
signature_length – [in] Size of the signature buffer in bytes.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED – The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
PSA_ERROR_INVALID_SIGNATURE – The calculation was performed successfully, but the passed signature is not a valid signature.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_sign_hash(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length)

Sign a hash or short message with a private key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling psa_hash_setup(), psa_hash_update() and psa_hash_finish(), or alternatively by calling psa_hash_compute(). Then pass the resulting hash as the hash parameter to this function. You can use PSA_ALG_SIGN_GET_HASH(alg) to determine the hash algorithm to use.

Parameters

key – Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_HASH.
alg – A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(alg) is true), that is compatible with the type of key.
hash – [in] The hash or message to sign.
hash_length – Size of the hash buffer in bytes.
signature – [out] Buffer where the signature is to be written.
signature_size – Size of the signature buffer in bytes.
signature_length – [out] On success, the number of bytes that make up the returned signature value.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_BUFFER_TOO_SMALL – The size of the signature buffer is too small. You can determine a sufficient buffer size by calling PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_verify_hash(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)

Verify the signature of a hash or short message using a public key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling psa_hash_setup(), psa_hash_update() and psa_hash_finish(), or alternatively by calling psa_hash_compute(). Then pass the resulting hash as the hash parameter to this function. You can use PSA_ALG_SIGN_GET_HASH(alg) to determine the hash algorithm to use.

Parameters

key – Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
alg – A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(alg) is true), that is compatible with the type of key.
hash – [in] The hash or message whose signature is to be verified.
hash_length – Size of the hash buffer in bytes.
signature – [in] Buffer containing the signature to verify.
signature_length – Size of the signature buffer in bytes.

Return values

PSA_SUCCESS – The signature is valid.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_SIGNATURE – The calculation was performed successfully, but the passed signature is not a valid signature.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_asymmetric_encrypt(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)

Encrypt a short message with a public key.

For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

Parameters

salt_length – Size of the salt buffer in bytes. If salt is NULL, pass 0.
output – [out] Buffer where the encrypted message is to be written.
output_size – Size of the output buffer in bytes.
output_length – [out] On success, the number of bytes that make up the returned output.
key – Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg – An asymmetric encryption algorithm that is compatible with the type of key.
input – [in] The message to encrypt.
input_length – Size of the input buffer in bytes.
salt – [in] A salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass NULL. If the algorithm supports an optional salt and you do not want to pass a salt, pass NULL.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_BUFFER_TOO_SMALL – The size of the output buffer is too small. You can determine a sufficient buffer size by calling PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_asymmetric_decrypt(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)

Decrypt a short message with a private key.

For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

Parameters

salt_length – Size of the salt buffer in bytes. If salt is NULL, pass 0.
output – [out] Buffer where the decrypted message is to be written.
output_size – Size of the output buffer in bytes.
output_length – [out] On success, the number of bytes that make up the returned output.
key – Identifier of the key to use for the operation. It must be an asymmetric key pair. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg – An asymmetric encryption algorithm that is compatible with the type of key.
input – [in] The message to decrypt.
input_length – Size of the input buffer in bytes.
salt – [in] A salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass NULL. If the algorithm supports an optional salt and you do not want to pass a salt, pass NULL.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_BUFFER_TOO_SMALL – The size of the output buffer is too small. You can determine a sufficient buffer size by calling PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_INVALID_PADDING –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

static psa_key_derivation_operation_t psa_key_derivation_operation_init(void): Return an initial value for a key derivation operation object.

psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t *operation, psa_algorithm_t alg)

Set up a key derivation operation.

A key derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic way. This byte stream can be used to produce keys and other cryptographic material.

To derive a key:

Start with an initialized object of type psa_key_derivation_operation_t.
Call psa_key_derivation_setup() to select the algorithm.
Provide the inputs for the key derivation by calling psa_key_derivation_input_bytes() or psa_key_derivation_input_key() as appropriate. Which inputs are needed, in what order, and whether they may be keys and if so of what type depends on the algorithm.
Optionally set the operation’s maximum capacity with psa_key_derivation_set_capacity(). You may do this before, in the middle of or after providing inputs. For some algorithms, this step is mandatory because the output depends on the maximum capacity.
To derive a key, call psa_key_derivation_output_key() or psa_key_derivation_output_key_ext(). To derive a byte string for a different purpose, call psa_key_derivation_output_bytes(). Successive calls to these functions use successive output bytes calculated by the key derivation algorithm.
Clean up the key derivation operation object with psa_key_derivation_abort().

If this function returns an error, the key derivation operation object is not changed.

If an error occurs at any step after a call to psa_key_derivation_setup(), the operation will need to be reset by a call to psa_key_derivation_abort().

Implementations must reject an attempt to derive a key of size 0.

Parameters

operation – [inout] The key derivation operation object to set up. It must have been initialized but not set up yet.
alg – The key derivation algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_KEY_DERIVATION(alg) is true).

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – alg is not a key derivation algorithm.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a key derivation algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t *operation, size_t *capacity)

Retrieve the current capacity of a key derivation operation.

The capacity of a key derivation is the maximum number of bytes that it can return. When you get N bytes of output from a key derivation operation, this reduces its capacity by N.

Parameters

operation – [in] The operation to query.
capacity – [out] On success, the capacity of the operation.

Return values

PSA_SUCCESS –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t *operation, size_t capacity)

Set the maximum capacity of a key derivation operation.

The capacity of a key derivation operation is the maximum number of bytes that the key derivation operation can return from this point onwards.

Parameters

operation – [inout] The key derivation operation object to modify.
capacity – The new capacity of the operation. It must be less or equal to the operation’s current capacity.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_ARGUMENT – capacity is larger than the operation’s current capacity. In this case, the operation object remains valid and its capacity remains unchanged.
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_input_bytes(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, const uint8_t *data, size_t data_length)

Provide an input for key derivation or key agreement.

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function passes direct inputs, which is usually correct for non-secret inputs. To pass a secret input, which should be in a key object, call psa_key_derivation_input_key() instead of this function. Refer to the documentation of individual step types (PSA_KEY_DERIVATION_INPUT_xxx values of type psa_key_derivation_step_t) for more information.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation – [inout] The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
step – Which step the input data is for.
data – [in] Input data to use.
data_length – Size of the data buffer in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – step is not compatible with the operation’s algorithm, or step does not allow direct inputs.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid for this input step, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_input_integer(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, uint64_t value)

Provide a numeric input for key derivation or key agreement.

Which inputs are required and in what order depends on the algorithm. However, when an algorithm requires a particular order, numeric inputs usually come first as they tend to be configuration parameters. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function is used for inputs which are fixed-size non-negative integers.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation – [inout] The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
step – Which step the input data is for.
value – [in] The value of the numeric input.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_ARGUMENT – step is not compatible with the operation’s algorithm, or step does not allow numeric inputs.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid for this input step, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, mbedtls_svc_key_id_t key)

Provide an input for key derivation in the form of a key.

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function obtains input from a key object, which is usually correct for secret inputs or for non-secret personalization strings kept in the key store. To pass a non-secret parameter which is not in the key store, call psa_key_derivation_input_bytes() instead of this function. Refer to the documentation of individual step types (PSA_KEY_DERIVATION_INPUT_xxx values of type psa_key_derivation_step_t) for more information.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Note

Once all inputs steps are completed, the operations will allow:

psa_key_derivation_output_bytes() if each input was either a direct input or a key with PSA_KEY_USAGE_DERIVE set;
psa_key_derivation_output_key() or psa_key_derivation_output_key_ext() if the input for step PSA_KEY_DERIVATION_INPUT_SECRET or PSA_KEY_DERIVATION_INPUT_PASSWORD was from a key slot with PSA_KEY_USAGE_DERIVE and each other input was either a direct input or a key with PSA_KEY_USAGE_DERIVE set;
psa_key_derivation_verify_bytes() if each input was either a direct input or a key with PSA_KEY_USAGE_VERIFY_DERIVATION set;
psa_key_derivation_verify_key() under the same conditions as psa_key_derivation_verify_bytes().

Parameters

operation – [inout] The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
step – Which step the input data is for.
key – Identifier of the key. It must have an appropriate type for step and must allow the usage PSA_KEY_USAGE_DERIVE or PSA_KEY_USAGE_VERIFY_DERIVATION (see note) and the algorithm used by the operation.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED – The key allows neither PSA_KEY_USAGE_DERIVE nor PSA_KEY_USAGE_VERIFY_DERIVATION, or it doesn’t allow this algorithm.
PSA_ERROR_INVALID_ARGUMENT – step is not compatible with the operation’s algorithm, or step does not allow key inputs of the given type or does not allow key inputs at all.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid for this input step, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_key_agreement(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, mbedtls_svc_key_id_t private_key, const uint8_t *peer_key, size_t peer_key_length)

Perform a key agreement and use the shared secret as input to a key derivation.

A key agreement algorithm takes two inputs: a private key private_key a public key peer_key. The result of this function is passed as input to a key derivation. The output of this key derivation can be extracted by reading from the resulting operation to produce keys and other cryptographic material.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation – [inout] The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() with a key agreement and derivation algorithm alg (PSA_ALG_XXX value such that PSA_ALG_IS_KEY_AGREEMENT(alg) is true and PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) is false). The operation must be ready for an input of the type given by step.
step – Which step the input data is for.
private_key – Identifier of the private key to use. It must allow the usage PSA_KEY_USAGE_DERIVE.
peer_key – [in] Public key of the peer. The peer key must be in the same format that psa_import_key() accepts for the public key type corresponding to the type of private_key. That is, this function performs the equivalent of psa_import_key(…, peer_key, peer_key_length) where with key attributes indicating the public key type corresponding to the type of private_key. For example, for EC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of psa_export_public_key().
peer_key_length – Size of peer_key in bytes.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – private_key is not compatible with alg, or peer_key is not valid for alg or not compatible with private_key, or step does not allow an input resulting from a key agreement.
PSA_ERROR_NOT_SUPPORTED – alg is not supported or is not a key derivation algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid for this key agreement step, or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t *operation, uint8_t *output, size_t output_length)

Read some data from a key derivation operation.

This function calculates output bytes from a key derivation algorithm and return those bytes. If you view the key derivation’s output as a stream of bytes, this function destructively reads the requested number of bytes from the stream. The operation’s capacity decreases by the number of bytes read.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation – [inout] The key derivation operation object to read from.
output – [out] Buffer where the output will be written.
output_length – Number of bytes to output.

Return values

PSA_SUCCESS –
PSA_ERROR_NOT_PERMITTED – One of the inputs was a key whose policy didn’t allow PSA_KEY_USAGE_DERIVE.
PSA_ERROR_INSUFFICIENT_DATA – The operation’s capacity was less than output_length bytes. Note that in this case, no output is written to the output buffer. The operation’s capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller output buffer.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active and completed all required input steps), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_output_key(const psa_key_attributes_t *attributes, psa_key_derivation_operation_t *operation, mbedtls_svc_key_id_t *key)

Derive a key from an ongoing key derivation operation.

This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key’s location, usage policy, type and size are taken from attributes.

If you view the key derivation’s output as a stream of bytes, this function destructively reads as many bytes as required from the stream. The operation’s capacity decreases by the number of bytes read.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

How much output is produced and consumed from the operation, and how the key is derived, depends on the key type and on the key size (denoted bits below):

For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling psa_key_derivation_output_bytes and passing the resulting output to psa_import_key. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly (bits / 8) bytes from the operation. The following key types defined in this specification follow this scheme:
For ECC keys on a Montgomery elliptic curve (PSA_KEY_TYPE_ECC_KEY_PAIR(curve) where curve designates a Montgomery curve), this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is:
- Curve25519 (PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte string and process it as specified in RFC 7748 5.
- Curve448 (PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte string and process it as specified in RFC 7748 5.
For key types for which the key is represented by a single sequence of bits bits with constraints as to which bit sequences are acceptable, this function draws a byte string of length (bits / 8) bytes rounded up to the nearest whole number of bytes. If the resulting byte string is acceptable, it becomes the key, otherwise the drawn bytes are discarded. This process is repeated until an acceptable byte string is drawn. The byte string drawn from the operation is interpreted as specified for the output produced by psa_export_key(). The following key types defined in this specification follow this scheme:
- PSA_KEY_TYPE_DES. Force-set the parity bits, but discard forbidden weak keys. For 2-key and 3-key triple-DES, the three keys are generated successively (for example, for 3-key triple-DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys).
- Finite-field Diffie-Hellman keys (PSA_KEY_TYPE_DH_KEY_PAIR(group) where group designates any Diffie-Hellman group) and ECC keys on a Weierstrass elliptic curve (PSA_KEY_TYPE_ECC_KEY_PAIR(curve) where curve designates a Weierstrass curve). For these key types, interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, N - 2] where N is the boundary of the private key domain (the prime p for Diffie-Hellman, the subprime q for DSA, or the order of the curve’s base point for ECC). Add 1 to the resulting integer and use this as the private key x. This method allows compliance to NIST standards, specifically the methods titled “key-pair generation by testing candidates” in NIST SP 800-56A 5.6.1.1.4 for Diffie-Hellman, in FIPS 186-4 B.1.2 for DSA, and in NIST SP 800-56A 5.6.1.2.2 or FIPS 186-4 B.4.2 for elliptic curve keys.
For other key types, including PSA_KEY_TYPE_RSA_KEY_PAIR, the way in which the operation output is consumed is implementation-defined.

In all cases, the data that is read is discarded from the operation. The operation’s capacity is decreased by the number of bytes read.

For algorithms that take an input step PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be provided with psa_key_derivation_input_key(). Future versions of this specification may include additional restrictions on the derived key based on the attributes and strength of the secret key.

Note

This function is equivalent to calling psa_key_derivation_output_key_ext() with the production parameters PSA_KEY_PRODUCTION_PARAMETERS_INIT and params_data_length == 0 (i.e. params->data is empty).

Parameters

attributes – [in] The attributes for the new key. If the key type to be created is PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in the policy must be the same as in the current operation.
operation – [inout] The key derivation operation object to read from.
key – [out] On success, an identifier for the newly created key. For persistent keys, this is the key identifier defined in attributes. 0 on failure.

Return values

PSA_SUCCESS – Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_ALREADY_EXISTS – This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INSUFFICIENT_DATA – There was not enough data to create the desired key. Note that in this case, no output is written to the output buffer. The operation’s capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller output buffer.
PSA_ERROR_NOT_SUPPORTED – The key type or key size is not supported, either by the implementation in general or in this particular location.
PSA_ERROR_INVALID_ARGUMENT – The provided key attributes are not valid for the operation.
PSA_ERROR_NOT_PERMITTED – The PSA_KEY_DERIVATION_INPUT_SECRET or PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a key; or one of the inputs was a key whose policy didn’t allow PSA_KEY_USAGE_DERIVE.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active and completed all required input steps), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_output_key_ext(const psa_key_attributes_t *attributes, psa_key_derivation_operation_t *operation, const psa_key_production_parameters_t *params, size_t params_data_length, mbedtls_svc_key_id_t *key)

Derive a key from an ongoing key derivation operation with custom production parameters.

See the description of psa_key_derivation_out_key() for the operation of this function with the default production parameters. Mbed TLS currently does not currently support any non-default production parameters.

Note

This function is experimental and may change in future minor versions of Mbed TLS.

Parameters

attributes – [in] The attributes for the new key. If the key type to be created is PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in the policy must be the same as in the current operation.
operation – [inout] The key derivation operation object to read from.
params – [in] Customization parameters for the key derivation. When this is PSA_KEY_PRODUCTION_PARAMETERS_INIT with params_data_length = 0, this function is equivalent to psa_key_derivation_output_key(). Mbed TLS currently only supports the default production parameters, i.e. PSA_KEY_PRODUCTION_PARAMETERS_INIT, for all key types.
params_data_length – Length of params->data in bytes.
key – [out] On success, an identifier for the newly created key. For persistent keys, this is the key identifier defined in attributes. 0 on failure.

Return values

PSA_SUCCESS – Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_ALREADY_EXISTS – This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INSUFFICIENT_DATA – There was not enough data to create the desired key. Note that in this case, no output is written to the output buffer. The operation’s capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller output buffer.
PSA_ERROR_NOT_SUPPORTED – The key type or key size is not supported, either by the implementation in general or in this particular location.
PSA_ERROR_INVALID_ARGUMENT – The provided key attributes are not valid for the operation.
PSA_ERROR_NOT_PERMITTED – The PSA_KEY_DERIVATION_INPUT_SECRET or PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a key; or one of the inputs was a key whose policy didn’t allow PSA_KEY_USAGE_DERIVE.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active and completed all required input steps), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_verify_bytes(psa_key_derivation_operation_t *operation, const uint8_t *expected_output, size_t output_length)

Compare output data from a key derivation operation to an expected value.

This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value in constant time. If you view the key derivation’s output as a stream of bytes, this function destructively reads the expected number of bytes from the stream before comparing them. The operation’s capacity decreases by the number of bytes read.

This is functionally equivalent to the following code:

psa_key_derivation_output_bytes(operation, tmp, output_length);
if (memcmp(output, tmp, output_length) != 0)
    return PSA_ERROR_INVALID_SIGNATURE;

except (1) it works even if the key’s policy does not allow outputting the bytes, and (2) the comparison will be done in constant time.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation – [inout] The key derivation operation object to read from.
expected_output – [in] Buffer containing the expected derivation output.
output_length – Length of the expected output; this is also the number of bytes that will be read.

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_SIGNATURE – The output was read successfully, but it differs from the expected output.
PSA_ERROR_NOT_PERMITTED – One of the inputs was a key whose policy didn’t allow PSA_KEY_USAGE_VERIFY_DERIVATION.
PSA_ERROR_INSUFFICIENT_DATA – The operation’s capacity was less than output_length bytes. Note that in this case, the operation’s capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller expected output.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active and completed all required input steps), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_verify_key(psa_key_derivation_operation_t *operation, psa_key_id_t expected)

Compare output data from a key derivation operation to an expected value stored in a key object.

This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value, provided as key of type PSA_KEY_TYPE_PASSWORD_HASH. If you view the key derivation’s output as a stream of bytes, this function destructively reads the number of bytes corresponding to the length of the expected value from the stream before comparing them. The operation’s capacity decreases by the number of bytes read.

This is functionally equivalent to exporting the key and calling psa_key_derivation_verify_bytes() on the result, except that it works even if the key cannot be exported.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation – [inout] The key derivation operation object to read from.
expected – [in] A key of type PSA_KEY_TYPE_PASSWORD_HASH containing the expected output. Its policy must include the PSA_KEY_USAGE_VERIFY_DERIVATION flag and the permitted algorithm must match the operation. The value of this key was likely computed by a previous call to psa_key_derivation_output_key() or psa_key_derivation_output_key_ext().

Return values

PSA_SUCCESS –
PSA_ERROR_INVALID_SIGNATURE – The output was read successfully, but if differs from the expected output.
PSA_ERROR_INVALID_HANDLE – The key passed as the expected value does not exist.
PSA_ERROR_INVALID_ARGUMENT – The key passed as the expected value has an invalid type.
PSA_ERROR_NOT_PERMITTED – The key passed as the expected value does not allow this usage or this algorithm; or one of the inputs was a key whose policy didn’t allow PSA_KEY_USAGE_VERIFY_DERIVATION.
PSA_ERROR_INSUFFICIENT_DATA – The operation’s capacity was less than the length of the expected value. In this case, the operation’s capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller expected output.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The operation state is not valid (it must be active and completed all required input steps), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t *operation)

Abort a key derivation operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_key_derivation_setup() again.

This function may be called at any time after the operation object has been initialized as described in psa_key_derivation_operation_t.

In particular, it is valid to call psa_key_derivation_abort() twice, or to call psa_key_derivation_abort() on an operation that has not been set up.

Parameters

operation – [inout] The operation to abort.

Return values

PSA_SUCCESS –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, mbedtls_svc_key_id_t private_key, const uint8_t *peer_key, size_t peer_key_length, uint8_t *output, size_t output_size, size_t *output_length)

Perform a key agreement and return the raw shared secret.

Warning

The raw result of a key agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should not be used directly as key material. It should instead be passed as input to a key derivation algorithm. To chain a key agreement with a key derivation, use psa_key_derivation_key_agreement() and other functions from the key derivation interface.

Parameters

alg – The key agreement algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) is true).
private_key – Identifier of the private key to use. It must allow the usage PSA_KEY_USAGE_DERIVE.
peer_key – [in] Public key of the peer. It must be in the same format that psa_import_key() accepts. The standard formats for public keys are documented in the documentation of psa_export_public_key().
peer_key_length – Size of peer_key in bytes.
output – [out] Buffer where the decrypted message is to be written.
output_size – Size of the output buffer in bytes.
output_length – [out] On success, the number of bytes that make up the returned output.

Return values

PSA_SUCCESS – Success.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED –
PSA_ERROR_INVALID_ARGUMENT – alg is not a key agreement algorithm, or private_key is not compatible with alg, or peer_key is not valid for alg or not compatible with private_key.
PSA_ERROR_BUFFER_TOO_SMALL – output_size is too small
PSA_ERROR_NOT_SUPPORTED – alg is not a supported key agreement algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_generate_random(uint8_t *output, size_t output_size)

Generate random bytes.

Note

To generate a key, use psa_generate_key() instead.

Warning

This function can fail! Callers MUST check the return status and MUST NOT use the content of the output buffer if the return status is not PSA_SUCCESS.

Parameters

output – [out] Output buffer for the generated data.
output_size – Number of bytes to generate and output.

Return values

PSA_SUCCESS –
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_generate_key(const psa_key_attributes_t *attributes, mbedtls_svc_key_id_t *key)

Generate a key or key pair.

The key is generated randomly. Its location, usage policy, type and size are taken from attributes.

Implementations must reject an attempt to generate a key of size 0.

The following type-specific considerations apply:

For RSA keys (PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.

Note

This function is equivalent to calling psa_generate_key_ext() with the production parameters PSA_KEY_PRODUCTION_PARAMETERS_INIT and params_data_length == 0 (i.e. params->data is empty).

Parameters

attributes – [in] The attributes for the new key.
key – [out] On success, an identifier for the newly created key. For persistent keys, this is the key identifier defined in attributes. 0 on failure.

Return values

PSA_SUCCESS – Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_ALREADY_EXISTS – This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_generate_key_ext(const psa_key_attributes_t *attributes, const psa_key_production_parameters_t *params, size_t params_data_length, mbedtls_svc_key_id_t *key)

Generate a key or key pair using custom production parameters.

See the description of psa_generate_key() for the operation of this function with the default production parameters. In addition, this function supports the following production customizations, described in more detail in the documentation of psa_key_production_parameters_t:

RSA keys: generation with a custom public exponent.

Note

This function is experimental and may change in future minor versions of Mbed TLS.

Parameters

attributes – [in] The attributes for the new key.
params – [in] Customization parameters for the key generation. When this is PSA_KEY_PRODUCTION_PARAMETERS_INIT with params_data_length = 0, this function is equivalent to psa_generate_key().
params_data_length – Length of params->data in bytes.
key – [out] On success, an identifier for the newly created key. For persistent keys, this is the key identifier defined in attributes. 0 on failure.

Return values

PSA_SUCCESS – Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_ALREADY_EXISTS – This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_INSUFFICIENT_STORAGE –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

void psa_interruptible_set_max_ops(uint32_t max_ops)

Set the maximum number of ops allowed to be executed by an interruptible function in a single call.

Note

The time taken to execute a single op is implementation specific and depends on software, hardware, the algorithm, key type and curve chosen. Even within a single operation, successive ops can take differing amounts of time. The only guarantee is that lower values for max_ops means functions will block for a lesser maximum amount of time. The functions psa_sign_interruptible_get_num_ops() and psa_verify_interruptible_get_num_ops() are provided to help with tuning this value.

Note

This value defaults to PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, which means the whole operation will be done in one go, regardless of the number of ops required.

Note

If more ops are needed to complete a computation, PSA_OPERATION_INCOMPLETE will be returned by the function performing the computation. It is then the caller’s responsibility to either call again with the same operation context until it returns 0 or an error code; or to call the relevant abort function if the answer is no longer required.

Note

The interpretation of max_ops is also implementation defined. On a hard real time system, this can indicate a hard deadline, as a real-time system needs a guarantee of not spending more than X time, however care must be taken in such an implementation to avoid the situation whereby calls just return, not being able to do any actual work within the allotted time. On a non-real-time system, the implementation can be more relaxed, but again whether this number should be interpreted as as hard or soft limit or even whether a less than or equals as regards to ops executed in a single call is implementation defined.

Note

For keys in local storage when no accelerator driver applies, please see also the documentation for mbedtls_ecp_set_max_ops(), which is the internal implementation in these cases.

Note

This only applies to functions whose documentation mentions they may return PSA_OPERATION_INCOMPLETE.

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Warning

With implementations that interpret this number as a hard limit, setting this number too small may result in an infinite loop, whereby each call results in immediate return with no ops done (as there is not enough time to execute any), and thus no result will ever be achieved.

Parameters: max_ops – The maximum number of ops to be executed in a single call. This can be a number from 0 to PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, where 0 is the least amount of work done per call.

uint32_t psa_interruptible_get_max_ops(void)

Get the maximum number of ops allowed to be executed by an interruptible function in a single call. This will return the last value set by psa_interruptible_set_max_ops() or PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED if that function has never been called.

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Returns: Maximum number of ops allowed to be executed by an interruptible function in a single call.

uint32_t psa_sign_hash_get_num_ops(const psa_sign_hash_interruptible_operation_t *operation)

Get the number of ops that a hash signing operation has taken so far. If the operation has completed, then this will represent the number of ops required for the entire operation. After initialization or calling psa_sign_hash_interruptible_abort() on the operation, a value of 0 will be returned.

This is a helper provided to help you tune the value passed to psa_interruptible_set_max_ops().

Note

This interface is guaranteed re-entrant and thus may be called from driver code.

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters: operation – The psa_sign_hash_interruptible_operation_t to use. This must be initialized first.
Returns: Number of ops that the operation has taken so far.

uint32_t psa_verify_hash_get_num_ops(const psa_verify_hash_interruptible_operation_t *operation)

Get the number of ops that a hash verification operation has taken so far. If the operation has completed, then this will represent the number of ops required for the entire operation. After initialization or calling psa_verify_hash_interruptible_abort() on the operation, a value of 0 will be returned.

This is a helper provided to help you tune the value passed to psa_interruptible_set_max_ops().

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters: operation – The psa_verify_hash_interruptible_operation_t to use. This must be initialized first.
Returns: Number of ops that the operation has taken so far.

psa_status_t psa_sign_hash_start(psa_sign_hash_interruptible_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length)

Start signing a hash or short message with a private key, in an interruptible manner.

See also

psa_sign_hash_complete()

Note

This function combined with psa_sign_hash_complete() is equivalent to psa_sign_hash() but psa_sign_hash_complete() can return early and resume according to the limit set with psa_interruptible_set_max_ops() to reduce the maximum time spent in a function call.

Note

Users should call psa_sign_hash_complete() repeatedly on the same context after a successful call to this function until psa_sign_hash_complete() either returns 0 or an error. psa_sign_hash_complete() will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_sign_hash_abort() at any point if they no longer want the result.

Note

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_sign_hash_abort().

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters

operation – [inout] The psa_sign_hash_interruptible_operation_t to use. This must be initialized first.
key – Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_HASH.
alg – A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(alg) is true), that is compatible with the type of key.
hash – [in] The hash or message to sign.
hash_length – Size of the hash buffer in bytes.

Return values

PSA_SUCCESS – The operation started successfully - call psa_sign_hash_complete() with the same context to complete the operation
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_NOT_PERMITTED – The key does not have the PSA_KEY_USAGE_SIGN_HASH flag, or it does not permit the requested algorithm.
PSA_ERROR_BAD_STATE – An operation has previously been started on this context, and is still in progress.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_sign_hash_complete(psa_sign_hash_interruptible_operation_t *operation, uint8_t *signature, size_t signature_size, size_t *signature_length)

Continue and eventually complete the action of signing a hash or short message with a private key, in an interruptible manner.

See also

psa_sign_hash_start()

Note

This function combined with psa_sign_hash_start() is equivalent to psa_sign_hash() but this function can return early and resume according to the limit set with psa_interruptible_set_max_ops() to reduce the maximum time spent in a function call.

Note

Users should call this function on the same operation object repeatedly until it either returns 0 or an error. This function will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_sign_hash_abort() at any point if they no longer want the result.

Note

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_sign_hash_abort().

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters

operation – [inout] The psa_sign_hash_interruptible_operation_t to use. This must be initialized first, and have had psa_sign_hash_start() called with it first.
signature – [out] Buffer where the signature is to be written.
signature_size – Size of the signature buffer in bytes. This must be appropriate for the selected algorithm and key:
- The required signature size is PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
- PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.
signature_length – [out] On success, the number of bytes that make up the returned signature value.

Return values

PSA_SUCCESS – Operation completed successfully
PSA_OPERATION_INCOMPLETE – Operation was interrupted due to the setting of psa_interruptible_set_max_ops(). There is still work to be done. Call this function again with the same operation object.
PSA_ERROR_BUFFER_TOO_SMALL – The size of the signature buffer is too small. You can determine a sufficient buffer size by calling PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of key.
PSA_ERROR_BAD_STATE – An operation was not previously started on this context via psa_sign_hash_start().
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_BAD_STATE – The library has either not been previously initialized by psa_crypto_init() or you did not previously call psa_sign_hash_start() with this operation object. It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_sign_hash_abort(psa_sign_hash_interruptible_operation_t *operation)

Abort a sign hash operation.

Note

This function is the only function that clears the number of ops completed as part of the operation. Please ensure you copy this value via psa_sign_hash_get_num_ops() if required before calling.

Note

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_sign_hash_start() again.

Note

You may call this function any time after the operation object has been initialized. In particular, calling psa_sign_hash_abort() after the operation has already been terminated by a call to psa_sign_hash_abort() or psa_sign_hash_complete() is safe.

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters

operation – [inout] Initialized sign hash operation.

Return values

PSA_SUCCESS – The operation was aborted successfully.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_verify_hash_start(psa_verify_hash_interruptible_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)

Start reading and verifying a hash or short message, in an interruptible manner.

See also

psa_verify_hash_complete()

Note

This function combined with psa_verify_hash_complete() is equivalent to psa_verify_hash() but psa_verify_hash_complete() can return early and resume according to the limit set with psa_interruptible_set_max_ops() to reduce the maximum time spent in a function.

Note

Users should call psa_verify_hash_complete() repeatedly on the same operation object after a successful call to this function until psa_verify_hash_complete() either returns 0 or an error. psa_verify_hash_complete() will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_verify_hash_abort() at any point if they no longer want the result.

Note

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_verify_hash_abort().

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters

operation – [inout] The psa_verify_hash_interruptible_operation_t to use. This must be initialized first.
key – Identifier of the key to use for the operation. The key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
alg – A signature algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(alg) is true), that is compatible with the type of key.
hash – [in] The hash whose signature is to be verified.
hash_length – Size of the hash buffer in bytes.
signature – [in] Buffer containing the signature to verify.
signature_length – Size of the signature buffer in bytes.

Return values

PSA_SUCCESS – The operation started successfully - please call psa_verify_hash_complete() with the same context to complete the operation.
PSA_ERROR_BAD_STATE – Another operation has already been started on this context, and is still in progress.
PSA_ERROR_NOT_PERMITTED – The key does not have the PSA_KEY_USAGE_VERIFY_HASH flag, or it does not permit the requested algorithm.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_verify_hash_complete(psa_verify_hash_interruptible_operation_t *operation)

Continue and eventually complete the action of reading and verifying a hash or short message signed with a private key, in an interruptible manner.

See also

psa_verify_hash_start()

Note

This function combined with psa_verify_hash_start() is equivalent to psa_verify_hash() but this function can return early and resume according to the limit set with psa_interruptible_set_max_ops() to reduce the maximum time spent in a function call.

Note

Users should call this function on the same operation object repeatedly until it either returns 0 or an error. This function will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_verify_hash_abort() at any point if they no longer want the result.

Note

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_verify_hash_abort().

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters

operation – [inout] The psa_verify_hash_interruptible_operation_t to use. This must be initialized first, and have had psa_verify_hash_start() called with it first.

Return values

PSA_SUCCESS – Operation completed successfully, and the passed signature is valid.
PSA_OPERATION_INCOMPLETE – Operation was interrupted due to the setting of psa_interruptible_set_max_ops(). There is still work to be done. Call this function again with the same operation object.
PSA_ERROR_INVALID_HANDLE –
PSA_ERROR_INVALID_SIGNATURE – The calculation was performed successfully, but the passed signature is not a valid signature.
PSA_ERROR_BAD_STATE – An operation was not previously started on this context via psa_verify_hash_start().
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_INVALID_ARGUMENT –
PSA_ERROR_INSUFFICIENT_MEMORY –
PSA_ERROR_COMMUNICATION_FAILURE –
PSA_ERROR_HARDWARE_FAILURE –
PSA_ERROR_CORRUPTION_DETECTED –
PSA_ERROR_STORAGE_FAILURE –
PSA_ERROR_DATA_CORRUPT –
PSA_ERROR_DATA_INVALID –
PSA_ERROR_INSUFFICIENT_ENTROPY –
PSA_ERROR_BAD_STATE – The library has either not been previously initialized by psa_crypto_init() or you did not previously call psa_verify_hash_start() on this object. It is implementation-dependent whether a failure to initialize results in this error code.

psa_status_t psa_verify_hash_abort(psa_verify_hash_interruptible_operation_t *operation)

Abort a verify hash operation.

Note

This function is the only function that clears the number of ops completed as part of the operation. Please ensure you copy this value via psa_verify_hash_get_num_ops() if required before calling.

Note

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_verify_hash_start() again.

Note

You may call this function any time after the operation object has been initialized. In particular, calling psa_verify_hash_abort() after the operation has already been terminated by a call to psa_verify_hash_abort() or psa_verify_hash_complete() is safe.

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

Parameters

operation – [inout] Initialized verify hash operation.

Return values

PSA_SUCCESS – The operation was aborted successfully.
PSA_ERROR_NOT_SUPPORTED –
PSA_ERROR_BAD_STATE – The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.