|
|
Parameters
key
Identifier of the key to export. It must permit the usage
PSA_KEY_USAGE_EXPORT, unless it is a public key.
data
Buffer where the key data is to be written.
data_size
Size of the data buffer in bytes. This must be appropriate for the key:
∙ The required output size is PSA_EXPORT_KEY_OUTPUT_SIZE(type,
bits) where type is the key type and bits is the key size in bits.
∙ PSA_EXPORT_KEY_PAIR_MAX_SIZE evaluates to the maximum output
size of any supported key pair.
∙ PSA_EXPORT_PUBLIC_KEY_MAX_SIZE evaluates to the maximum
output size of any supported public key.
∙ This API defines no maximum size for symmetric keys.
Arbitrarily large data items can be stored in the key store, for
example certificates that correspond to a stored private key or
input material for key derivation.
data_length
On success, the number of bytes that make up the key data.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*data_length) bytes of data contain the exported
key.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_EXPORT flag.
PSA_ERROR_BUFFER_TOO_SMALL
The size of the data buffer is too small. PSA_EXPORT_KEY_OUTPUT_SIZE()
or PSA_EXPORT_KEY_PAIR_MAX_SIZE can be used to determine a
sufficient buffer size.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ The key’s storage location does not support export of the key.
∙ The implementation does not support export of keys with this
key type.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 99
1.1.2
Non-confidential
Description
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 in Key formats on page 103, not the
originally imported representation.
For standard key types, the output format is defined in Key formats on page 103.
The policy on the key must have the usage flag PSA_KEY_USAGE_EXPORT set.
psa_export_public_key (function)
Export a public key or the public part of a key pair in binary format.
psa_status_t psa_export_public_key(psa_key_id_t key,
uint8_t * data,
size_t data_size,
size_t * data_length);
Parameters
key
Identifier of the key to export.
data
Buffer where the key data is to be written.
data_size
Size of the data buffer in bytes. This must be appropriate for the key:
∙ The required output size is
PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(type, bits) where type is
the key type and bits is the key size in bits.
∙ PSA_EXPORT_PUBLIC_KEY_MAX_SIZE evaluates to the maximum
output size of any supported public key or public part of a key
pair.
data_length
On success, the number of bytes that make up the key data.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*data_length) bytes of data contain the exported
public key.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_BUFFER_TOO_SMALL
The size of the data buffer is too small.
PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE() or
PSA_EXPORT_PUBLIC_KEY_MAX_SIZE can be used to determine a sufficient
buffer size.
PSA_ERROR_INVALID_ARGUMENT
The key is neither a public key nor a key pair.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ The key’s storage location does not support export of the key.
∙ The implementation does not support export of keys with this
key type.
IHI 0086
Page 100
1.1.2
Non-confidential
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The output of this function can be passed to psa_import_key() to create an object that is equivalent to the
public key.
If the implementation of psa_import_key() supports other formats beyond the format specified here, the
output from psa_export_public_key() must use the representation specified in Key formats on page 103,
not the originally imported representation.
For standard key types, the output format is defined in Key formats on page 103.
Exporting a public key object or the public part of a key pair is always permitted, regardless of the key’s
usage flags.
PSA_EXPORT_KEY_OUTPUT_SIZE (macro)
Sufficient output buffer size for psa_export_key().
#define PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits) \
/* implementation-defined value */
Parameters
key_type
A supported key type.
key_bits
The size of the key in bits.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that
psa_export_key() or psa_export_public_key() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the
parameters are a valid combination that is not supported by the implementation, this macro must return
either a sensible size or 0. If the parameters are not valid, the return value is unspecified.
Description
The following code illustrates how to allocate enough memory to export a key by querying the key type
and size at runtime.
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_status_t status;
status = psa_get_key_attributes(key, &attributes);
if (status != PSA_SUCCESS)
handle_error(...);
psa_key_type_t key_type = psa_get_key_type(&attributes);
(continues on next page)
IHI 0086
Page 101
1.1.2
Non-confidential
(continued from previous page)
size_t key_bits = psa_get_key_bits(&attributes);
size_t buffer_size = PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits);
psa_reset_key_attributes(&attributes);
uint8_t *buffer = malloc(buffer_size);
if (buffer == NULL)
handle_error(...);
size_t buffer_length;
status = psa_export_key(key, buffer, buffer_size, &buffer_length);
if (status != PSA_SUCCESS)
handle_error(...);
See also PSA_EXPORT_KEY_PAIR_MAX_SIZE and PSA_EXPORT_PUBLIC_KEY_MAX_SIZE.
PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE (macro)
Sufficient output buffer size for psa_export_public_key().
#define PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits) \
/* implementation-defined value */
Parameters
key_type
A public key or key pair key type.
key_bits
The size of the key in bits.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that
psa_export_public_key() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid
combination that is not supported by the implementation, this macro must return either a sensible size or
0. If the parameters are not valid, the return value is unspecified.
If the parameters are valid and supported, it is recommended that this macro returns the same result as
PSA_EXPORT_KEY_OUTPUT_SIZE(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type), key_bits).
Description
The following code illustrates how to allocate enough memory to export a public key by querying the key
type and size at runtime.
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_status_t status;
status = psa_get_key_attributes(key, &attributes);
if (status != PSA_SUCCESS)
handle_error(...);
psa_key_type_t key_type = psa_get_key_type(&attributes);
size_t key_bits = psa_get_key_bits(&attributes);
size_t buffer_size = PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits);
psa_reset_key_attributes(&attributes);
uint8_t *buffer = malloc(buffer_size);
(continues on next page)
IHI 0086
Page 102
1.1.2
Non-confidential
(continued from previous page)
if (buffer == NULL)
handle_error(...);
size_t buffer_length;
status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
if (status != PSA_SUCCESS)
handle_error(...);
See also PSA_EXPORT_PUBLIC_KEY_MAX_SIZE.
PSA_EXPORT_KEY_PAIR_MAX_SIZE (macro)
Sufficient buffer size for exporting any asymmetric key pair.
#define PSA_EXPORT_KEY_PAIR_MAX_SIZE /* implementation-defined value */
This value must be a sufficient buffer size when calling psa_export_key() to export any asymmetric key pair
that is supported by the implementation, regardless of the exact key type and key size.
See also PSA_EXPORT_KEY_OUTPUT_SIZE().
PSA_EXPORT_PUBLIC_KEY_MAX_SIZE (macro)
Sufficient buffer size for exporting any asymmetric public key.
#define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE /* implementation-defined value */
This value must be a sufficient buffer size when calling psa_export_key() or psa_export_public_key() to
export any asymmetric public key that is supported by the implementation, regardless of the exact key
type and key size.
See also PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE().
9.6.4 Key formats
This section defines the format of the key data that an implementation is required to support when
importing and exporting keys. Keys can be imported using psa_import_key(), and exported using
psa_export_key() or psa_export_public_key().
Table 8 Standard key formats
Key type
Key type details and format
DES
PSA_KEY_TYPE_DES, 64 bits.
The key data consists of 8 bytes. The parity bits must be correct.
2-key 3DES
PSA_KEY_TYPE_DES, 128 bits.
3-key 3DES
PSA_KEY_TYPE_DES, 192 bits.
The key data is the concatenation of the two or three DES keys.
continues on next page
IHI 0086
Page 103
1.1.2
Non-confidential
Table 8 - continued from previous page
Key type
Key type details and format
HMAC
PSA_KEY_TYPE_HMAC(hash_alg)
For HMAC keys that are shorter than, or equal in size to, the block size of
hash_alg, the format is the raw bytes of the key.
HMAC keys that are longer than the block size of hash_alg, are permitted
in a call to psa_import_key(). For such a key, the output of
psa_export_key() is an IMPLEMENTATION DEFINED choice between the
following:
1. The raw bytes of the key.
2. The raw bytes of the hash of the key, using hash_alg.
Other symmetric keys
PSA_KEY_TYPE_AES
∙ AES
PSA_KEY_TYPE_ARC4
∙ ARC4
PSA_KEY_TYPE_ARIA
∙ ARIA
PSA_KEY_TYPE_CAMELLIA
∙ CAMELLIA
PSA_KEY_TYPE_CHACHA20
∙ ChaCha20
PSA_KEY_TYPE_SM4
∙ SM4
PSA_KEY_TYPE_DERIVE
∙ Secrets for derivation
PSA_KEY_TYPE_PASSWORD_HASH
∙ Password hashes
The key data is the raw bytes of the key.
continues on next page
IHI 0086
Page 104
1.1.2
Non-confidential
Table 8 - continued from previous page
Key type
Key type details and format
RSA key pair
PSA_KEY_TYPE_RSA_KEY_PAIR
The key data is the non-encrypted DER encoding of the representation
defined by in PKCS #1: RSA Cryptography Specifications Version 2.2
[RFC8017] 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
}
Note:
Although it is possible to define an RSA key pair or private key
using a subset of these elements, the output from psa_export_key()
for an RSA key pair must include all of these elements.
RSA public key
PSA_KEY_TYPE_RSA_PUBLIC_KEY
The key data is the DER encoding of the representation defined by
Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure
Certificate and Certificate Revocation List (CRL) Profile [RFC3279] §2.3.1 as
RSAPublicKey.
RSAPublicKey ::= SEQUENCE {
modulus
INTEGER,
-- n
publicExponent
INTEGER
}
-- e
Weierstrass Elliptic curve
PSA_KEY_TYPE_ECC_KEY_PAIR(ecc_family), where ecc_family designates a
key pair
Weierstrass curve family.
The key data is the content of the privateKey field of the ECPrivateKey
format defined by Elliptic Curve Private Key Structure [RFC5915].
This is a ceiling(m/8)-byte string in big-endian order where m is the key
size in bits.
continues on next page
IHI 0086
Page 105
1.1.2
Non-confidential
Table 8 - continued from previous page
Key type
Key type details and format
Weierstrass Elliptic curve
PSA_KEY_TYPE_ECC_PUBLIC_KEY(ecc_family), where ecc_family designates a
public key
Weierstrass curve family.
The key data is the uncompressed representation of an elliptic curve
point as an octet string defined in SEC 1: Elliptic Curve Cryptography
[SEC1] §2.3.3. If m is the bit size associated with the curve, i.e. the bit size
of q for a curve over F_q, then 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.
Montgomery Elliptic curve
PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_MONTGOMERY)
key pair
The key data is the scalar value of the ‘private key’ in little-endian order
as defined by Elliptic Curves for Security [RFC7748] §6. The value must
have the forced bits set to zero or one as specified by
decodeScalar25519() and decodeScalar448() in [RFC7748] §5.
This is a ceiling(m/8)-byte string where m is the key size in bits. This is 32
bytes for Curve25519, and 56 bytes for Curve448.
Montgomery Elliptic curve
PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_MONTGOMERY)
public key
The key data is the scalar value of the ‘public key’ in little-endian order as
defined by Elliptic Curves for Security [RFC7748] §6. This is a
ceiling(m/8)-byte string where m is the key size in bits.
∙ This is 32 bytes for Curve25519, computed as X25519(private_key,
9).
∙ This is 56 bytes for Curve448, computed as X448(private_key, 5).
Twisted Edwards Elliptic
PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)
curve key pair
The key data is the private key, as defined by Edwards-Curve Digital
Signature Algorithm (EdDSA) [RFC8032].
This is a 32-byte string for Edwards25519, and a 57-byte string for
Edwards448.
Twisted Edwards Elliptic
PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS)
curve public key
The key data is the public key, as defined by Edwards-Curve Digital
Signature Algorithm (EdDSA) [RFC8032].
This is a 32-byte string for Edwards25519, and a 57-byte string for
Edwards448.
continues on next page
IHI 0086
Page 106
1.1.2
Non-confidential
Table 8 - continued from previous page
Key type
Key type details and format
Finite-field Diffie-Hellman
PSA_KEY_TYPE_DH_KEY_PAIR(dh_family) where dh_family designates any
key pair
Diffie-Hellman family.
The key data 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,
and leading zeroes are not stripped.
Finite-field Diffie-Hellman
PSA_KEY_TYPE_DH_PUBLIC_KEY(dh_family) where dh_family designates any
public key
Diffie-Hellman family.
The key data 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.
10 Cryptographic operation reference
10.1 Algorithms
This specification encodes algorithms into a structured 32-bit integer value.
Algorithm identifiers are used for two purposes in the Crypto API:
1. To specify a specific algorithm to use in a cryptographic operation. These are all defined in
Cryptographic operation reference.
2. To specify the policy for a key, identifying the permitted algorithm for use with the key. This use is
described in Key policies on page 83.
The specific algorithm identifiers are described alongside the cryptographic operation functions to which
they apply:
∙ Hash algorithms on page 113
∙ MAC algorithms on page 134
∙ Cipher algorithms on page 150
∙ AEAD algorithms on page 176
∙ Key derivation algorithms on page 206
∙ Asymmetric signature algorithms on page 235
∙ Asymmetric encryption algorithms on page 256
∙ Key agreement algorithms on page 263
IHI 0086
Page 107
1.1.2
Non-confidential
10.1.1 Algorithm encoding
psa_algorithm_t (typedef)
Encoding of a cryptographic algorithm.
typedef uint32_t psa_algorithm_t;
This is a structured bitfield that identifies the category and type of algorithm. The range of algorithm
identifier values is divided as follows:
0x00000000 Reserved as an invalid algorithm identifier.
0x00000001 - 0x7fffffff
Specification-defined algorithm identifiers. Algorithm identifiers defined by this standard
always have bit 31 clear. Unallocated algorithm identifier values in this range are reserved
for future use.
0x80000000 - 0xffffffff
Implementation-defined algorithm identifiers. Implementations that define additional
algorithms must use an encoding with bit 31 set. The related support macros will be easier
to write if these algorithm identifier encodings also respect the bitwise structure used by
standard encodings.
For algorithms that can be applied to multiple key types, this identifier does not encode the key type. For
example, for symmetric ciphers based on a block cipher, psa_algorithm_t encodes the block cipher mode
and the padding mode while the block cipher itself is encoded via psa_key_type_t.
The Algorithm and key type encoding on page 287 appendix provides a full definition of the algorithm
identifier encoding.
PSA_ALG_NONE (macro)
An invalid algorithm identifier value.
#define PSA_ALG_NONE ((psa_algorithm_t)0)
Zero is not the encoding of any algorithm.
10.1.2 Algorithm categories
PSA_ALG_IS_HASH (macro)
Whether the specified algorithm is a hash algorithm.
#define PSA_ALG_IS_HASH(alg) /* specification-defined value */
IHI 0086
Page 108
1.1.2
Non-confidential
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a hash algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported
algorithm identifier.
Description
See Hash algorithms on page 113 for a list of defined hash algorithms.
PSA_ALG_IS_MAC (macro)
Whether the specified algorithm is a MAC algorithm.
#define PSA_ALG_IS_MAC(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a MAC algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported
algorithm identifier.
Description
See MAC algorithms on page 134 for a list of defined MAC algorithms.
PSA_ALG_IS_CIPHER (macro)
Whether the specified algorithm is a symmetric cipher algorithm.
#define PSA_ALG_IS_CIPHER(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a symmetric cipher algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a
supported algorithm identifier.
Description
See Cipher algorithms on page 150 for a list of defined cipher algorithms.
IHI 0086
Page 109
1.1.2
Non-confidential
PSA_ALG_IS_AEAD (macro)
Whether the specified algorithm is an authenticated encryption with associated data (AEAD) algorithm.
#define PSA_ALG_IS_AEAD(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is an AEAD algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported
algorithm identifier.
Description
See AEAD algorithms on page 176 for a list of defined AEAD algorithms.
PSA_ALG_IS_SIGN (macro)
Whether the specified algorithm is an asymmetric signature algorithm, also known as public-key signature
algorithm.
#define PSA_ALG_IS_SIGN(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is an asymmetric signature algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a
supported algorithm identifier.
Description
See Asymmetric signature algorithms on page 235 for a list of defined signature algorithms.
PSA_ALG_IS_ASYMMETRIC_ENCRYPTION (macro)
Whether the specified algorithm is an asymmetric encryption algorithm, also known as public-key
encryption algorithm.
#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
IHI 0086
Page 110
1.1.2
Non-confidential
Returns
1 if alg is an asymmetric encryption algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not
a supported algorithm identifier.
Description
See Asymmetric encryption algorithms on page 256 for a list of defined asymmetric encryption algorithms.
PSA_ALG_IS_KEY_AGREEMENT (macro)
Whether the specified algorithm is a key agreement algorithm.
#define PSA_ALG_IS_KEY_AGREEMENT(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a key agreement algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a
supported algorithm identifier.
Description
See Key agreement algorithms on page 263 for a list of defined key agreement algorithms.
PSA_ALG_IS_KEY_DERIVATION (macro)
Whether the specified algorithm is a key derivation algorithm.
#define PSA_ALG_IS_KEY_DERIVATION(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a key derivation algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a
supported algorithm identifier.
Description
See Key derivation algorithms on page 206 for a list of defined key derivation algorithms.
PSA_ALG_IS_WILDCARD (macro)
Whether the specified algorithm encoding is a wildcard.
#define PSA_ALG_IS_WILDCARD(alg) /* specification-defined value */
IHI 0086
Page 111
1.1.2
Non-confidential
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a wildcard algorithm encoding.
0 if alg is a non-wildcard algorithm encoding that is suitable for an operation.
This macro can return either 0 or 1 if alg is not a supported algorithm identifier.
Description
Wildcard algorithm values can only be used to set the permitted-algorithm field in a key policy, wildcard
values cannot be used to perform an operation.
See PSA_ALG_ANY_HASH for example of how a wildcard algorithm can be used in a key policy.
PSA_ALG_GET_HASH (macro)
Get the hash used by a composite algorithm.
#define PSA_ALG_GET_HASH(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
The underlying hash algorithm if alg is a composite algorithm that uses a hash algorithm.
PSA_ALG_NONE if alg is not a composite algorithm that uses a hash.
Description
The following composite algorithms require a hash algorithm:
∙ PSA_ALG_ECDSA()
∙ PSA_ALG_HKDF()
∙ PSA_ALG_HKDF_EXPAND()
∙ PSA_ALG_HKDF_EXTRACT()
∙ PSA_ALG_HMAC()
∙ PSA_ALG_RSA_OAEP()
∙ PSA_ALG_RSA_PKCS1V15_SIGN()
∙ PSA_ALG_RSA_PSS()
∙ PSA_ALG_RSA_PSS_ANY_SALT()
∙ PSA_ALG_TLS12_PRF()
∙ PSA_ALG_TLS12_PSK_TO_MS()
∙ PSA_ALG_PBKDF2_HMAC()
IHI 0086
Page 112
1.1.2
Non-confidential
10.2 Message digests (Hashes)
The single-part hash functions are:
∙ psa_hash_compute() to calculate the hash of a message.
∙ psa_hash_compare() to compare the hash of a message with a reference value.
The psa_hash_operation_t multi-part operation allows messages to be processed in fragments. A multi-part
hash operation is used as follows:
1. Initialize the psa_hash_operation_t object to zero, or by assigning the value of the associated macro
PSA_HASH_OPERATION_INIT.
2. Call psa_hash_setup() to specify the required hash algorithm, call psa_hash_clone() to duplicate the
state of active psa_hash_operation_t object, or call psa_hash_resume() to restart a hash operation with
the output from a previously suspended hash operation.
3. Call the psa_hash_update() function on successive chunks of the message.
4. At the end of the message, call the required finishing function:
∙ To suspend the hash operation and extract a hash suspend state, call psa_hash_suspend(). The
output state can subsequently be used to resume the hash operation.
∙ To calculate the digest of a message, call psa_hash_finish().
∙ To verify the digest of a message against a reference value, call psa_hash_verify().
To abort the operation or recover from an error, call psa_hash_abort().
10.2.1 Hash algorithms
PSA_ALG_MD2 (macro)
The MD2 message-digest algorithm.
#define PSA_ALG_MD2 ((psa_algorithm_t)0x02000001)
Warning: The MD2 hash is weak and deprecated and is only recommended for use in legacy
applications.
MD2 is defined in The MD2 Message-Digest Algorithm [RFC1319].
PSA_ALG_MD4 (macro)
The MD4 message-digest algorithm.
#define PSA_ALG_MD4 ((psa_algorithm_t)0x02000002)
Warning: The MD4 hash is weak and deprecated and is only recommended for use in legacy
applications.
IHI 0086
Page 113
1.1.2
Non-confidential
MD4 is defined in The MD4 Message-Digest Algorithm [RFC1320].
PSA_ALG_MD5 (macro)
The MD5 message-digest algorithm.
#define PSA_ALG_MD5 ((psa_algorithm_t)0x02000003)
Warning: The MD5 hash is weak and deprecated and is only recommended for use in legacy
applications.
MD5 is defined in The MD5 Message-Digest Algorithm [RFC1321].
PSA_ALG_RIPEMD160 (macro)
The RIPEMD-160 message-digest algorithm.
#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x02000004)
RIPEMD-160 is defined in RIPEMD-160: A Strengthened Version of RIPEMD [RIPEMD], and also in ISO/IEC
10118-3:2018 IT Security techniques - Hash-functions - Part 3: Dedicated hash-functions [ISO10118].
PSA_ALG_SHA_1 (macro)
The SHA-1 message-digest algorithm.
#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x02000005)
Warning: The SHA-1 hash is weak and deprecated and is only recommended for use in legacy
applications.
SHA-1 is defined in FIPS Publication 180-4: Secure Hash Standard (SHS) [FIPS180-4].
PSA_ALG_SHA_224 (macro)
The SHA-224 message-digest algorithm.
#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x02000008)
SHA-224 is defined in [FIPS180-4].
IHI 0086
Page 114
1.1.2
Non-confidential
PSA_ALG_SHA_256 (macro)
The SHA-256 message-digest algorithm.
#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x02000009)
SHA-256 is defined in [FIPS180-4].
PSA_ALG_SHA_384 (macro)
The SHA-384 message-digest algorithm.
#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0200000a)
SHA-384 is defined in [FIPS180-4].
PSA_ALG_SHA_512 (macro)
The SHA-512 message-digest algorithm.
#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0200000b)
SHA-512 is defined in [FIPS180-4].
PSA_ALG_SHA_512_224 (macro)
The SHA-512/224 message-digest algorithm.
#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0200000c)
SHA-512/224 is defined in [FIPS180-4].
PSA_ALG_SHA_512_256 (macro)
The SHA-512/256 message-digest algorithm.
#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0200000d)
SHA-512/256 is defined in [FIPS180-4].
PSA_ALG_SHA3_224 (macro)
The SHA3-224 message-digest algorithm.
#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x02000010)
SHA3-224 is defined in FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and
Extendable-Output Functions [FIPS202].
IHI 0086
Page 115
1.1.2
Non-confidential
PSA_ALG_SHA3_256 (macro)
The SHA3-256 message-digest algorithm.
#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x02000011)
SHA3-256 is defined in [FIPS202].
PSA_ALG_SHA3_384 (macro)
The SHA3-384 message-digest algorithm.
#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012)
SHA3-384 is defined in [FIPS202].
PSA_ALG_SHA3_512 (macro)
The SHA3-512 message-digest algorithm.
#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013)
SHA3-512 is defined in [FIPS202].
PSA_ALG_SHAKE256_512 (macro)
The first 512 bits (64 bytes) of the SHAKE256 output.
#define PSA_ALG_SHAKE256_512 ((psa_algorithm_t)0x02000015)
This is the prehashing for Ed448ph (see PSA_ALG_ED448PH).
SHAKE256 is defined in [FIPS202].
Note:
For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-512 is
recommended. SHA3-512 has the same output size, and a theoretically higher security strength.
PSA_ALG_SM3 (macro)
The SM3 message-digest algorithm.
#define PSA_ALG_SM3 ((psa_algorithm_t)0x02000014)
SM3 is defined in ISO/IEC 10118-3:2018 IT Security techniques - Hash-functions - Part 3: Dedicated
hash-functions [ISO10118], and also in GM/T 0004-2012: SM3 cryptographic hash algorithm [CSTC0004].
IHI 0086
Page 116
1.1.2
Non-confidential
10.2.2 Single-part hashing functions
psa_hash_compute (function)
Calculate the hash (digest) of a message.
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);
Parameters
alg
The hash algorithm to compute: a value of type psa_algorithm_t such
that PSA_ALG_IS_HASH(alg) is true.
input
Buffer containing the message to hash.
input_length
Size of the input buffer in bytes.
hash
Buffer where the hash is to be written.
hash_size
Size of the hash buffer in bytes. This must be at least
PSA_HASH_LENGTH(alg).
hash_length
On success, the number of bytes that make up the hash value. This is
always PSA_HASH_LENGTH(alg).
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*hash_length) bytes of hash contain the hash value.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the hash buffer is too small. PSA_HASH_LENGTH() can be used
to determine a sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a hash algorithm.
∙ input_length is too large for alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a hash algorithm.
∙ input_length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
IHI 0086
Page 117
1.1.2
Non-confidential
Description
Note:
To verify the hash of a message against an expected value, use psa_hash_compare() instead.
psa_hash_compare (function)
Calculate the hash (digest) of a message and compare it with a reference value.
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);
Parameters
alg
The hash algorithm to compute: a value of type psa_algorithm_t such
that PSA_ALG_IS_HASH(alg) is true.
input
Buffer containing the message to hash.
input_length
Size of the input buffer in bytes.
hash
Buffer containing the expected hash value.
hash_length
Size of the hash buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success. The expected hash is identical to the actual hash of the
input.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_SIGNATURE
The calculated hash of the message does not match the value in hash.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a hash algorithm.
∙ input_length is too large for alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a hash algorithm.
∙ input_length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
IHI 0086
Page 118
1.1.2
Non-confidential
10.2.3 Multi-part hashing operations
psa_hash_operation_t (typedef)
The type of the state object for multi-part hash operations.
typedef /* implementation-defined type */ psa_hash_operation_t;
Before calling any function on a hash operation object, the application must initialize it by any of the
following means:
∙ Set the object to all-bits-zero, for example:
psa_hash_operation_t operation;
memset(&operation, 0, sizeof(operation));
∙ Initialize the object to logical zero values by declaring the object as static or global without an
explicit initializer, for example:
static psa_hash_operation_t operation;
∙ Initialize the object 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 object, for example:
psa_hash_operation_t operation;
operation = psa_hash_operation_init();
This is an implementation-defined type. Applications that make assumptions about the content of this
object will result in in implementation-specific behavior, and are non-portable.
PSA_HASH_OPERATION_INIT (macro)
This macro returns a suitable initializer for a hash operation object of type psa_hash_operation_t.
#define PSA_HASH_OPERATION_INIT /* implementation-defined value */
psa_hash_operation_init (function)
Return an initial value for a hash operation object.
psa_hash_operation_t psa_hash_operation_init(void);
IHI 0086
Page 119
1.1.2
Non-confidential
Returns: psa_hash_operation_t
psa_hash_setup (function)
Set up a multi-part hash operation.
psa_status_t psa_hash_setup(psa_hash_operation_t * operation,
psa_algorithm_t alg);
Parameters
operation
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: a value of type psa_algorithm_t such
that PSA_ALG_IS_HASH(alg) is true.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation is now active.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
alg is not a hash algorithm.
PSA_ERROR_NOT_SUPPORTED
alg is not supported or is not a hash algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
The sequence of operations to calculate a hash (message digest) is as follows:
1. Allocate a hash operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for
psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
3. Call psa_hash_setup() to specify the algorithm.
4. 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.
5. To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call
psa_hash_verify(). To suspend the hash operation and extract the current state, call
psa_hash_suspend().
After a successful call to psa_hash_setup(), the operation is active, and the application must eventually
terminate the operation. The following events terminate an operation:
∙ A successful call to psa_hash_finish() or psa_hash_verify() or psa_hash_suspend().
∙ A call to psa_hash_abort().
IHI 0086
Page 120
1.1.2
Non-confidential
If psa_hash_setup() returns an error, the operation object is unchanged. If a subsequent function call with
an active operation returns an error, the operation enters an error state.
To abandon an active operation, or reset an operation in an error state, call psa_hash_abort().
See Multi-part operations on page 24.
psa_hash_update (function)
Add a message fragment to a multi-part hash operation.
psa_status_t psa_hash_update(psa_hash_operation_t * operation,
const uint8_t * input,
size_t input_length);
Parameters
operation
Active hash operation.
input
Buffer containing the message fragment to hash.
input_length
Size of the input buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
The total input for the operation is too large for the hash algorithm.
PSA_ERROR_NOT_SUPPORTED
The total input for the operation is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
The application must call psa_hash_setup() or psa_hash_resume() 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().
psa_hash_finish (function)
Finish the calculation of the hash of a message.
psa_status_t psa_hash_finish(psa_hash_operation_t * operation,
uint8_t * hash,
size_t hash_size,
size_t * hash_length);
IHI 0086
Page 121
1.1.2
Non-confidential
Parameters
operation
Active hash operation.
hash
Buffer where the hash is to be written.
hash_size
Size of the hash buffer in bytes. This must be at least
PSA_HASH_LENGTH(alg) where alg is the algorithm that the operation
performs.
hash_length
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 the
operation performs.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*hash_length) bytes of hash contain the hash value.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the hash buffer is too small. PSA_HASH_LENGTH() can be used
to determine a sufficient buffer size.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
The application must call psa_hash_setup() or psa_hash_resume() 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: It is not recommended to use this function when a specific value is expected for the hash.
Call psa_hash_verify() instead with the expected hash value.
Comparing integrity or authenticity data such as hash values with a function such as memcmp() is risky
because the time taken by the comparison might leak information about the hashed data which could
allow an attacker to guess a valid hash and thereby bypass security controls.
IHI 0086
Page 122
1.1.2
Non-confidential
psa_hash_verify (function)
Finish the calculation of the hash of a message and compare it with an expected value.
psa_status_t psa_hash_verify(psa_hash_operation_t * operation,
const uint8_t * hash,
size_t hash_length);
Parameters
operation
Active hash operation.
hash
Buffer containing the expected hash value.
hash_length
Size of the hash buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success. The expected hash is identical to the actual hash of the
message.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_SIGNATURE
The calculated hash of the message does not match the value in hash.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
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 must make the best effort to ensure that the comparison between the actual hash
and the expected hash is performed in constant time.
IHI 0086
Page 123
1.1.2
Non-confidential
psa_hash_abort (function)
Abort a hash operation.
psa_status_t psa_hash_abort(psa_hash_operation_t * operation);
Parameters
operation
Initialized hash operation.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation object can now be discarded or reused.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
Aborting an operation frees all associated resources except for the operation object itself. Once aborted,
the operation object can be reused for another operation by calling psa_hash_setup() again.
This function can be called 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.
psa_hash_suspend (function)
Halt the hash operation and extract the intermediate state of the hash computation.
psa_status_t psa_hash_suspend(psa_hash_operation_t * operation,
uint8_t * hash_state,
size_t hash_state_size,
size_t * hash_state_length);
Parameters
operation
Active hash operation.
hash_state
Buffer where the hash suspend state is to be written.
hash_state_size
Size of the hash_state buffer in bytes. This must be appropriate for
the selected algorithm:
∙ A sufficient output size is PSA_HASH_SUSPEND_OUTPUT_SIZE(alg)
where alg is the algorithm that was used to set up the operation.
∙ PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE evaluates to the maximum
output size of any supported hash algorithm.
hash_state_length
On success, the number of bytes that make up the hash suspend
state.
IHI 0086
Page 124
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*hash_state_length) bytes of hash_state contain
the intermediate hash state.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the hash_state buffer is too small.
PSA_HASH_SUSPEND_OUTPUT_SIZE() or PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE
can be used to determine a sufficient buffer size.
PSA_ERROR_NOT_SUPPORTED
The hash algorithm being computed does not support suspend and
resume.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
The application must call psa_hash_setup() or psa_hash_resume() before calling this function. This function
extracts an intermediate state of the hash computation of the message formed by concatenating the
inputs passed to preceding calls to psa_hash_update().
This function can be used to halt a hash operation, and then resume the hash operation at a later time, or
in another application, by transferring the extracted hash suspend state to a call to psa_hash_resume().
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().
Hash suspend and resume is not defined for the SHA3 family of hash algorithms. Hash suspend state on
page 131 defines the format of the output from psa_hash_suspend().
Warning: Applications must not use any of the hash suspend state as if it was a hash output. Instead,
the suspend state must only be used to resume a hash operation, and psa_hash_finish() or
psa_hash_verify() can then calculate or verify the final hash value.
Usage
The sequence of operations to suspend and resume a hash operation is as follows:
1. Compute the first part of the hash.
a. Allocate an operation object and initialize it as described in the documentation for
psa_hash_operation_t.
b. Call psa_hash_setup() to specify the algorithm.
c. Call psa_hash_update() zero, one or more times, passing a fragment of the message each time.
d. Call psa_hash_suspend() to extract the hash suspend state into a buffer.
2. Pass the hash state buffer to the application which will resume the operation.
3. Compute the rest of the hash.
IHI 0086
Page 125
1.1.2
Non-confidential
a. Allocate an operation object and initialize it as described in the documentation for
psa_hash_operation_t.
b. Call psa_hash_resume() with the extracted hash state.
c. Call psa_hash_update() zero, one or more times, passing a fragment of the message each time.
d. 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() or psa_hash_resume(), the operation will need
to be reset by a call to psa_hash_abort(). The application can call psa_hash_abort() at any time after the
operation has been initialized.
psa_hash_resume (function)
Set up a multi-part hash operation using the hash suspend state from a previously suspended hash
operation.
psa_status_t psa_hash_resume(psa_hash_operation_t * operation,
const uint8_t * hash_state,
size_t hash_state_length);
Parameters
operation
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.
hash_state
A buffer containing the suspended hash state which is to be
resumed. This must be in the format output by psa_hash_suspend(),
which is described in Hash suspend state format on page 131.
hash_state_length
Length of hash_state in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
hash_state does not correspond to a valid hash suspend state. See
Hash suspend state format on page 131 for the definition.
PSA_ERROR_NOT_SUPPORTED
The provided hash suspend state is for an algorithm that is not
supported.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
IHI 0086
Page 126
1.1.2
Non-confidential
Description
See psa_hash_suspend() for an example of how to use this function to suspend and resume a hash
operation.
After a successful call to psa_hash_resume(), the application must eventually terminate the operation. The
following events terminate an operation:
∙ A successful call to psa_hash_finish(), psa_hash_verify() or psa_hash_suspend().
∙ A call to psa_hash_abort().
psa_hash_clone (function)
Clone a hash operation.
psa_status_t psa_hash_clone(const psa_hash_operation_t * source_operation,
psa_hash_operation_t * target_operation);
Parameters
source_operation
The active hash operation to clone.
target_operation
The operation object to set up. It must be initialized but not active.
Returns: psa_status_t
PSA_SUCCESS
Success. target_operation is ready to continue the same hash
operation as source_operation.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The source_operation state is not valid: it must be active.
∙ The target_operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
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.
IHI 0086
Page 127
1.1.2
Non-confidential
10.2.4 Support macros
PSA_HASH_LENGTH (macro)
The size of the output of psa_hash_compute() and psa_hash_finish(), in bytes.
#define PSA_HASH_LENGTH(alg) /* implementation-defined value */
Parameters
alg
A hash algorithm or an HMAC algorithm: a value of type
psa_algorithm_t such that (PSA_ALG_IS_HASH(alg) ||
PSA_ALG_IS_HMAC(alg)) is true.
Returns
The hash length for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An
implementation can return either 0 or the correct size for a hash algorithm that it recognizes, but does not
support.
Description
This is also the hash length that psa_hash_compare() and psa_hash_verify() expect.
See also PSA_HASH_MAX_SIZE.
PSA_HASH_MAX_SIZE (macro)
Maximum size of a hash.
#define PSA_HASH_MAX_SIZE /* implementation-defined value */
It is recommended that this value is the maximum size of a hash supported by the implementation, in
bytes. The value must not be smaller than this maximum.
See also PSA_HASH_LENGTH().
PSA_HASH_SUSPEND_OUTPUT_SIZE (macro)
A sufficient hash suspend state buffer size for psa_hash_suspend(), in bytes.
#define PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) /* specification-defined value */
Parameters
alg
A hash algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_HASH(alg) is true.
IHI 0086
Page 128
1.1.2
Non-confidential
Returns
A sufficient output size for the algorithm. If the hash algorithm is not recognized, or is not supported by
psa_hash_suspend(), return 0. An implementation can return either 0 or a correct size for a hash algorithm
that it recognizes, but does not support.
For a supported hash algorithm alg, the following expression is true:
PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) == PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH +
PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) +
PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) +
PSA_HASH_BLOCK_LENGTH(alg) - 1
Description
If the size of the hash state buffer is at least this large, it is guaranteed that psa_hash_suspend() will not fail
due to an insufficient buffer size. The actual size of the output might be smaller in any given call.
See also PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE.
PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE (macro)
A sufficient hash suspend state buffer size for psa_hash_suspend(), for any supported hash algorithms.
#define PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE /* implementation-defined value */
If the size of the hash state buffer is at least this large, it is guaranteed that psa_hash_suspend() will not fail
due to an insufficient buffer size.
See also PSA_HASH_SUSPEND_OUTPUT_SIZE().
PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH (macro)
The size of the algorithm field that is part of the output of psa_hash_suspend(), in bytes.
#define PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH ((size_t)4)
Applications can use this value to unpack the hash suspend state that is output by psa_hash_suspend().
PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH (macro)
The size of the input-length field that is part of the output of psa_hash_suspend(), in bytes.
#define PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) \
/* specification-defined value */
IHI 0086
Page 129
1.1.2
Non-confidential
Parameters
alg
A hash algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_HASH(alg) is true.
Returns
The size, in bytes, of the input-length field of the hash suspend state for the specified hash algorithm. If the
hash algorithm is not recognized, return 0. An implementation can return either 0 or the correct size for a
hash algorithm that it recognizes, but does not support.
The algorithm-specific values are defined in Hash suspend state field sizes on page 132.
Description
Applications can use this value to unpack the hash suspend state that is output by psa_hash_suspend().
PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH (macro)
The size of the hash-state field that is part of the output of psa_hash_suspend(), in bytes.
#define PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) \
/* specification-defined value */
Parameters
alg
A hash algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_HASH(alg) is true.
Returns
The size, in bytes, of the hash-state field of the hash suspend state for the specified hash algorithm. If the
hash algorithm is not recognized, return 0. An implementation can return either 0 or the correct size for a
hash algorithm that it recognizes, but does not support.
The algorithm-specific values are defined in Hash suspend state field sizes on page 132.
Description
Applications can use this value to unpack the hash suspend state that is output by psa_hash_suspend().
PSA_HASH_BLOCK_LENGTH (macro)
The input block size of a hash algorithm, in bytes.
#define PSA_HASH_BLOCK_LENGTH(alg) /* implementation-defined value */
Parameters
alg
A hash algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_HASH(alg) is true.
IHI 0086
Page 130
1.1.2
Non-confidential
Returns
The block size in bytes for the specified hash algorithm. If the hash algorithm is not recognized, return 0.
An implementation can return either 0 or the correct size for a hash algorithm that it recognizes, but does
not support.
Description
Hash algorithms process their input data in blocks. Hash operations will retain any partial blocks until they
have enough input to fill the block or until the operation is finished.
This affects the output from psa_hash_suspend().
10.2.5 Hash suspend state
The hash suspend state is output by psa_hash_suspend() and input to psa_hash_resume().
Note:
Hash suspend and resume is not defined for the SM3 algorithm and the SHA3 family of hash
algorithms.
Hash suspend state format
The hash suspend state has the following format:
hash-suspend-state = algorithm || input-length || hash-state || unprocessed-input
The fields in the hash suspend state are defined as follows:
algorithm
A big-endian 32-bit unsigned integer.
The Crypto API algorithm identifier value.
The byte length of the algorithm field can be evaluated using
PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH.
input-length
A big-endian unsigned integer
The content of this field is algorithm-specific:
∙ For MD2, this is the number of bytes in the unprocessed-input.
∙ For all other hash algorithms, this is the total number of bytes of input to the hash
computation. This includes the unprocessed-input bytes.
The size of this field is algorithm-specific:
∙ For MD2: input-length is an 8-bit unsigned integer.
∙ For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: input-length is a
64-bit unsigned integer.
∙ For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: input-length is a 128-bit
unsigned integer.
The length, in bytes, of the input-length field can be calculated using
PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) where alg is a hash algorithm. See Hash
suspend state field sizes on page 132.
IHI 0086
Page 131
1.1.2
Non-confidential
hash-state An array of bytes
Algorithm-specific intermediate hash state:
∙ For MD2: 16 bytes of internal checksum, then 48 bytes of intermediate digest.
∙ For MD4 and MD5: 4x 32-bit integers, in little-endian encoding.
∙ For RIPEMD-160: 5x 32-bit integers, in little-endian encoding.
∙ For SHA-1: 5x 32-bit integers, in big-endian encoding.
∙ For SHA-224 and SHA-256: 8x 32-bit integers, in big-endian encoding.
∙ For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: 8x 64-bit integers, in
big-endian encoding.
The length of this field is specific to the algorithm. The length, in bytes, of the hash-state
field can be calculated using PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) where alg is a
hash algorithm. See Hash suspend state field sizes.
unprocessed-input
0 to (hash-block-size-1) bytes
A partial block of unprocessed input data. This is between zero and hash-block-size-1 bytes
of data, the length can be calculated by:
length(unprocessed-input) = input-length % hash-block-size.
The hash-block-size is specific to the algorithm. The size of a hash block can be calculated
using PSA_HASH_BLOCK_LENGTH(alg) where alg is a hash algorithm. See Hash suspend state field
sizes.
Hash suspend state field sizes
The following table defines the algorithm-specific field lengths for the hash suspend state returned by
psa_hash_suspend(). All of the field lengths are in bytes. To compute the field lengths for algorithm alg, use
the following expressions:
∙ PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH returns the length of the algorithm field.
∙ PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) returns the length of the input-length field.
∙ PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) returns the length of the hash-state field.
∙ PSA_HASH_BLOCK_LENGTH(alg)-1 is the maximum length of the unprocessed-bytes field.
∙ PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) returns the maximum size of the hash suspend state.
IHI 0086
Page 132
1.1.2
Non-confidential
Hash algorithm
input-length size (bytes) hash-state length (bytes) unprocessed-bytes length (bytes)
PSA_ALG_MD2
1
64
0 - 15
PSA_ALG_MD4
8
16
0 - 63
PSA_ALG_MD5
8
16
0 - 63
PSA_ALG_RIPEMD160
8
20
0 - 63
PSA_ALG_SHA_1
8
20
0 - 63
PSA_ALG_SHA_224
8
32
0 - 63
PSA_ALG_SHA_256
8
32
0 - 63
PSA_ALG_SHA_512_224
16
64
0 - 127
PSA_ALG_SHA_512_256
16
64
0 - 127
PSA_ALG_SHA_384
16
64
0 - 127
PSA_ALG_SHA_512
16
64
0 - 127
10.3 Message authentication codes (MAC)
The single-part MAC functions are:
∙ psa_mac_compute() to calculate the MAC of a message.
∙ psa_mac_verify() to compare the MAC of a message with a reference value.
The psa_mac_operation_t multi-part operation allows messages to be processed in fragments. A multi-part
MAC operation is used as follows:
1. Initialize the psa_mac_operation_t object to zero, or by assigning the value of the associated macro
PSA_MAC_OPERATION_INIT.
2. Call psa_mac_sign_setup() or psa_mac_verify_setup() to specify the algorithm and key.
3. Call the psa_mac_update() function on successive chunks of the message.
4. At the end of the message, call the required finishing function:
∙ To calculate the MAC of the message, call psa_mac_sign_finish().
∙ To verify the MAC of the message against a reference value, call psa_mac_verify_finish().
To abort the operation or recover from an error, call psa_mac_abort().
IHI 0086
Page 133
1.1.2
Non-confidential
10.3.1 MAC algorithms
PSA_ALG_HMAC (macro)
Macro to build an HMAC message-authentication-code algorithm from an underlying hash algorithm.
#define PSA_ALG_HMAC(hash_alg) /* specification-defined value */
Parameters
hash_alg
A hash algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_HASH(hash_alg) is true.
Returns
The corresponding HMAC algorithm.
Unspecified if hash_alg is not a supported hash algorithm.
Description
For example, PSA_ALG_HMAC(PSA_ALG_SHA_256) is HMAC-SHA-256.
The HMAC construction is defined in HMAC: Keyed-Hashing for Message Authentication [RFC2104].
Compatible key types
PSA_KEY_TYPE_HMAC
PSA_ALG_CBC_MAC (macro)
The CBC-MAC message-authentication-code algorithm, constructed over a block cipher.
#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x03c00100)
Warning: CBC-MAC is insecure in many cases. A more secure mode, such as PSA_ALG_CMAC, is
recommended.
The CBC-MAC algorithm must be used with a key for a block cipher. For example, one of PSA_KEY_TYPE_AES.
CBC-MAC is defined as MAC Algorithm 1 in ISO/IEC 9797-1:2011 Information technology - Security
techniques - Message Authentication Codes (MACs) - Part 1: Mechanisms using a block cipher [ISO9797].
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
IHI 0086
Page 134
1.1.2
Non-confidential
PSA_ALG_CMAC (macro)
The CMAC message-authentication-code algorithm, constructed over a block cipher.
#define PSA_ALG_CMAC ((psa_algorithm_t)0x03c00200)
The CMAC algorithm must be used with a key for a block cipher. For example, when used with a key with
type PSA_KEY_TYPE_AES, the resulting operation is AES-CMAC.
CMAC is defined in NIST Special Publication 800-38B: Recommendation for Block Cipher Modes of Operation:
the CMAC Mode for Authentication [SP800-38B].
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
PSA_ALG_TRUNCATED_MAC (macro)
Macro to build a truncated MAC algorithm.
#define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
/* specification-defined value */
Parameters
mac_alg
A MAC algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_MAC(mac_alg) is true. This can be a truncated or
untruncated MAC algorithm.
mac_length
Desired length of the truncated MAC in bytes. This must be at most
the untruncated length of the MAC and must be at least an
implementation-specified minimum. The implementation-specified
minimum must not be zero.
Returns
The corresponding MAC algorithm with the specified length.
Unspecified if mac_alg is not a supported MAC algorithm or if mac_length is too small or too large for the
specified MAC algorithm.
IHI 0086
Page 135
1.1.2
Non-confidential
Description
A truncated MAC algorithm is identical to the corresponding MAC algorithm except that the MAC value
for the truncated algorithm consists of only the first mac_length bytes of the MAC value for the
untruncated algorithm.
Note:
This macro might allow constructing algorithm identifiers that are not valid, either because the
specified length is larger than the untruncated MAC or because the specified length is smaller than
permitted by the implementation.
Note:
It is implementation-defined whether a truncated MAC that is truncated to the same length as the
MAC of the untruncated algorithm is considered identical to the untruncated algorithm for policy
comparison purposes.
The untruncated MAC algorithm can be recovered using PSA_ALG_FULL_LENGTH_MAC().
Compatible key types
The resulting truncated MAC algorithm is compatible with the same key types as the MAC algorithm used
to construct it.
PSA_ALG_FULL_LENGTH_MAC (macro)
Macro to construct the MAC algorithm with an untruncated MAC, from a truncated MAC algorithm.
#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) /* specification-defined value */
Parameters
mac_alg
A MAC algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_MAC(mac_alg) is true. This can be a truncated or
untruncated MAC algorithm.
Returns
The corresponding MAC algorithm with an untruncated MAC.
Unspecified if mac_alg is not a supported MAC algorithm.
Compatible key types
The resulting untruncated MAC algorithm is compatible with the same key types as the MAC algorithm
used to construct it.
IHI 0086
Page 136
1.1.2
Non-confidential
PSA_ALG_AT_LEAST_THIS_LENGTH_MAC (macro)
Macro to build a MAC minimum-MAC-length wildcard algorithm.
#define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
/* specification-defined value */
Parameters
mac_alg
A MAC algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_MAC(alg) is true. This can be a truncated or untruncated
MAC algorithm.
min_mac_length
Desired minimum length of the message authentication code in
bytes. This must be at most the untruncated length of the MAC and
must be at least 1.
Returns
The corresponding MAC wildcard algorithm with the specified minimum MAC length.
Unspecified if mac_alg is not a supported MAC algorithm or if min_mac_length is less than 1 or too large for
the specified MAC algorithm.
Description
A key with a minimum-MAC-length MAC wildcard algorithm as permitted-algorithm policy can be used
with all MAC algorithms sharing the same base algorithm, and where the (potentially truncated) MAC
length of the specific algorithm is equal to or larger then the wildcard algorithm’s minimum MAC length.
Note:
When setting the minimum required MAC length to less than the smallest MAC length permitted by
the base algorithm, this effectively becomes an ‘any-MAC-length-permitted’ policy for that base
algorithm.
The untruncated MAC algorithm can be recovered using PSA_ALG_FULL_LENGTH_MAC().
Compatible key types
The resulting wildcard MAC algorithm is compatible with the same key types as the MAC algorithm used
to construct it.
10.3.2 Single-part MAC functions
psa_mac_compute (function)
Calculate the message authentication code (MAC) of a message.
psa_status_t psa_mac_compute(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t * input,
size_t input_length,
(continues on next page)
IHI 0086
Page 137
1.1.2
Non-confidential
(continued from previous page)
uint8_t * mac,
size_t
mac_size,
size_t
* mac_length);
Parameters
key
Identifier of the key to use for the operation. It must permit the
usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg
The MAC algorithm to compute: a value of type psa_algorithm_t such
that PSA_ALG_IS_MAC(alg) is true.
input
Buffer containing the input message.
input_length
Size of the input buffer in bytes.
mac
Buffer where the MAC value is to be written.
mac_size
Size of the mac buffer in bytes. This must be appropriate for the
selected algorithm and key:
∙ The exact MAC size is PSA_MAC_LENGTH(key_type, key_bits, alg)
where key_type and key_bits are attributes of the key used to
compute the MAC.
∙ PSA_MAC_MAX_SIZE evaluates to the maximum MAC size of any
supported MAC algorithm.
mac_length
On success, the number of bytes that make up the MAC value.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*mac_length) bytes of mac contain the MAC value.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
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 mac buffer is too small. PSA_MAC_LENGTH() or
PSA_MAC_MAX_SIZE can be used to determine a sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a MAC algorithm.
∙ key is not compatible with alg.
∙ input_length is too large for alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a MAC algorithm.
∙ key is not supported for use with alg.
∙ input_length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
IHI 0086
Page 138
1.1.2
Non-confidential
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
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 might leak information about the MAC value which
could allow an attacker to guess a valid MAC and thereby bypass security controls.
psa_mac_verify (function)
Calculate the MAC of a message and compare it with a reference value.
psa_status_t psa_mac_verify(psa_key_id_t key,
psa_algorithm_t alg,
const uint8_t * input,
size_t input_length,
const uint8_t * mac,
size_t mac_length);
Parameters
key
Identifier of the key to use for the operation. It must permit the
usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg
The MAC algorithm to compute: a value of type psa_algorithm_t such
that PSA_ALG_IS_MAC(alg) is true.
input
Buffer containing the input message.
input_length
Size of the input buffer in bytes.
mac
Buffer containing the expected MAC value.
mac_length
Size of the mac buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success. The expected MAC is identical to the actual MAC of the
input.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_VERIFY_MESSAGE flag, or it
does not permit the requested algorithm.
PSA_ERROR_INVALID_SIGNATURE
The calculated MAC of the message does not match the value in mac.
IHI 0086
Page 139
1.1.2
Non-confidential
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a MAC algorithm.
∙ key is not compatible with alg.
∙ input_length is too large for alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a MAC algorithm.
∙ key is not supported for use with alg.
∙ input_length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
10.3.3 Multi-part MAC operations
psa_mac_operation_t (typedef)
The type of the state object for multi-part MAC operations.
typedef /* implementation-defined type */ psa_mac_operation_t;
Before calling any function on a MAC operation object, the application must initialize it by any of the
following means:
∙ Set the object to all-bits-zero, for example:
psa_mac_operation_t operation;
memset(&operation, 0, sizeof(operation));
∙ Initialize the object to logical zero values by declaring the object as static or global without an
explicit initializer, for example:
static psa_mac_operation_t operation;
∙ Initialize the object 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 object, for example:
psa_mac_operation_t operation;
operation = psa_mac_operation_init();
This is an implementation-defined type. Applications that make assumptions about the content of this
object will result in in implementation-specific behavior, and are non-portable.
IHI 0086
Page 140
1.1.2
Non-confidential
PSA_MAC_OPERATION_INIT (macro)
This macro returns a suitable initializer for a MAC operation object of type psa_mac_operation_t.
#define PSA_MAC_OPERATION_INIT /* implementation-defined value */
psa_mac_operation_init (function)
Return an initial value for a MAC operation object.
psa_mac_operation_t psa_mac_operation_init(void);
Returns: psa_mac_operation_t
psa_mac_sign_setup (function)
Set up a multi-part MAC calculation operation.
psa_status_t psa_mac_sign_setup(psa_mac_operation_t * operation,
psa_key_id_t key,
psa_algorithm_t alg);
Parameters
operation
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 permit the usage
PSA_KEY_USAGE_SIGN_MESSAGE.
alg
The MAC algorithm to compute: a value of type psa_algorithm_t such
that PSA_ALG_IS_MAC(alg) is true.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation is now active.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
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_ARGUMENT
The following conditions can result in this error:
∙ alg is not a MAC algorithm.
∙ key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a MAC algorithm.
∙ key is not supported for use with alg.
IHI 0086
Page 141
1.1.2
Non-confidential
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function sets up the calculation of the message authentication code (MAC) 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:
1. Allocate a MAC operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for
psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
3. Call psa_mac_sign_setup() to specify the algorithm and key.
4. 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.
5. At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and
retrieve it.
After a successful call to psa_mac_sign_setup(), the operation is active, and the application must eventually
terminate the operation. The following events terminate an operation:
∙ A successful call to psa_mac_sign_finish().
∙ A call to psa_mac_abort().
If psa_mac_sign_setup() returns an error, the operation object is unchanged. If a subsequent function call
with an active operation returns an error, the operation enters an error state.
To abandon an active operation, or reset an operation in an error state, call psa_mac_abort().
See Multi-part operations on page 24.
psa_mac_verify_setup (function)
Set up a multi-part MAC verification operation.
psa_status_t psa_mac_verify_setup(psa_mac_operation_t * operation,
psa_key_id_t key,
psa_algorithm_t alg);
IHI 0086
Page 142
1.1.2
Non-confidential
Parameters
operation
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 permit the usage
PSA_KEY_USAGE_VERIFY_MESSAGE.
alg
The MAC algorithm to compute: a value of type psa_algorithm_t such
that PSA_ALG_IS_MAC(alg) is true.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation is now active.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_VERIFY_MESSAGE flag, or it
does not permit the requested algorithm.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a MAC algorithm.
∙ key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a MAC algorithm.
∙ key is not supported for use with alg.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function sets up the verification of the message authentication code (MAC) of a byte string against an
expected value.
The sequence of operations to verify a MAC is as follows:
1. Allocate a MAC operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for
psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
3. Call psa_mac_verify_setup() to specify the algorithm and key.
4. 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.
IHI 0086
Page 143
1.1.2
Non-confidential
5. 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.
After a successful call to psa_mac_verify_setup(), the operation is active, and the application must
eventually terminate the operation. The following events terminate an operation:
∙ A successful call to psa_mac_verify_finish().
∙ A call to psa_mac_abort().
If psa_mac_verify_setup() returns an error, the operation object is unchanged. If a subsequent function call
with an active operation returns an error, the operation enters an error state.
To abandon an active operation, or reset an operation in an error state, call psa_mac_abort().
See Multi-part operations on page 24.
psa_mac_update (function)
Add a message fragment to a multi-part MAC operation.
psa_status_t psa_mac_update(psa_mac_operation_t * operation,
const uint8_t * input,
size_t input_length);
Parameters
operation
Active MAC operation.
input
Buffer containing the message fragment to add to the MAC
calculation.
input_length
Size of the input buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
The total input for the operation is too large for the MAC algorithm.
PSA_ERROR_NOT_SUPPORTED
The total input for the operation is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 144
1.1.2
Non-confidential
Description
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().
psa_mac_sign_finish (function)
Finish the calculation of the MAC of a message.
psa_status_t psa_mac_sign_finish(psa_mac_operation_t * operation,
uint8_t * mac,
size_t mac_size,
size_t * mac_length);
Parameters
operation
Active MAC operation.
mac
Buffer where the MAC value is to be written.
mac_size
Size of the mac buffer in bytes. This must be appropriate for the
selected algorithm and key:
∙ The exact MAC size is PSA_MAC_LENGTH(key_type, key_bits, alg)
where key_type and key_bits are attributes of the key, and alg is
the algorithm used to compute the MAC.
∙ PSA_MAC_MAX_SIZE evaluates to the maximum MAC size of any
supported MAC algorithm.
mac_length
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 attributes of the key, and alg is the algorithm used to
compute the MAC.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*mac_length) bytes of mac contain the MAC value.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be an active mac sign
operation.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the mac buffer is too small. PSA_MAC_LENGTH() or
PSA_MAC_MAX_SIZE can be used to determine a sufficient buffer size.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 145
1.1.2
Non-confidential
Description
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: It is not recommended to use this function when a specific value is expected for the MAC.
Call psa_mac_verify_finish() instead with the expected MAC value.
Comparing integrity or authenticity data such as MAC values with a function such as memcmp() is risky
because the time taken by the comparison might leak information about the hashed data which could
allow an attacker to guess a valid MAC and thereby bypass security controls.
psa_mac_verify_finish (function)
Finish the calculation of the MAC of a message and compare it with an expected value.
psa_status_t psa_mac_verify_finish(psa_mac_operation_t * operation,
const uint8_t * mac,
size_t mac_length);
Parameters
operation
Active MAC operation.
mac
Buffer containing the expected MAC value.
mac_length
Size of the mac buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success. The expected MAC is identical to the actual MAC of the
message.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be an active mac verify
operation.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_SIGNATURE
The calculated MAC of the message does not match the value in mac.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 146
1.1.2
Non-confidential
Description
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 must make the best effort to ensure that the comparison between the actual MAC
and the expected MAC is performed in constant time.
psa_mac_abort (function)
Abort a MAC operation.
psa_status_t psa_mac_abort(psa_mac_operation_t * operation);
Parameters
operation
Initialized MAC operation.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation object can now be discarded or reused.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
Aborting an operation frees all associated resources except for the operation object itself. Once aborted,
the operation object can be reused for another operation by calling psa_mac_sign_setup() or
psa_mac_verify_setup() again.
This function can be called 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.
10.3.4 Support macros
PSA_ALG_IS_HMAC (macro)
Whether the specified algorithm is an HMAC algorithm.
#define PSA_ALG_IS_HMAC(alg) /* specification-defined value */
IHI 0086
Page 147
1.1.2
Non-confidential
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is an HMAC algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported
algorithm identifier.
Description
HMAC is a family of MAC algorithms that are based on a hash function.
PSA_ALG_IS_BLOCK_CIPHER_MAC (macro)
Whether the specified algorithm is a MAC algorithm based on a block cipher.
#define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a MAC algorithm based on a block cipher, 0 otherwise. This macro can return either 0 or 1 if alg is
not a supported algorithm identifier.
PSA_MAC_LENGTH (macro)
The size of the output of psa_mac_compute() and psa_mac_sign_finish(), in bytes.
#define PSA_MAC_LENGTH(key_type, key_bits, alg) \
/* implementation-defined value */
Parameters
key_type
The type of the MAC key.
key_bits
The size of the MAC key in bits.
alg
A MAC algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_MAC(alg) is true.
Returns
The MAC length for the specified algorithm with the specified key parameters.
0 if the MAC algorithm is not recognized.
Either 0 or the correct length for a MAC algorithm that the implementation recognizes, but does not
support.
Unspecified if the key parameters are not consistent with the algorithm.
IHI 0086
Page 148
1.1.2
Non-confidential
Description
If the size of the MAC buffer is at least this large, it is guaranteed that psa_mac_compute() and
psa_mac_sign_finish() will not fail due to an insufficient buffer size.
This is also the MAC length that psa_mac_verify() and psa_mac_verify_finish() expect.
See also PSA_MAC_MAX_SIZE.
PSA_MAC_MAX_SIZE (macro)
A sufficient buffer size for storing the MAC output by psa_mac_verify() and psa_mac_verify_finish(), for
any of the supported key types and MAC algorithms.
#define PSA_MAC_MAX_SIZE /* implementation-defined value */
If the size of the MAC buffer is at least this large, it is guaranteed that psa_mac_verify() and
psa_mac_verify_finish() will not fail due to an insufficient buffer size.
See also PSA_MAC_LENGTH().
10.4 Unauthenticated ciphers
Warning: The unauthenticated cipher API is provided to implement legacy protocols and for use cases
where the data integrity and authenticity is guaranteed by non-cryptographic means.
It is recommended that newer protocols use Authenticated encryption with associated data (AEAD) on
page 175.
The single-part functions for encrypting or decrypting a message using an unauthenticated symmetric
cipher are:
∙ psa_cipher_encrypt() to encrypt a message using an unauthenticated symmetric cipher. The
encryption function generates a random initialization vector (IV). Use the multi-part API to provide a
deterministic IV: this is not secure in general, but can be secure in some conditions that depend on
the algorithm.
∙ psa_cipher_decrypt() to decrypt a message using an unauthenticated symmetric cipher.
The psa_cipher_operation_t multi-part operation permits alternative initialization parameters and allows
messages to be processed in fragments. A multi-part cipher operation is used as follows:
1. Initialize the psa_cipher_operation_t object to zero, or by assigning the value of the associated macro
PSA_CIPHER_OPERATION_INIT.
2. Call psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() to specify the algorithm and key.
3. Provide additional parameters:
∙ When encrypting data, generate or set an IV, nonce, or similar initial value such as an initial
counter value. To generate a random IV, which is recommended in most protocols, call
psa_cipher_generate_iv(). To set the IV, call psa_cipher_set_iv().
IHI 0086
Page 149
1.1.2
Non-confidential
∙ When decrypting, set the IV or nonce. To set the IV, call psa_cipher_set_iv().
4. Call the psa_cipher_update() function on successive chunks of the message.
5. Call psa_cipher_finish() to complete the operation and return any final output.
To abort the operation or recover from an error, call psa_cipher_abort().
10.4.1 Cipher algorithms
PSA_ALG_STREAM_CIPHER (macro)
The stream cipher mode of a stream cipher algorithm.
#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800100)
The underlying stream cipher is determined by the key type. The ARC4 and ChaCha20 ciphers use this
algorithm identifier.
ARC4
To use ARC4, use a key type of PSA_KEY_TYPE_ARC4 and algorithm id PSA_ALG_STREAM_CIPHER.
Warning: The ARC4 cipher is weak and deprecated and is only recommended for use in legacy
applications.
The ARC4 cipher does not use an initialization vector (IV). When using a multi-part cipher operation with
the PSA_ALG_STREAM_CIPHER algorithm and an ARC4 key, psa_cipher_generate_iv() and psa_cipher_set_iv()
must not be called.
ChaCha20
To use ChaCha20, use a key type of PSA_KEY_TYPE_CHACHA20 and algorithm id PSA_ALG_STREAM_CIPHER.
Implementations must support the variant that is defined in ChaCha20 and Poly1305 for IETF Protocols
[RFC7539] §2.4, which has a 96-bit nonce and a 32-bit counter. Implementations can optionally also
support the original variant, as defined in ChaCha, a variant of Salsa20 [CHACHA20], which has a 64-bit
nonce and a 64-bit counter. Except where noted, the [RFC7539] variant must be used.
ChaCha20 defines a nonce and an initial counter to be provided to the encryption and decryption
operations. When using a ChaCha20 key with the PSA_ALG_STREAM_CIPHER algorithm, these values are
provided using the initialization vector (IV) functions in the following ways:
∙ A call to psa_cipher_encrypt() will generate a random 12-byte nonce, and set the counter value to
zero. The random nonce is output as a 12-byte IV value in the output.
∙ A call to psa_cipher_decrypt() will use first 12 bytes of the input buffer as the nonce and set the
counter value to zero.
∙ A call to psa_cipher_generate_iv() on a multi-part cipher operation will generate and return a random
12-byte nonce and set the counter value to zero.
∙ A call to psa_cipher_set_iv() on a multi-part cipher operation can support the following IV sizes:
- 12 bytes: the provided IV is used as the nonce, and the counter value is set to zero.
IHI 0086
Page 150
1.1.2
Non-confidential
- 16 bytes: the first four bytes of the IV are used as the counter value (encoded as little-endian),
and the remaining 12 bytes is used as the nonce.
- 8 bytes: the cipher operation uses the original [CHACHA20] definition of ChaCha20: the
provided IV is used as the 64-bit nonce, and the 64-bit counter value is set to zero.
- It is recommended that implementations do not support other sizes of IV.
Compatible key types
PSA_KEY_TYPE_ARC4
PSA_KEY_TYPE_CHACHA20
PSA_ALG_CTR (macro)
A stream cipher built using the Counter (CTR) mode of a block cipher.
#define PSA_ALG_CTR ((psa_algorithm_t)0x04c01000)
CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the
key type. For example, to use AES-128-CTR, use this algorithm with a key of type PSA_KEY_TYPE_AES and a
size of 128 bits (16 bytes).
The CTR block cipher mode is defined in NIST Special Publication 800-38A: Recommendation for Block
Cipher Modes of Operation: Methods and Techniques [SP800-38A].
CTR mode requires a counter block which is the same size as the cipher block length. The counter block is
updated for each block (or a partial final block) that is encrypted or decrypted.
A counter block value must only be used once across all messages encrypted using the same key value.
This is typically achieved by splitting the counter block into a nonce, which is unique among all message
encrypted with the key, and a counter which is incremented for each block of a message.
For example, when using AES-CTR encryption, which uses a 16-byte block, the application can provide a
12-byte nonce when setting the IV. This leaves 4 bytes for the counter, allowing up to 2^32 blocks (64GB)
of message data to be encrypted in each message.
The first counter block is constructed from the initialization vector (IV). The initial counter block is is
constructed in the following ways:
∙ A call to psa_cipher_encrypt() will generate a random counter block value. This is the first block of
output.
∙ A call to psa_cipher_decrypt() will use first block of the input buffer as the initial counter block value.
∙ A call to psa_cipher_generate_iv() on a multi-part cipher operation will generate and return a random
counter block value.
∙ A call to psa_cipher_set_iv() on a multi-part cipher operation requires an IV that is between 1 and n
bytes in length, where n is the cipher block length. The counter block is initialized using the IV, and
padded with zero bytes up to the block length.
During the counter block update operation, the counter block is treated as a single big-endian encoded
integer and the update operation increments this integer by 1.
This scheme meets the recommendations in Appendix B of [SP800-38A].
IHI 0086
Page 151
1.1.2
Non-confidential
Note:
The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
PSA_ALG_CFB (macro)
A stream cipher built using the Cipher Feedback (CFB) mode of a block cipher.
#define PSA_ALG_CFB ((psa_algorithm_t)0x04c01100)
The underlying block cipher is determined by the key type. This is the variant of CFB where each iteration
encrypts or decrypts a segment of the input that is the same length as the cipher block size. For example,
using PSA_ALG_CFB with a key of type PSA_KEY_TYPE_AES will result in the AES-CFB-128 cipher.
CFB mode requires an initialization vector (IV) that is the same size as the cipher block length.
Note:
The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().
The CFB block cipher mode is defined in NIST Special Publication 800-38A: Recommendation for Block Cipher
Modes of Operation: Methods and Techniques [SP800-38A], using a segment size s equal to the block size b.
The definition in [SP800-38A] is extended to allow an incomplete final block of input, in which case the
algorithm discards the final bytes of the key stream when encrypting or decrypting the final partial block.
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
IHI 0086
Page 152
1.1.2
Non-confidential
PSA_ALG_OFB (macro)
A stream cipher built using the Output Feedback (OFB) mode of a block cipher.
#define PSA_ALG_OFB ((psa_algorithm_t)0x04c01200)
The underlying block cipher is determined by the key type.
OFB mode requires an initialization vector (IV) that is the same size as the cipher block length. OFB mode
requires that the IV is a nonce, and must be unique for each use of the mode with the same key.
Note:
The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().
The OFB block cipher mode is defined in NIST Special Publication 800-38A: Recommendation for Block
Cipher Modes of Operation: Methods and Techniques [SP800-38A].
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
PSA_ALG_XTS (macro)
The XEX with Ciphertext Stealing (XTS) cipher mode of a block cipher.
#define PSA_ALG_XTS ((psa_algorithm_t)0x0440ff00)
XTS is a cipher mode which is built from a block cipher, designed for use in disk encryption. It requires at
least one full cipher block length of input, but beyond this minimum the input does not need to be a whole
number of blocks.
XTS mode uses two keys for the underlying block cipher. These are provided by using a key that is twice
the normal key size for the cipher. For example, to use AES-256-XTS the application must create a key
with type PSA_KEY_TYPE_AES and bit size 512.
XTS mode requires an initialization vector (IV) that is the same size as the cipher block length. The IV for
XTS is typically defined to be the sector number of the disk block being encrypted or decrypted.
The XTS block cipher mode is defined in 1619-2018 --- IEEE Standard for Cryptographic Protection of Data
on Block-Oriented Storage Devices [IEEE-XTS].
IHI 0086
Page 153
1.1.2
Non-confidential
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
PSA_ALG_ECB_NO_PADDING (macro)
The Electronic Codebook (ECB) mode of a block cipher, with no padding.
#define PSA_ALG_ECB_NO_PADDING ((psa_algorithm_t)0x04404400)
Warning: ECB mode does not protect the confidentiality of the encrypted data except in extremely
narrow circumstances. It is recommended that applications only use ECB if they need to construct an
operating mode that the implementation does not provide. Implementations are encouraged to provide
the modes that applications need in preference to supporting direct access to ECB.
The underlying block cipher is determined by the key type.
This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block
size of the chosen block cipher.
ECB mode does not accept an initialization vector (IV). When using a multi-part cipher operation with this
algorithm, psa_cipher_generate_iv() and psa_cipher_set_iv() must not be called.
Note:
The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().
The ECB block cipher mode is defined in NIST Special Publication 800-38A: Recommendation for Block
Cipher Modes of Operation: Methods and Techniques [SP800-38A].
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
IHI 0086
Page 154
1.1.2
Non-confidential
PSA_ALG_CBC_NO_PADDING (macro)
The Cipher Block Chaining (CBC) mode of a block cipher, with no padding.
#define PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t)0x04404000)
The underlying block cipher is determined by the key type.
This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block
size of the chosen block cipher.
CBC mode requires an initialization vector (IV) that is the same size as the cipher block length.
Note:
The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().
The CBC block cipher mode is defined in NIST Special Publication 800-38A: Recommendation for Block
Cipher Modes of Operation: Methods and Techniques [SP800-38A].
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
PSA_ALG_CBC_PKCS7 (macro)
The Cipher Block Chaining (CBC) mode of a block cipher, with PKCS#7 padding.
#define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t)0x04404100)
The underlying block cipher is determined by the key type.
CBC mode requires an initialization vector (IV) that is the same size as the cipher block length.
Note:
The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().
The CBC block cipher mode is defined in NIST Special Publication 800-38A: Recommendation for Block
Cipher Modes of Operation: Methods and Techniques [SP800-38A]. The padding operation is defined by
PKCS #7: Cryptographic Message Syntax Version 1.5 [RFC2315] §10.3.
IHI 0086
Page 155
1.1.2
Non-confidential
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
10.4.2 Single-part cipher functions
psa_cipher_encrypt (function)
Encrypt a message using a symmetric cipher.
psa_status_t psa_cipher_encrypt(psa_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);
Parameters
key
Identifier of the key to use for the operation. It must permit the
usage PSA_KEY_USAGE_ENCRYPT.
alg
The cipher algorithm to compute: a value of type psa_algorithm_t
such that PSA_ALG_IS_CIPHER(alg) is true.
input
Buffer containing the message to encrypt.
input_length
Size of the input buffer in bytes.
output
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. This must be appropriate for the
selected algorithm and key:
∙ A sufficient output size is
PSA_CIPHER_ENCRYPT_OUTPUT_SIZE(key_type, alg, input_length)
where key_type is the type of key.
∙ PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE(input_length) evaluates to
the maximum output size of any supported cipher encryption.
output_length
On success, the number of bytes that make up the output.
IHI 0086
Page 156
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*output_length) bytes of output contain the
encrypted output.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_BUFFER_TOO_SMALL
The size of the output buffer is too small.
PSA_CIPHER_ENCRYPT_OUTPUT_SIZE() or
PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE() can be used to determine a
sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a cipher algorithm.
∙ key is not compatible with alg.
∙ The input_length is not valid for the algorithm and key type. 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_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a cipher algorithm.
∙ key is not supported for use with alg.
∙ input_length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function encrypts a message with a random initialization vector (IV). The length of the IV is
PSA_CIPHER_IV_LENGTH(key_type, alg) where key_type is the type of key. The output of psa_cipher_encrypt()
is the IV followed by the ciphertext.
Use the multi-part operation interface with a psa_cipher_operation_t object to provide other forms of IV or
to manage the IV and ciphertext independently.
IHI 0086
Page 157
1.1.2
Non-confidential
psa_cipher_decrypt (function)
Decrypt a message using a symmetric cipher.
psa_status_t psa_cipher_decrypt(psa_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);
Parameters
key
Identifier of the key to use for the operation. It must remain valid
until the operation terminates. It must permit the usage
PSA_KEY_USAGE_DECRYPT.
alg
The cipher algorithm to compute: a value of type psa_algorithm_t
such that PSA_ALG_IS_CIPHER(alg) is true.
input
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
Buffer where the plaintext 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_CIPHER_DECRYPT_OUTPUT_SIZE(key_type, alg, input_length)
where key_type is the type of key.
∙ PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE(input_length) evaluates to
the maximum output size of any supported cipher decryption.
output_length
On success, the number of bytes that make up the output.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*output_length) bytes of output contain the
plaintext.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_BUFFER_TOO_SMALL
The size of the output buffer is too small.
PSA_CIPHER_DECRYPT_OUTPUT_SIZE() or
PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE() can be used to determine a
sufficient buffer size.
PSA_ERROR_INVALID_PADDING
The algorithm uses padding, and the input does not contain valid
padding.
IHI 0086
Page 158
1.1.2
Non-confidential
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a cipher algorithm.
∙ key is not compatible with alg.
∙ The input_length is not valid for the algorithm and key type. 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_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a cipher algorithm.
∙ key is not supported for use with alg.
∙ input_length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function decrypts a message encrypted with a symmetric cipher.
The input to this function must contain the IV followed by the ciphertext, as output by
psa_cipher_encrypt(). The IV must be PSA_CIPHER_IV_LENGTH(key_type, alg) bytes in length, where key_type
is the type of key.
Use the multi-part operation interface with a psa_cipher_operation_t object to decrypt data which is not in
the expected input format.
10.4.3 Multi-part cipher operations
psa_cipher_operation_t (typedef)
The type of the state object for multi-part cipher operations.
typedef /* implementation-defined type */ psa_cipher_operation_t;
Before calling any function on a cipher operation object, the application must initialize it by any of the
following means:
∙ Set the object to all-bits-zero, for example:
psa_cipher_operation_t operation;
memset(&operation, 0, sizeof(operation));
∙ Initialize the object to logical zero values by declaring the object as static or global without an
explicit initializer, for example:
IHI 0086
Page 159
1.1.2
Non-confidential
static psa_cipher_operation_t operation;
∙ Initialize the object 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 object, for example:
psa_cipher_operation_t operation;
operation = psa_cipher_operation_init();
This is an implementation-defined type. Applications that make assumptions about the content of this
object will result in in implementation-specific behavior, and are non-portable.
PSA_CIPHER_OPERATION_INIT (macro)
This macro returns a suitable initializer for a cipher operation object of type psa_cipher_operation_t.
#define PSA_CIPHER_OPERATION_INIT /* implementation-defined value */
psa_cipher_operation_init (function)
Return an initial value for a cipher operation object.
psa_cipher_operation_t psa_cipher_operation_init(void);
Returns: psa_cipher_operation_t
psa_cipher_encrypt_setup (function)
Set the key for a multi-part symmetric encryption operation.
psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t * operation,
psa_key_id_t key,
psa_algorithm_t alg);
Parameters
operation
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 permit the usage
PSA_KEY_USAGE_ENCRYPT.
alg
The cipher algorithm to compute: a value of type psa_algorithm_t
such that PSA_ALG_IS_CIPHER(alg) is true.
IHI 0086
Page 160
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. The operation is now active.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a cipher algorithm.
∙ key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a cipher algorithm.
∙ key is not supported for use with alg.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The sequence of operations to encrypt a message with a symmetric cipher is as follows:
1. Allocate a cipher operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for
psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
3. Call psa_cipher_encrypt_setup() to specify the algorithm and key.
4. Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to generate or set the initialization
vector (IV), if the algorithm requires one. It is recommended to use psa_cipher_generate_iv() unless
the protocol being implemented requires a specific IV value.
5. Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
6. Call psa_cipher_finish().
After a successful call to psa_cipher_encrypt_setup(), the operation is active, and 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().
If psa_cipher_encrypt_setup() returns an error, the operation object is unchanged. If a subsequent function
call with an active operation returns an error, the operation enters an error state.
IHI 0086
Page 161
1.1.2
Non-confidential
To abandon an active operation, or reset an operation in an error state, call psa_cipher_abort().
See Multi-part operations on page 24.
psa_cipher_decrypt_setup (function)
Set the key for a multi-part symmetric decryption operation.
psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t * operation,
psa_key_id_t key,
psa_algorithm_t alg);
Parameters
operation
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 permit the usage
PSA_KEY_USAGE_DECRYPT.
alg
The cipher algorithm to compute: a value of type psa_algorithm_t
such that PSA_ALG_IS_CIPHER(alg) is true.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation is now active.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not a cipher algorithm.
∙ key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not a cipher algorithm.
∙ key is not supported for use with alg.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 162
1.1.2
Non-confidential
Description
The sequence of operations to decrypt a message with a symmetric cipher is as follows:
1. Allocate a cipher operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for
psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
3. Call psa_cipher_decrypt_setup() to specify the algorithm and key.
4. Call psa_cipher_set_iv() with the initialization vector (IV) for the decryption, if the algorithm requires
one. This must match the IV used for the encryption.
5. Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
6. Call psa_cipher_finish().
After a successful call to psa_cipher_decrypt_setup(), the operation is active, and 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().
If psa_cipher_decrypt_setup() returns an error, the operation object is unchanged. If a subsequent function
call with an active operation returns an error, the operation enters an error state.
To abandon an active operation, or reset an operation in an error state, call psa_cipher_abort().
See Multi-part operations on page 24.
psa_cipher_generate_iv (function)
Generate an initialization vector (IV) for a symmetric encryption operation.
psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t * operation,
uint8_t * iv,
size_t iv_size,
size_t * iv_length);
Parameters
operation
Active cipher operation.
iv
Buffer where the generated IV is to be written.
iv_size
Size of the iv buffer in bytes. This must be at least
PSA_CIPHER_IV_LENGTH(key_type, alg) where key_type and alg are type
of key and the algorithm respectively that were used to set up the
cipher operation.
iv_length
On success, the number of bytes of the generated IV.
IHI 0086
Page 163
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*iv_length) bytes of iv contain the generated IV.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The cipher algorithm does not use an IV.
∙ The operation state is not valid: it must be active, with no IV set.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the iv buffer is too small. PSA_CIPHER_IV_LENGTH() or
PSA_CIPHER_IV_MAX_SIZE can be used to determine a sufficient buffer
size.
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function generates a random IV, nonce or initial counter value for the encryption operation as
appropriate for the chosen algorithm, key type and key size.
The generated IV is always the default length for the key and algorithm: PSA_CIPHER_IV_LENGTH(key_type,
alg), where key_type is the type of key and alg is the algorithm that were used to set up the operation. To
generate different lengths of IV, use psa_generate_random() and psa_cipher_set_iv().
If the cipher algorithm does not use an IV, calling this function returns a PSA_ERROR_BAD_STATE error. For
these algorithms, PSA_CIPHER_IV_LENGTH(key_type, alg) will be zero.
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().
psa_cipher_set_iv (function)
Set the initialization vector (IV) for a symmetric encryption or decryption operation.
psa_status_t psa_cipher_set_iv(psa_cipher_operation_t * operation,
const uint8_t * iv,
size_t iv_length);
IHI 0086
Page 164
1.1.2
Non-confidential
Parameters
operation
Active cipher operation.
iv
Buffer containing the IV to use.
iv_length
Size of the IV in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The cipher algorithm does not use an IV.
∙ The operation state is not valid: it must be an active cipher
encrypt operation, with no IV set.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ The chosen algorithm does not use an IV.
∙ iv_length is not valid for the chosen algorithm.
PSA_ERROR_NOT_SUPPORTED
iv_length is not supported for use with the operation’s algorithm and
key.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function sets the IV, nonce or initial counter value for the encryption or decryption operation.
If the cipher algorithm does not use an IV, calling this function returns a PSA_ERROR_BAD_STATE error. For
these algorithms, PSA_CIPHER_IV_LENGTH(key_type, alg) will be zero.
The application must call psa_cipher_encrypt_setup() or psa_cipher_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_cipher_abort().
Note:
When encrypting, psa_cipher_generate_iv() is recommended instead of using this function, unless
implementing a protocol that requires a non-random IV.
IHI 0086
Page 165
1.1.2
Non-confidential
psa_cipher_update (function)
Encrypt or decrypt a message fragment in an active cipher operation.
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);
Parameters
operation
Active cipher operation.
input
Buffer containing the message fragment to encrypt or decrypt.
input_length
Size of the input buffer in bytes.
output
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_CIPHER_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_CIPHER_UPDATE_OUTPUT_MAX_SIZE(input_length) evaluates to
the maximum output size of any supported cipher algorithm.
output_length
On success, the number of bytes that make up the returned output.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*output_length) bytes of output contain the output
data.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active, with an IV set
if required for the algorithm.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the output buffer is too small.
PSA_CIPHER_UPDATE_OUTPUT_SIZE() or
PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE() can be used to determine a
sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The total input size passed to this operation is too large for this
particular algorithm.
PSA_ERROR_NOT_SUPPORTED
The total input size passed to this operation is too large for the
implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
IHI 0086
Page 166
1.1.2
Non-confidential
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The following must occur before calling this function:
1. 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.
2. If the algorithm requires an IV, call psa_cipher_generate_iv() or psa_cipher_set_iv().
psa_cipher_generate_iv() is recommended when encrypting.
If this function returns an error status, the operation enters an error state and must be aborted by calling
psa_cipher_abort().
Note:
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 might delay the end of the corresponding output until a subsequent call to psa_cipher_update()
provides sufficient input, or a subsequent call to psa_cipher_finish() indicates the end of the input.
The amount of data that can be delayed in this way is bounded by the associated output size macro:
PSA_CIPHER_UPDATE_OUTPUT_SIZE() or PSA_CIPHER_FINISH_OUTPUT_SIZE().
psa_cipher_finish (function)
Finish encrypting or decrypting a message in a cipher operation.
psa_status_t psa_cipher_finish(psa_cipher_operation_t * operation,
uint8_t * output,
size_t output_size,
size_t * output_length);
Parameters
operation
Active cipher operation.
output
Buffer where the last part of 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_CIPHER_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_CIPHER_FINISH_OUTPUT_MAX_SIZE evaluates to the maximum
output size of any supported cipher algorithm.
IHI 0086
Page 167
1.1.2
Non-confidential
output_length
On success, the number of bytes that make up the returned output.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*output_length) bytes of output contain the final
output.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active, with an IV set
if required for the algorithm.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the output buffer is too small.
PSA_CIPHER_FINISH_OUTPUT_SIZE() or
PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE can be used to determine a
sufficient buffer 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_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_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
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().
psa_cipher_abort (function)
Abort a cipher operation.
psa_status_t psa_cipher_abort(psa_cipher_operation_t * operation);
IHI 0086
Page 168
1.1.2
Non-confidential
Parameters
operation
Initialized cipher operation.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation object can now be discarded or reused.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
Aborting an operation frees all associated resources except for the operation object itself. Once aborted,
the operation object can be reused for another operation by calling psa_cipher_encrypt_setup() or
psa_cipher_decrypt_setup() again.
This function can be called 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.
10.4.4 Support macros
PSA_ALG_IS_STREAM_CIPHER (macro)
Whether the specified algorithm is a stream cipher.
#define PSA_ALG_IS_STREAM_CIPHER(alg) /* specification-defined value */
Parameters
alg
An algorithm identifier: a value of type psa_algorithm_t.
Returns
1 if alg is a stream cipher algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a
supported algorithm identifier or if it is not a symmetric cipher algorithm.
Description
A stream cipher is a symmetric cipher that encrypts or decrypts messages by applying a bitwise-xor with a
stream of bytes that is generated from a key.
PSA_CIPHER_ENCRYPT_OUTPUT_SIZE (macro)
A sufficient output buffer size for psa_cipher_encrypt(), in bytes.
#define PSA_CIPHER_ENCRYPT_OUTPUT_SIZE(key_type, alg, input_length) \
/* implementation-defined value */
IHI 0086
Page 169
1.1.2
Non-confidential
Parameters
key_type
A symmetric key type that is compatible with algorithm alg.
alg
A cipher algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_CIPHER(alg) is true.
input_length
Size of the input in bytes.
Returns
A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not
recognized, or the parameters are incompatible, return 0. An implementation can return either 0 or a
correct size for a key type and cipher algorithm that it recognizes, but does not support.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_encrypt() will not fail
due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be
smaller.
See also PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE.
PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE (macro)
A sufficient output buffer size for psa_cipher_encrypt(), for any of the supported key types and cipher
algorithms.
#define PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE(input_length) \
/* implementation-defined value */
Parameters
input_length
Size of the input in bytes.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_encrypt() will not fail
due to an insufficient buffer size.
See also PSA_CIPHER_ENCRYPT_OUTPUT_SIZE().
PSA_CIPHER_DECRYPT_OUTPUT_SIZE (macro)
A sufficient output buffer size for psa_cipher_decrypt(), in bytes.
#define PSA_CIPHER_DECRYPT_OUTPUT_SIZE(key_type, alg, input_length) \
/* implementation-defined value */
IHI 0086
Page 170
1.1.2
Non-confidential
Parameters
key_type
A symmetric key type that is compatible with algorithm alg.
alg
A cipher algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_CIPHER(alg) is true.
input_length
Size of the input in bytes.
Returns
A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not
recognized, or the parameters are incompatible, return 0. An implementation can return either 0 or a
correct size for a key type and cipher algorithm that it recognizes, but does not support.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_decrypt() will not fail
due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be
smaller.
See also PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE.
PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE (macro)
A sufficient output buffer size for psa_cipher_decrypt(), for any of the supported key types and cipher
algorithms.
#define PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE(input_length) \
/* implementation-defined value */
Parameters
input_length
Size of the input in bytes.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_decrypt() will not fail
due to an insufficient buffer size.
See also PSA_CIPHER_DECRYPT_OUTPUT_SIZE().
PSA_CIPHER_IV_LENGTH (macro)
The default IV size for a cipher algorithm, in bytes.
#define PSA_CIPHER_IV_LENGTH(key_type, alg) /* implementation-defined value */
IHI 0086
Page 171
1.1.2
Non-confidential
Parameters
key_type
A symmetric key type that is compatible with algorithm alg.
alg
A cipher algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_CIPHER(alg) is true.
Returns
The default IV size for the specified key type and algorithm. If the algorithm does not use an IV, return 0. If
the key type or cipher algorithm is not recognized, or the parameters are incompatible, return 0. An
implementation can return either 0 or a correct size for a key type and cipher algorithm that it recognizes,
but does not support.
Description
The IV that is generated as part of a call to psa_cipher_encrypt() is always the default IV length for the
algorithm.
This macro can be used to allocate a buffer of sufficient size to store the IV output from
psa_cipher_generate_iv() when using a multi-part cipher operation.
See also PSA_CIPHER_IV_MAX_SIZE.
PSA_CIPHER_IV_MAX_SIZE (macro)
A sufficient buffer size for storing the IV generated by psa_cipher_generate_iv(), for any of the supported
key types and cipher algorithms.
#define PSA_CIPHER_IV_MAX_SIZE /* implementation-defined value */
If the size of the IV buffer is at least this large, it is guaranteed that psa_cipher_generate_iv() will not fail
due to an insufficient buffer size.
See also PSA_CIPHER_IV_LENGTH().
PSA_CIPHER_UPDATE_OUTPUT_SIZE (macro)
A sufficient output buffer size for psa_cipher_update(), in bytes.
#define PSA_CIPHER_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \
/* implementation-defined value */
Parameters
key_type
A symmetric key type that is compatible with algorithm alg.
alg
A cipher algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_CIPHER(alg) is true.
input_length
Size of the input in bytes.
IHI 0086
Page 172
1.1.2
Non-confidential
Returns
A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not
recognized, or the parameters are incompatible, return 0. An implementation can return either 0 or a
correct size for a key type and cipher algorithm that it recognizes, but does not support.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_update() will not fail
due to an insufficient buffer size. The actual size of the output might be smaller in any given call.
See also PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE.
PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE (macro)
A sufficient output buffer size for psa_cipher_update(), for any of the supported key types and cipher
algorithms.
#define PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE(input_length) \
/* implementation-defined value */
Parameters
input_length
Size of the input in bytes.
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_update() will not fail
due to an insufficient buffer size.
See also PSA_CIPHER_UPDATE_OUTPUT_SIZE().
PSA_CIPHER_FINISH_OUTPUT_SIZE (macro)
A sufficient output buffer size for psa_cipher_finish().
#define PSA_CIPHER_FINISH_OUTPUT_SIZE(key_type, alg) \
/* implementation-defined value */
Parameters
key_type
A symmetric key type that is compatible with algorithm alg.
alg
A cipher algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_CIPHER(alg) is true.
Returns
A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not
recognized, or the parameters are incompatible, return 0. An implementation can return either 0 or a
correct size for a key type and cipher algorithm that it recognizes, but does not support.
IHI 0086
Page 173
1.1.2
Non-confidential
Description
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_finish() will not fail
due to an insufficient buffer size. The actual size of the output might be smaller in any given call.
See also PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE.
PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE (macro)
A sufficient output buffer size for psa_cipher_finish(), for any of the supported key types and cipher
algorithms.
#define PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE /* implementation-defined value */
If the size of the output buffer is at least this large, it is guaranteed that psa_cipher_finish() will not fail
due to an insufficient buffer size.
See also PSA_CIPHER_FINISH_OUTPUT_SIZE().
PSA_BLOCK_CIPHER_BLOCK_LENGTH (macro)
The block size of a block cipher.
#define PSA_BLOCK_CIPHER_BLOCK_LENGTH(type) /* specification-defined value */
Parameters
type
A cipher key type: a value of type psa_key_type_t.
Returns
The block size for a block cipher, or 1 for a stream cipher. The return value is undefined if type is not a
supported cipher key type.
Description
Note:
It is possible to build stream cipher algorithms on top of a block cipher, for example CTR mode
(PSA_ALG_CTR). This macro only takes the key type into account, so it cannot be used to determine the
size of the data that psa_cipher_update() might buffer for future processing in general.
See also PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE.
PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE (macro)
The maximum block size of a block cipher supported by the implementation.
#define PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE /* implementation-defined value */
See also PSA_BLOCK_CIPHER_BLOCK_LENGTH().
IHI 0086
Page 174
1.1.2
Non-confidential
10.5 Authenticated encryption with associated data (AEAD)
The single-part AEAD functions are:
∙ psa_aead_encrypt() to encrypt a message using an authenticated symmetric cipher.
∙ psa_aead_decrypt() to decrypt a message using an authenticated symmetric cipher.
These functions follow the interface recommended by An Interface and Algorithms for Authenticated
Encryption [RFC5116].
The encryption function requires a nonce to be provided. To generate a random nonce, either call
psa_generate_random() or use the AEAD multi-part API.
The psa_aead_operation_t multi-part operation permits alternative initialization parameters and allows
messages to be processed in fragments. A multi-part AEAD operation is used as follows:
1. Initialize the psa_aead_operation_t object to zero, or by assigning the value of the associated macro
PSA_AEAD_OPERATION_INIT.
2. Call psa_aead_encrypt_setup() or psa_aead_decrypt_setup() to specify the algorithm and key.
3. Provide additional parameters:
∙ If the algorithm requires it, call psa_aead_set_lengths() to specify the length of the
non-encrypted and encrypted inputs to the operation.
∙ When encrypting, call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or
set the nonce.
∙ When decrypting, call psa_aead_set_nonce() to set the nonce.
4. Call psa_aead_update_ad() zero or more times with fragments of the non-encrypted additional data.
5. Call psa_aead_update() zero or more times with fragments of the plaintext or ciphertext to encrypt or
decrypt.
6. At the end of the message, call the required finishing function:
∙ To complete an encryption operation, call psa_aead_finish() to compute and return
authentication tag.
∙ To complete a decryption operation, call psa_aead_verify() to compute the authentication tag
and verify it against a reference value.
To abort the operation or recover from an error, call psa_aead_abort().
Note:
Using a multi-part interface to authenticated encryption raises specific issues.
∙ Multi-part authenticated decryption produces intermediate results that are not authenticated.
Revealing unauthenticated results, either directly or indirectly through the application’s
behavior, can compromise the confidentiality of all inputs that are encrypted with the same key.
See the detailed warning.
∙ For encryption, some common algorithms cannot be processed in a streaming fashion. For SIV
mode, the whole plaintext must be known before the encryption can start; the multi-part AEAD
API is not meant to be usable with SIV mode. For CCM mode, the length of the plaintext must
IHI 0086
Page 175
1.1.2
Non-confidential
be known before the encryption can start; the application can call the function
psa_aead_set_lengths() to provide these lengths before providing input.
10.5.1 AEAD algorithms
PSA_ALG_CCM (macro)
The Counter with CBC-MAC (CCM) authenticated encryption algorithm.
#define PSA_ALG_CCM ((psa_algorithm_t)0x05500100)
CCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined
by the key type.
To use PSA_ALG_CCM with a multi-part AEAD operation, the application must call psa_aead_set_lengths()
before providing the nonce, the additional data and plaintext to the operation.
CCM requires a nonce of between 7 and 13 bytes in length. The length of the nonce affects the maximum
length of the plaintext than can be encrypted or decrypted. If the nonce has length N, then the plaintext
length pLen is encoded in L = 15 - N octets, this requires that pLen < 28L.
The value for L that is used with PSA_ALG_CCM depends on the function used to provide the nonce:
∙ A call to psa_aead_encrypt(), psa_aead_decrypt(), or psa_aead_set_nonce() will set L to 15 -
nonce_length. If the plaintext length cannot be encoded in L octets, then a PSA_ERROR_INVALID_ARGUMENT
error is returned.
∙ A call to psa_aead_generate_nonce() on a multi-part cipher operation will select L as the smallest
integer >= 2 where pLen < 28L, with pLen being the plaintext_length provided to
psa_aead_set_lengths(). The call to psa_aead_generate_nonce() will generate and return a random
nonce of length 15 - L bytes.
CCM supports authentication tag sizes of 4, 6, 8, 10, 12, 14, and 16 bytes. The default tag length is 16.
Shortened tag lengths can be requested using PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length),
where tag_length is a valid CCM tag length.
The CCM block cipher mode is defined in Counter with CBC-MAC (CCM) [RFC3610].
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
IHI 0086
Page 176
1.1.2
Non-confidential
PSA_ALG_GCM (macro)
The Galois/Counter Mode (GCM) authenticated encryption algorithm.
#define PSA_ALG_GCM ((psa_algorithm_t)0x05500200)
GCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined
by the key type.
GCM requires a nonce of at least 1 byte in length. The maximum supported nonce size is IMPLEMENTATION
DEFINED. Calling psa_aead_generate_nonce() will generate a random 12-byte nonce.
GCM supports authentication tag sizes of 4, 8, 12, 13, 14, 15, and 16 bytes. The default tag length is 16.
Shortened tag lengths can be requested using PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, tag_length),
where tag_length is a valid GCM tag length.
The GCM block cipher mode is defined in NIST Special Publication 800-38D: Recommendation for Block
Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC [SP800-38D].
Compatible key types
PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4
PSA_ALG_CHACHA20_POLY1305 (macro)
The ChaCha20-Poly1305 AEAD algorithm.
#define PSA_ALG_CHACHA20_POLY1305 ((psa_algorithm_t)0x05100500)
There are two defined variants of ChaCha20-Poly1305:
∙ An implementation that supports ChaCha20-Poly1305 must support the variant defined by
ChaCha20 and Poly1305 for IETF Protocols [RFC7539], which has a 96-bit nonce and 32-bit counter.
∙ An implementation can optionally also support the original variant defined by ChaCha, a variant of
Salsa20 [CHACHA20], which has a 64-bit nonce and 64-bit counter.
The variant used for the AEAD encryption or decryption operation, depends on the nonce provided for an
AEAD operation using PSA_ALG_CHACHA20_POLY1305:
∙ A nonce provided in a call to psa_aead_encrypt(), psa_aead_decrypt() or psa_aead_set_nonce() must be
8 or 12 bytes. The size of nonce will select the appropriate variant of the algorithm.
∙ A nonce generated by a call to psa_aead_generate_nonce() will be 12 bytes, and will use the
[RFC7539] variant.
Implementations must support 16-byte tags. It is recommended that truncated tag sizes are rejected.
IHI 0086
Page 177
1.1.2
Non-confidential
Compatible key types
PSA_KEY_TYPE_CHACHA20
PSA_ALG_AEAD_WITH_SHORTENED_TAG (macro)
Macro to build a AEAD algorithm with a shortened tag.
#define PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length) \
/* specification-defined value */
Parameters
aead_alg
An AEAD algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_AEAD(aead_alg) is true.
tag_length
Desired length of the authentication tag in bytes.
Returns
The corresponding AEAD algorithm with the specified tag length.
Unspecified if aead_alg is not a supported AEAD algorithm or if tag_length is not valid for the specified
AEAD algorithm.
Description
An AEAD algorithm with a shortened tag is similar to the corresponding AEAD algorithm, but has an
authentication tag that consists of fewer bytes. Depending on the algorithm, the tag length might affect
the calculation of the ciphertext.
The AEAD algorithm with a default length tag can be recovered using
PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG().
Compatible key types
The resulting AEAD algorithm is compatible with the same key types as the AEAD algorithm used to
construct it.
PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG (macro)
An AEAD algorithm with the default tag length.
#define PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(aead_alg) \
/* specification-defined value */
Parameters
aead_alg
An AEAD algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_AEAD(aead_alg) is true.
IHI 0086
Page 178
1.1.2
Non-confidential
Returns
The corresponding AEAD algorithm with the default tag length for that algorithm.
Description
This macro can be used to construct the AEAD algorithm with default tag length from an AEAD algorithm
with a shortened tag. See also PSA_ALG_AEAD_WITH_SHORTENED_TAG().
Compatible key types
The resulting AEAD algorithm is compatible with the same key types as the AEAD algorithm used to
construct it.
PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG (macro)
Macro to build an AEAD minimum-tag-length wildcard algorithm.
#define PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG(aead_alg, min_tag_length) \
/* specification-defined value */
Parameters
aead_alg
An AEAD algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_AEAD(aead_alg) is true.
min_tag_length
Desired minimum length of the authentication tag in bytes. This must
be at least 1 and at most the largest permitted tag length of the
algorithm.
Returns
The corresponding AEAD wildcard algorithm with the specified minimum tag length.
Unspecified if aead_alg is not a supported AEAD algorithm or if min_tag_length is less than 1 or too large
for the specified AEAD algorithm.
Description
A key with a minimum-tag-length AEAD wildcard algorithm as permitted-algorithm policy can be used
with all AEAD algorithms sharing the same base algorithm, and where the tag length of the specific
algorithm is equal to or larger then the minimum tag length specified by the wildcard algorithm.
Note:
When setting the minimum required tag length to less than the smallest tag length permitted by the
base algorithm, this effectively becomes an ‘any-tag-length-permitted’ policy for that base algorithm.
The AEAD algorithm with a default length tag can be recovered using
PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG().
IHI 0086
Page 179
1.1.2
Non-confidential
Compatible key types
The resulting wildcard AEAD algorithm is compatible with the same key types as the AEAD algorithm used
to construct it.
10.5.2 Single-part AEAD functions
psa_aead_encrypt (function)
Process an authenticated encryption operation.
psa_status_t psa_aead_encrypt(psa_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);
Parameters
key
Identifier of the key to use for the operation. It must permit the
usage PSA_KEY_USAGE_ENCRYPT.
alg
The AEAD algorithm to compute: a value of type psa_algorithm_t
such that PSA_ALG_IS_AEAD(alg) is true.
nonce
Nonce or IV to use.
nonce_length
Size of the nonce buffer in bytes. This must be appropriate for the
selected algorithm. The default nonce size is
PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of
key.
additional_data
Additional data that will be authenticated but not encrypted.
additional_data_length
Size of additional_data in bytes.
plaintext
Data that will be authenticated and encrypted.
plaintext_length
Size of plaintext in bytes.
ciphertext
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.
IHI 0086
Page 180
1.1.2
Non-confidential
∙ PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) evaluates
to the maximum ciphertext size of any supported AEAD
encryption.
ciphertext_length
On success, the size of the output in the ciphertext buffer.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*ciphertext_length) bytes of ciphertext contain
the output.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_BUFFER_TOO_SMALL
The size of the ciphertext buffer is too small.
PSA_AEAD_ENCRYPT_OUTPUT_SIZE() or
PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE() can be used to determine a
sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not an AEAD algorithm.
∙ key is not compatible with alg.
∙ nonce_length is not valid for use with alg and key.
∙ additional_data_length or plaintext_length are too large for alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not an AEAD algorithm.
∙ key is not supported for use with alg.
∙ nonce_length is not supported for use with alg and key.
∙ additional_data_length or plaintext_length are too large for the
implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 181
1.1.2
Non-confidential
psa_aead_decrypt (function)
Process an authenticated decryption operation.
psa_status_t psa_aead_decrypt(psa_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);
Parameters
key
Identifier of the key to use for the operation. It must permit the
usage PSA_KEY_USAGE_DECRYPT.
alg
The AEAD algorithm to compute: a value of type psa_algorithm_t
such that PSA_ALG_IS_AEAD(alg) is true.
nonce
Nonce or IV to use.
nonce_length
Size of the nonce buffer in bytes. This must be appropriate for the
selected algorithm. The default nonce size is
PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of
key.
additional_data
Additional data that has been authenticated but not encrypted.
additional_data_length
Size of additional_data in bytes.
ciphertext
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
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
On success, the size of the output in the plaintext buffer.
IHI 0086
Page 182
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*plaintext_length) bytes of plaintext contain the
output.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_INVALID_SIGNATURE
The ciphertext is not authentic.
PSA_ERROR_BUFFER_TOO_SMALL
The size of the plaintext buffer is too small.
PSA_AEAD_DECRYPT_OUTPUT_SIZE() or
PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE() can be used to determine a
sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not an AEAD algorithm.
∙ key is not compatible with alg.
∙ nonce_length is not valid for use with alg and key.
∙ additional_data_length or ciphertext_length are too large for
alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not an AEAD algorithm.
∙ key is not supported for use with alg.
∙ nonce_length is not supported for use with alg and key.
∙ additional_data_length or plaintext_length are too large for the
implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
10.5.3 Multi-part AEAD operations
Warning: When decrypting using a multi-part AEAD operation, there is no guarantee that the input or
output is valid until psa_aead_verify() has returned PSA_SUCCESS.
A call to psa_aead_update() or psa_aead_update_ad() returning PSA_SUCCESS does not indicate that the
input and output is valid.
Until an application calls psa_aead_verify() and it has returned PSA_SUCCESS, the following rules apply to
input and output data from a multi-part AEAD operation:
IHI 0086
Page 183
1.1.2
Non-confidential
∙ Do not trust the input. If the application takes any action that depends on the input data, this
action will need to be undone if the input turns out to be invalid.
∙ Store the output in a confidential location. In particular, the application must not copy the output
to a memory or storage space which is shared.
∙ Do not trust the output. If the application takes any action that depends on the tentative
decrypted data, this action will need to be undone if the input turns out to be invalid.
Furthermore, if an adversary can observe that this action took place, for example, through timing,
they might be able to use this fact as an oracle to decrypt any message encrypted with the same
key.
An application that does not follow these rules might be vulnerable to maliciously constructed AEAD
input data.
psa_aead_operation_t (typedef)
The type of the state object for multi-part AEAD operations.
typedef /* implementation-defined type */ psa_aead_operation_t;
Before calling any function on an AEAD operation object, the application must initialize it by any of the
following means:
∙ Set the object to all-bits-zero, for example:
psa_aead_operation_t operation;
memset(&operation, 0, sizeof(operation));
∙ Initialize the object to logical zero values by declaring the object as static or global without an
explicit initializer, for example:
static psa_aead_operation_t operation;
∙ Initialize the object 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 object, for example:
psa_aead_operation_t operation;
operation = psa_aead_operation_init();
This is an implementation-defined type. Applications that make assumptions about the content of this
object will result in in implementation-specific behavior, and are non-portable.
IHI 0086
Page 184
1.1.2
Non-confidential
PSA_AEAD_OPERATION_INIT (macro)
This macro returns a suitable initializer for an AEAD operation object of type psa_aead_operation_t.
#define PSA_AEAD_OPERATION_INIT /* implementation-defined value */
psa_aead_operation_init (function)
Return an initial value for an AEAD operation object.
psa_aead_operation_t psa_aead_operation_init(void);
Returns: psa_aead_operation_t
psa_aead_encrypt_setup (function)
Set the key for a multi-part authenticated encryption operation.
psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t * operation,
psa_key_id_t key,
psa_algorithm_t alg);
Parameters
operation
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 permit the usage
PSA_KEY_USAGE_ENCRYPT.
alg
The AEAD algorithm: a value of type psa_algorithm_t such that
PSA_ALG_IS_AEAD(alg) is true.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation is now active.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not an AEAD algorithm.
∙ key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not an AEAD algorithm.
∙ key is not supported for use with alg.
IHI 0086
Page 185
1.1.2
Non-confidential
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The sequence of operations to encrypt a message with authentication is as follows:
1. Allocate an AEAD operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for
psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
3. Call psa_aead_encrypt_setup() to specify the algorithm and key.
4. 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.
5. Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or set the nonce. It is
recommended to use psa_aead_generate_nonce() unless the protocol being implemented requires a
specific nonce value.
6. Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted
additional authenticated data each time.
7. Call psa_aead_update() zero, one or more times, passing a fragment of the message to encrypt each
time.
8. Call psa_aead_finish().
After a successful call to psa_aead_encrypt_setup(), the operation is active, and 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().
If psa_aead_encrypt_setup() returns an error, the operation object is unchanged. If a subsequent function
call with an active operation returns an error, the operation enters an error state.
To abandon an active operation, or reset an operation in an error state, call psa_aead_abort().
See Multi-part operations on page 24.
IHI 0086
Page 186
1.1.2
Non-confidential
psa_aead_decrypt_setup (function)
Set the key for a multi-part authenticated decryption operation.
psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t * operation,
psa_key_id_t key,
psa_algorithm_t alg);
Parameters
operation
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 permit the usage
PSA_KEY_USAGE_DECRYPT.
alg
The AEAD algorithm to compute: a value of type psa_algorithm_t
such that PSA_ALG_IS_AEAD(alg) is true.
Returns: psa_status_t
PSA_SUCCESS
Success. The operation is now active.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be inactive.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not
permit the requested algorithm.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ alg is not an AEAD algorithm.
∙ key is not compatible with alg.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ alg is not supported or is not an AEAD algorithm.
∙ key is not supported for use with alg.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 187
1.1.2
Non-confidential
Description
The sequence of operations to decrypt a message with authentication is as follows:
1. Allocate an AEAD operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for
psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
3. Call psa_aead_decrypt_setup() to specify the algorithm and key.
4. 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.
5. Call psa_aead_set_nonce() with the nonce for the decryption.
6. Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted
additional authenticated data each time.
7. Call psa_aead_update() zero, one or more times, passing a fragment of the ciphertext to decrypt each
time.
8. Call psa_aead_verify().
After a successful call to psa_aead_decrypt_setup(), the operation is active, and 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().
If psa_aead_decrypt_setup() returns an error, the operation object is unchanged. If a subsequent function
call with an active operation returns an error, the operation enters an error state.
To abandon an active operation, or reset an operation in an error state, call psa_aead_abort().
See Multi-part operations on page 24.
psa_aead_set_lengths (function)
Declare the lengths of the message and additional data for AEAD.
psa_status_t psa_aead_set_lengths(psa_aead_operation_t * operation,
size_t ad_length,
size_t plaintext_length);
Parameters
operation
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.
IHI 0086
Page 188
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active, and
psa_aead_set_nonce() and psa_aead_generate_nonce() must not
have been called yet.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
ad_length or plaintext_length are too large for the chosen algorithm.
PSA_ERROR_NOT_SUPPORTED
ad_length or plaintext_length are too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
The application must call this function before calling psa_aead_set_nonce() or psa_aead_generate_nonce(), 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.
∙ 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().
psa_aead_generate_nonce (function)
Generate a random nonce for an authenticated encryption operation.
psa_status_t psa_aead_generate_nonce(psa_aead_operation_t * operation,
uint8_t * nonce,
size_t nonce_size,
size_t * nonce_length);
Parameters
operation
Active AEAD operation.
nonce
Buffer where the generated nonce is to be written.
nonce_size
Size of the nonce buffer in bytes. This must be appropriate for the
selected algorithm and key:
∙ A sufficient output size is PSA_AEAD_NONCE_LENGTH(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_NONCE_MAX_SIZE evaluates to a sufficient output size for
any supported AEAD algorithm.
IHI 0086
Page 189
1.1.2
Non-confidential
nonce_length
On success, the number of bytes of the generated nonce.
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*nonce_length) bytes of nonce contain the
generated nonce.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be an active AEAD
encryption operation, with no nonce set.
∙ The operation state is not valid: this is an algorithm which
requires psa_aead_set_lengths() to be called before setting the
nonce.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the nonce buffer is too small. PSA_AEAD_NONCE_LENGTH() or
PSA_AEAD_NONCE_MAX_SIZE can be used to determine a sufficient buffer
size.
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function generates a random nonce for the authenticated encryption operation with an appropriate
size for the chosen algorithm, key type and key size.
Most algorithms generate a default-length nonce, as returned by PSA_AEAD_NONCE_LENGTH(). Some
algorithms can return a shorter nonce from psa_aead_generate_nonce(), see the individual algorithm
descriptions for details.
The application must call psa_aead_encrypt_setup() before calling this function. If applicable for the
algorithm, the application must call psa_aead_set_lengths() 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().
psa_aead_set_nonce (function)
Set the nonce for an authenticated encryption or decryption operation.
psa_status_t psa_aead_set_nonce(psa_aead_operation_t * operation,
const uint8_t * nonce,
size_t nonce_length);
IHI 0086
Page 190
1.1.2
Non-confidential
Parameters
operation
Active AEAD operation.
nonce
Buffer containing the nonce to use.
nonce_length
Size of the nonce in bytes. This must be a valid nonce size for the
chosen algorithm. The default nonce size is
PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type and alg are
type of key and the algorithm respectively that were used to set up
the AEAD operation.
Returns: psa_status_t
PSA_SUCCESS
Success.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active, with no nonce
set.
∙ The operation state is not valid: this is an algorithm which
requires psa_aead_set_lengths() to be called before setting the
nonce.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
nonce_length is not valid for the chosen algorithm.
PSA_ERROR_NOT_SUPPORTED
nonce_length is not supported for use with the operation’s algorithm
and key.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
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 applicable for the algorithm, the application must call psa_aead_set_lengths() 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, psa_aead_generate_nonce() is recommended instead of using this function, unless
implementing a protocol that requires a non-random IV.
IHI 0086
Page 191
1.1.2
Non-confidential
psa_aead_update_ad (function)
Pass additional data to an active AEAD operation.
psa_status_t psa_aead_update_ad(psa_aead_operation_t * operation,
const uint8_t * input,
size_t input_length);
Parameters
operation
Active AEAD operation.
input
Buffer containing the fragment of additional data.
input_length
Size of the input buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success.
Warning: When decrypting, do not trust the additional data until
psa_aead_verify() succeeds.
See the detailed warning.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ 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.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_ARGUMENT
Excess additional data: the total input length to psa_aead_update_ad()
is greater than the additional data length that was previously
specified with psa_aead_set_lengths(), or is too large for the chosen
AEAD algorithm.
PSA_ERROR_NOT_SUPPORTED
The total additional data length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
IHI 0086
Page 192
1.1.2
Non-confidential
Description
Additional data is authenticated, but not encrypted.
This function can be called multiple times to pass successive fragments of the additional data. This
function must not be called after passing data to encrypt or decrypt with psa_aead_update().
The following must occur before calling this function:
1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2. 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().
psa_aead_update (function)
Encrypt or decrypt a message fragment in an active AEAD operation.
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);
Parameters
operation
Active AEAD operation.
input
Buffer containing the message fragment to encrypt or decrypt.
input_length
Size of the input buffer in bytes.
output
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
On success, the number of bytes that make up the returned output.
IHI 0086
Page 193
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*output_length) of output contains the output
data.
Warning: When decrypting, do not use the output until
psa_aead_verify() succeeds.
See the detailed warning.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be active, have a nonce
set, and have lengths set if required by the algorithm.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the output buffer is too small.
PSA_AEAD_UPDATE_OUTPUT_SIZE() or PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE()
can be used to determine a sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ Incomplete additional data: the total length of input to
psa_aead_update_ad() is less than the additional data length that
was previously specified with psa_aead_set_lengths().
∙ Excess input data: the total length of input to psa_aead_update()
is greater than the plaintext length that was previously specified
with psa_aead_set_lengths(), or is too large for the specific
AEAD algorithm.
PSA_ERROR_NOT_SUPPORTED
The total input length is too large for the implementation.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The following must occur before calling this function:
1. 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.
2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
3. 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().
IHI 0086
Page 194
1.1.2
Non-confidential
Note:
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 might delay the end of the corresponding output until a subsequent call to psa_aead_update()
provides sufficient input, or a subsequent call to psa_aead_finish() or psa_aead_verify() indicates the
end of the input. The amount of data that can be delayed in this way is bounded by the associated
output size macro: PSA_AEAD_UPDATE_OUTPUT_SIZE(), PSA_AEAD_FINISH_OUTPUT_SIZE(), or
PSA_AEAD_VERIFY_OUTPUT_SIZE().
psa_aead_finish (function)
Finish encrypting a message in an AEAD operation.
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);
Parameters
operation
Active AEAD operation.
ciphertext
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
On success, the number of bytes of returned ciphertext.
tag
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
On success, the number of bytes that make up the returned tag.
IHI 0086
Page 195
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. The first (*tag_length) bytes of tag contain the
authentication tag.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be an active encryption
operation with a nonce set.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
The size of the ciphertext or tag buffer is too small.
PSA_AEAD_FINISH_OUTPUT_SIZE() or PSA_AEAD_FINISH_OUTPUT_MAX_SIZE
can be used to determine the required ciphertext buffer size.
PSA_AEAD_TAG_LENGTH() or PSA_AEAD_TAG_MAX_SIZE can be used to
determine the required tag buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ Incomplete additional data: the total length of input to
psa_aead_update_ad() is less than the additional data length that
was previously specified with psa_aead_set_lengths().
∙ Incomplete plaintext: the total length of input to
psa_aead_update() 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_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
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().
IHI 0086
Page 196
1.1.2
Non-confidential
psa_aead_verify (function)
Finish authenticating and decrypting a message in an AEAD operation.
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);
Parameters
operation
Active AEAD operation.
plaintext
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
On success, the number of bytes of returned plaintext.
tag
Buffer containing the expected authentication tag.
tag_length
Size of the tag buffer in bytes.
Returns: psa_status_t
PSA_SUCCESS
Success. For a decryption operation, it is now safe to use the
additional data and the plaintext output.
PSA_ERROR_BAD_STATE
The following conditions can result in this error:
∙ The operation state is not valid: it must be an active decryption
operation with a nonce set.
∙ The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_SIGNATURE
The calculated authentication tag does not match the value in tag.
PSA_ERROR_BUFFER_TOO_SMALL
The size of the plaintext buffer is too small.
PSA_AEAD_VERIFY_OUTPUT_SIZE() or PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE
can be used to determine a sufficient buffer size.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ Incomplete additional data: the total length of input to
psa_aead_update_ad() is less than the additional data length that
was previously specified with psa_aead_set_lengths().
∙ Incomplete ciphertext: the total length of input to
psa_aead_update() is less than the plaintext length that was
IHI 0086
Page 197
1.1.2
Non-confidential
previously specified with psa_aead_set_lengths().
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
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().
Implementation note
Implementations must make the best effort to ensure that the comparison between the actual tag
and the expected tag is performed in constant time.
psa_aead_abort (function)
Abort an AEAD operation.
psa_status_t psa_aead_abort(psa_aead_operation_t * operation);
Parameters
operation
Initialized AEAD operation.
IHI 0086
Page 198
1.1.2
Non-confidential
|
||
|
|
|