10.7. Asymmetric signature
There are two pairs of singlepart functions for asymmetric signature:
The signature and verification functions
psa_sign_message()
andpsa_verify_message()
take a message as one of their inputs and perform a hashandsign algorithm.The functions
psa_sign_hash()
andpsa_verify_hash()
take a message hash as one of their inputs. This is useful for signing precomputed hashes, or for implementing hashandsign using a multipart hash operation before signing the resulting hash. To determine which hash algorithm to use, call the macroPSA_ALG_GET_HASH()
on the corresponding signature algorithm.Some hashandsign algorithms add padding to the message hash before completing the signing operation. The format of the padding that is used depends on the algorithm used to construct the signature.
10.7.1. Asymmetric signature algorithms
PSA_ALG_RSA_PKCS1V15_SIGN
(macro)
The RSA PKCS#1 v1.5 message signature scheme, with hashing.
#define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) /* specificationdefined value */
Parameters

hash_alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
hash_alg
)
is true. This includesPSA_ALG_ANY_HASH
when specifying the algorithm in a key policy.
Returns
The corresponding RSA PKCS#1 v1.5 signature algorithm.
Unspecified if hash_alg
is not a supported hash algorithm.
Description
This algorithm can be used with both the message and hash signature functions.
This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] §8.2 under the name RSASSAPKCS1v1_5.
When used with psa_sign_hash()
or psa_verify_hash()
, the provided hash
parameter is used as H from step 2 onwards in the message encoding algorithm EMSAPKCS1V1_5ENCODE()
in [RFC8017] §9.2. H is usually the message digest, using the hash_alg
hash algorithm.
Compatible key types
PSA_KEY_TYPE_RSA_PUBLIC_KEY
(signature verification only)PSA_ALG_RSA_PKCS1V15_SIGN_RAW
(macro)
The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.
#define PSA_ALG_RSA_PKCS1V15_SIGN_RAW ((psa_algorithm_t) 0x06000200)
This algorithm can be only used with the psa_sign_hash()
and psa_verify_hash()
functions.
This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] §8.2 under the name RSASSAPKCS1v1_5.
The hash
parameter to psa_sign_hash()
or psa_verify_hash()
is used as T from step 3 onwards in the message encoding algorithm EMSAPKCS1V1_5ENCODE()
in [RFC8017] §9.2. T is the DER encoding of the DigestInfo structure normally produced by step 2 in the message encoding algorithm.
The wildcard key policy PSA_ALG_RSA_PKCS1V15_SIGN
(
PSA_ALG_ANY_HASH
)
also permits a key to be used with the PSA_ALG_RSA_PKCS1V15_SIGN_RAW
signature algorithm.
Compatible key types
PSA_KEY_TYPE_RSA_PUBLIC_KEY
(signature verification only)PSA_ALG_RSA_PSS
(macro)
The RSA PSS message signature scheme, with hashing.
#define PSA_ALG_RSA_PSS(hash_alg) /* specificationdefined value */
Parameters

hash_alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
hash_alg
)
is true. This includesPSA_ALG_ANY_HASH
when specifying the algorithm in a key policy.
Returns
The corresponding RSA PSS signature algorithm.
Unspecified if hash_alg
is not a supported hash algorithm.
Description
This algorithm can be used with both the message and hash signature functions.
This algorithm is randomized: each invocation returns a different, equally valid signature.
This is the signature scheme defined by [RFC8017] §8.1 under the name RSASSAPSS, with the following options:
 The mask generation function is MGF1 defined by [RFC8017] Appendix B.
 When creating a signature, the salt length is equal to the length of the hash, or the largest possible salt length for the algorithm and key size if that is smaller than the hash length.
 When verifying a signature, the salt length must be equal to the length of the hash, or the largest possible salt length for the algorithm and key size if that is smaller than the hash length.
 The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.
Note
The PSA_ALG_RSA_PSS_ANY_SALT()
algorithm is equivalent to PSA_ALG_RSA_PSS()
when creating a signature, but permits any salt length when verifying a signature.
Compatible key types
PSA_KEY_TYPE_RSA_PUBLIC_KEY
(signature verification only)PSA_ALG_RSA_PSS_ANY_SALT
(macro)
The RSA PSS message signature scheme, with hashing. This variant permits any salt length for signature verification.
#define PSA_ALG_RSA_PSS_ANY_SALT(hash_alg) /* specificationdefined value */
Parameters

hash_alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
hash_alg
)
is true. This includesPSA_ALG_ANY_HASH
when specifying the algorithm in a key policy.
Returns
The corresponding RSA PSS signature algorithm.
Unspecified if hash_alg
is not a supported hash algorithm.
Description
This algorithm can be used with both the message and hash signature functions.
This algorithm is randomized: each invocation returns a different, equally valid signature.
This is the signature scheme defined by [RFC8017] §8.1 under the name RSASSAPSS, with the following options:
 The mask generation function is MGF1 defined by [RFC8017] Appendix B.
 When creating a signature, the salt length is equal to the length of the hash, or the largest possible salt length for the algorithm and key size if that is smaller than the hash length.
 When verifying a signature, any salt length permitted by the RSASSAPSS signature algorithm is accepted.
 The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.
Note
The PSA_ALG_RSA_PSS()
algorithm is equivalent to PSA_ALG_RSA_PSS_ANY_SALT()
when creating a signature, but is strict about the permitted salt length when verifying a signature.
Compatible key types
PSA_KEY_TYPE_RSA_PUBLIC_KEY
(signature verification only)PSA_ALG_ECDSA
(macro)
The randomized ECDSA signature scheme, with hashing.
#define PSA_ALG_ECDSA(hash_alg) /* specificationdefined value */
Parameters

hash_alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
hash_alg
)
is true. This includesPSA_ALG_ANY_HASH
when specifying the algorithm in a key policy.
Returns
The corresponding randomized ECDSA signature algorithm.
Unspecified if hash_alg
is not a supported hash algorithm.
Description
This algorithm can be used with both the message and hash signature functions.
This algorithm is randomized: each invocation returns a different, equally valid signature.
Note
When based on the same hash algorithm, the verification operations for PSA_ALG_ECDSA
and PSA_ALG_DETERMINISTIC_ECDSA
are identical. A signature created using PSA_ALG_ECDSA
can be verified with the same key using either PSA_ALG_ECDSA
or PSA_ALG_DETERMINISTIC_ECDSA
. Similarly, a signature created using PSA_ALG_DETERMINISTIC_ECDSA
can be verified with the same key using either PSA_ALG_ECDSA
or PSA_ALG_DETERMINISTIC_ECDSA
.
In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.
This signature scheme is defined by SEC 1: Elliptic Curve Cryptography [SEC1], and also by Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA) [X962], with a random permessage secret number k.
The representation of the signature as a byte string consists of the concatenation of the signature values r and s. Each of r and s is encoded as an Noctet string, where N is the length of the base point of the curve in octets. Each value is represented in bigendian order, with the most significant octet first.
Compatible key types
where family
is a Weierstrass Elliptic curve family. That is, one of the following values:
PSA_ECC_FAMILY_SECT_XX
PSA_ECC_FAMILY_SECP_XX
PSA_ECC_FAMILY_FRP
PSA_ECC_FAMILY_BRAINPOOL_P_R1
PSA_ALG_ECDSA_ANY
(macro)
The randomized ECDSA signature scheme, without hashing.
#define PSA_ALG_ECDSA_ANY ((psa_algorithm_t) 0x06000600)
This algorithm can be only used with the psa_sign_hash()
and psa_verify_hash()
functions.
This algorithm is randomized: each invocation returns a different, equally valid signature.
This is the same signature scheme as PSA_ALG_ECDSA()
, but without specifying a hash algorithm, and skipping the message hashing operation.
This algorithm is only recommended to sign or verify a sequence of bytes that are an alreadycalculated hash. Note that the input is padded with zeros on the left or truncated on the right as required to fit the curve size.
Compatible key types
where family
is a Weierstrass Elliptic curve family. That is, one of the following values:
PSA_ECC_FAMILY_SECT_XX
PSA_ECC_FAMILY_SECP_XX
PSA_ECC_FAMILY_FRP
PSA_ECC_FAMILY_BRAINPOOL_P_R1
PSA_ALG_DETERMINISTIC_ECDSA
(macro)
Deterministic ECDSA signature scheme, with hashing.
#define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) /* specificationdefined value */
Parameters

hash_alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
hash_alg
)
is true. This includesPSA_ALG_ANY_HASH
when specifying the algorithm in a key policy.
Returns
The corresponding deterministic ECDSA signature algorithm.
Unspecified if hash_alg
is not a supported hash algorithm.
Description
This algorithm can be used with both the message and hash signature functions.
This is the deterministic ECDSA signature scheme defined by Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) [RFC6979].
The representation of a signature is the same as with PSA_ALG_ECDSA()
.
Note
When based on the same hash algorithm, the verification operations for PSA_ALG_ECDSA
and PSA_ALG_DETERMINISTIC_ECDSA
are identical. A signature created using PSA_ALG_ECDSA
can be verified with the same key using either PSA_ALG_ECDSA
or PSA_ALG_DETERMINISTIC_ECDSA
. Similarly, a signature created using PSA_ALG_DETERMINISTIC_ECDSA
can be verified with the same key using either PSA_ALG_ECDSA
or PSA_ALG_DETERMINISTIC_ECDSA
.
In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.
Compatible key types
where family
is a Weierstrass Elliptic curve family. That is, one of the following values:
PSA_ECC_FAMILY_SECT_XX
PSA_ECC_FAMILY_SECP_XX
PSA_ECC_FAMILY_FRP
PSA_ECC_FAMILY_BRAINPOOL_P_R1
PSA_ALG_PURE_EDDSA
(macro)
Edwardscurve digital signature algorithm without prehashing (PureEdDSA), using standard parameters.
#define PSA_ALG_PURE_EDDSA ((psa_algorithm_t) 0x06000800)
This algorithm can be only used with the psa_sign_message()
and psa_verify_message()
functions.
This is the PureEdDSA digital signature algorithm defined by EdwardsCurve Digital Signature Algorithm (EdDSA) [RFC8032], using standard parameters.
PureEdDSA requires an elliptic curve key on a twisted Edwards curve. The following curves are supported:
 Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64byte string: the concatenation of R and S as defined by [RFC8032] §5.1.6.
 Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output signature is a 114byte string: the concatenation of R and S as defined by [RFC8032] §5.2.6.
Note
Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. A future version of this specification may add suitable functions and extend this algorithm to support contexts.
Note
To sign or verify the precomputed hash of a message using EdDSA, the HashEdDSA algorithms (PSA_ALG_ED25519PH
and PSA_ALG_ED448PH
) can be used with psa_sign_hash()
and psa_verify_hash()
.
The signature produced by HashEdDSA is distinct from that produced by PureEdDSA.
Compatible key types
PSA_ALG_ED25519PH
(macro)
Edwardscurve digital signature algorithm with prehashing (HashEdDSA), using the Edwards25519 curve.
#define PSA_ALG_ED25519PH ((psa_algorithm_t) 0x0600090B)
This algorithm can be used with both the message and hash signature functions.
This computes the Ed25519ph algorithm as specified in EdwardsCurve Digital Signature Algorithm (EdDSA) [RFC8032] §5.1, and requires an Edwards25519 curve key. An empty string is used as the context. The prehash function is SHA512.
Implementation note
When used with psa_sign_hash()
or psa_verify_hash()
, the hash
parameter to the call should be used as PH(M)
in the algorithms defined in [RFC8032] §5.1.
Usage
This is a hashandsign algorithm. To calculate a signature, use one of the following approaches:
 Call
psa_sign_message()
with the message.  Calculate the SHA512 hash of the message with
psa_hash_compute()
, or with a multipart hash operation, using the hash algorithmPSA_ALG_SHA_512
. Then sign the calculated hash withpsa_sign_hash()
.
Verifying a signature is similar, using psa_verify_message()
or psa_verify_hash()
instead of the signature function.
Compatible key types
PSA_ALG_ED448PH
(macro)
Edwardscurve digital signature algorithm with prehashing (HashEdDSA), using the Edwards448 curve.
#define PSA_ALG_ED448PH ((psa_algorithm_t) 0x06000915)
This algorithm can be used with both the message and hash signature functions.
This computes the Ed448ph algorithm as specified in EdwardsCurve Digital Signature Algorithm (EdDSA) [RFC8032] §5.2, and requires an Edwards448 curve key. An empty string is used as the context. The prehash function is the first 64 bytes of the output from SHAKE256.
Implementation note
When used with psa_sign_hash()
or psa_verify_hash()
, the hash
parameter to the call should be used as PH(M)
in the algorithms defined in [RFC8032] §5.2.
Usage
This is a hashandsign algorithm. To calculate a signature, use one of the following approaches:
 Call
psa_sign_message()
with the message.  Calculate the first 64 bytes of the SHAKE256 output of the message with
psa_hash_compute()
, or with a multipart hash operation, using the hash algorithmPSA_ALG_SHAKE256_512
. Then sign the calculated hash withpsa_sign_hash()
.
Verifying a signature is similar, using psa_verify_message()
or psa_verify_hash()
instead of the signature function.
Compatible key types
10.7.2. Asymmetric signature functions
psa_sign_message
(function)
Sign a message with a private key. For hashandsign algorithms, this includes the hashing step.
psa_status_t psa_sign_message(psa_key_id_t key, psa_algorithm_t alg, const uint8_t * input, size_t input_length, uint8_t * signature, size_t signature_size, size_t * signature_length);
Parameters

key
 Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage
PSA_KEY_USAGE_SIGN_MESSAGE
. 
alg
 An asymmetric signature algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_SIGN_MESSAGE
(
alg
)
is true. 
input
 The input message to sign.

input_length
 Size of the
input
buffer in bytes. 
signature
 Buffer where the signature is to be written.

signature_size
Size of the
signature
buffer in bytes. This must be appropriate for the selected algorithm and key: The required signature size is
PSA_SIGN_OUTPUT_SIZE
(
key_type
,
key_bits
,
alg
)
wherekey_type
andkey_bits
are the type and bitsize respectively ofkey
. PSA_SIGNATURE_MAX_SIZE
evaluates to the maximum signature size of any supported signature algorithm.
 The required signature size is

signature_length
 On success, the number of bytes that make up the returned signature value.
Returns: psa_status_t

PSA_SUCCESS
 Success.
The first
(*signature_length)
bytes ofsignature
contain the signature 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
signature
buffer is too small.PSA_SIGN_OUTPUT_SIZE()
orPSA_SIGNATURE_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 asymmetric signature algorithm.key
is not an asymmetric key pair, that is compatible withalg
.input_length
is too large for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
alg
is not supported or is not an asymmetric signature algorithm.key
is not supported for use withalg
.input_length
is too large for the implementation.

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
Note
To perform a multipart hashandsign signature algorithm, first use a multipart hash operation and then pass the resulting hash to psa_sign_hash()
. PSA_ALG_GET_HASH
(
alg
)
can be used to determine the hash algorithm to use.
psa_verify_message
(function)
Verify the signature of a message with a public key. For hashandsign algorithms, this includes the hashing step.
psa_status_t psa_verify_message(psa_key_id_t key, psa_algorithm_t alg, const uint8_t * input, size_t input_length, const uint8_t * signature, size_t signature_length);
Parameters

key
 Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage
PSA_KEY_USAGE_VERIFY_MESSAGE
. 
alg
 An asymmetric signature algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_SIGN_MESSAGE
(
alg
)
is true. 
input
 The message whose signature is to be verified.

input_length
 Size of the
input
buffer in bytes. 
signature
 Buffer containing the signature to verify.

signature_length
 Size of the
signature
buffer in bytes.
Returns: psa_status_t

PSA_SUCCESS
 Success. The signature is valid.

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
signature
is not the result of signing theinput
message with algorithmalg
using the private key corresponding tokey
.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
alg
is not an asymmetric signature algorithm.key
is not a public key or an asymmetric key pair, that is compatible withalg
.input_length
is too large for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
alg
is not supported or is not an asymmetric signature algorithm.key
is not supported for use withalg
.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
Note
To perform a multipart hashandsign signature verification algorithm, first use a multipart hash operation to hash the message and then pass the resulting hash to psa_verify_hash()
. PSA_ALG_GET_HASH
(
alg
)
can be used to determine the hash algorithm to use.
psa_sign_hash
(function)
Sign an alreadycalculated hash with a private key.
psa_status_t psa_sign_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t * hash, size_t hash_length, uint8_t * signature, size_t signature_size, size_t * signature_length);
Parameters

key
 Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage
PSA_KEY_USAGE_SIGN_HASH
. 
alg
 An asymmetric signature algorithm that separates the hash and sign operations: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_SIGN_HASH
(
alg
)
is true. 
hash
 The input to sign. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.

hash_length
 Size of the
hash
buffer in bytes. 
signature
 Buffer where the signature is to be written.

signature_size
Size of the
signature
buffer in bytes. This must be appropriate for the selected algorithm and key: The required signature size is
PSA_SIGN_OUTPUT_SIZE
(
key_type
,
key_bits
,
alg
)
wherekey_type
andkey_bits
are the type and bitsize respectively ofkey
. PSA_SIGNATURE_MAX_SIZE
evaluates to the maximum signature size of any supported signature algorithm.
 The required signature size is

signature_length
 On success, the number of bytes that make up the returned signature value.
Returns: psa_status_t

PSA_SUCCESS
 Success.
The first
(*signature_length)
bytes ofsignature
contain the signature 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_HASH
flag, or it does not permit the requested algorithm. 
PSA_ERROR_BUFFER_TOO_SMALL
 The size of the
signature
buffer is too small.PSA_SIGN_OUTPUT_SIZE()
orPSA_SIGNATURE_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 asymmetric signature algorithm.key
is not an asymmetric key pair, that is compatible withalg
.hash_length
is not valid for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
alg
is not supported or is not an asymmetric signature algorithm.key
is not supported for use withalg
.

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
With most signature mechanisms that follow the hashandsign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.
Some hashandsign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: PSA_ALG_RSA_PKCS1V15_SIGN_RAW
.
Note
To perform a hashandsign signature algorithm, the hash must be calculated before passing it to this function. This can be done by calling psa_hash_compute()
or with a multipart hash operation. The correct hash algorithm to use can be determined using PSA_ALG_GET_HASH()
.
Alternatively, to hash and sign a message in a single call, use psa_sign_message()
.
psa_verify_hash
(function)
Verify the signature of a hash or short message using a public key.
psa_status_t psa_verify_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t * hash, size_t hash_length, const uint8_t * signature, size_t signature_length);
Parameters

key
 Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage
PSA_KEY_USAGE_VERIFY_HASH
. 
alg
 An asymmetric signature algorithm that separates the hash and sign operations: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_SIGN_HASH
(
alg
)
is true. 
hash
 The input whose signature is to be verified. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.

hash_length
 Size of the
hash
buffer in bytes. 
signature
 Buffer containing the signature to verify.

signature_length
 Size of the
signature
buffer in bytes.
Returns: psa_status_t

PSA_SUCCESS
 Success. The signature is valid.

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_HASH
flag, or it does not permit the requested algorithm. 
PSA_ERROR_INVALID_SIGNATURE
signature
is not the result of signinghash
with algorithmalg
using the private key corresponding tokey
.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
alg
is not an asymmetric signature algorithm.key
is not a public key or an asymmetric key pair, that is compatible withalg
.hash_length
is not valid for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
alg
is not supported or is not an asymmetric signature algorithm.key
is not supported for use withalg
.

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
With most signature mechanisms that follow the hashandsign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.
Some hashandsign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: PSA_ALG_RSA_PKCS1V15_SIGN_RAW
.
Note
To perform a hashandsign verification algorithm, the hash must be calculated before passing it to this function. This can be done by calling psa_hash_compute()
or with a multipart hash operation. The correct hash algorithm to use can be determined using PSA_ALG_GET_HASH()
.
Alternatively, to hash and verify a message in a single call, use psa_verify_message()
.
10.7.3. Support macros
PSA_ALG_IS_SIGN_MESSAGE
(macro)
Whether the specified algorithm is a signature algorithm that can be used with psa_sign_message()
and psa_verify_message()
.
#define PSA_ALG_IS_SIGN_MESSAGE(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is a signature algorithm that can be used to sign a message. 0
if alg
is a signature algorithm that can only be used to sign an alreadycalculated hash. 0
if alg
is not a signature algorithm. This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
PSA_ALG_IS_SIGN_HASH
(macro)
Whether the specified algorithm is a signature algorithm that can be used with psa_sign_hash()
and psa_verify_hash()
.
#define PSA_ALG_IS_SIGN_HASH(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is a signature algorithm that can be used to sign a hash. 0
if alg
is a signature algorithm that can only be used to sign a message. 0
if alg
is not a signature algorithm. This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
Description
This includes all algorithms such that PSA_ALG_IS_HASH_AND_SIGN()
is true, as well as signature algorithms for which the input to psa_sign_hash()
or psa_verify_hash()
is not directly a hash, such as PSA_ALG_IS_RSA_PKCS1V15_SIGN
.
PSA_ALG_IS_RSA_PKCS1V15_SIGN
(macro)
Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm.
#define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is an RSA PKCS#1 v1.5 signature algorithm, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
PSA_ALG_IS_RSA_PSS
(macro)
Whether the specified algorithm is an RSA PSS signature algorithm.
#define PSA_ALG_IS_RSA_PSS(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is an RSA PSS signature algorithm, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
Description
This macro returns 1
for algorithms constructed using either PSA_ALG_RSA_PSS()
or PSA_ALG_RSA_PSS_ANY_SALT()
.
PSA_ALG_IS_RSA_PSS_ANY_SALT
(macro)
Whether the specified algorithm is an RSA PSS signature algorithm that permits any salt length.
#define PSA_ALG_IS_RSA_PSS_ANY_SALT(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is an RSA PSS signature algorithm that permits any salt length, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
Description
An RSA PSS signature algorithm that permits any salt length is constructed using PSA_ALG_RSA_PSS_ANY_SALT()
.
See also PSA_ALG_IS_RSA_PSS()
and PSA_ALG_IS_RSA_PSS_STANDARD_SALT()
.
PSA_ALG_IS_RSA_PSS_STANDARD_SALT
(macro)
Whether the specified algorithm is an RSA PSS signature algorithm that requires the standard salt length.
#define PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is an RSA PSS signature algorithm that requires the standard salt length, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
Description
An RSA PSS signature algorithm that requires the standard salt length is constructed using PSA_ALG_RSA_PSS()
.
See also PSA_ALG_IS_RSA_PSS()
and PSA_ALG_IS_RSA_PSS_ANY_SALT()
.
PSA_ALG_IS_ECDSA
(macro)
Whether the specified algorithm is ECDSA.
#define PSA_ALG_IS_ECDSA(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is an ECDSA algorithm, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
PSA_ALG_IS_DETERMINISTIC_ECDSA
(macro)
Whether the specified algorithm is deterministic ECDSA.
#define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is a deterministic ECDSA algorithm, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
Description
See also PSA_ALG_IS_ECDSA()
and PSA_ALG_IS_RANDOMIZED_ECDSA()
.
PSA_ALG_IS_RANDOMIZED_ECDSA
(macro)
Whether the specified algorithm is randomized ECDSA.
#define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is a randomized ECDSA algorithm, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
Description
See also PSA_ALG_IS_ECDSA()
and PSA_ALG_IS_DETERMINISTIC_ECDSA()
.
PSA_ALG_IS_HASH_EDDSA
(macro)
Whether the specified algorithm is HashEdDSA.
#define PSA_ALG_IS_HASH_EDDSA(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is a HashEdDSA algorithm, 0
otherwise.
This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
PSA_ALG_IS_HASH_AND_SIGN
(macro)
Whether the specified algorithm is a hashandsign algorithm that signs exactly the hash value.
#define PSA_ALG_IS_HASH_AND_SIGN(alg) /* specificationdefined value */
Parameters

alg
 An algorithm identifier: a value of type
psa_algorithm_t
.
Returns
1
if alg
is a hashandsign algorithm that signs exactly the hash value, 0
otherwise. This macro can return either 0
or 1
if alg
is not a supported algorithm identifier.
A wildcard signature algorithm policy, using PSA_ALG_ANY_HASH
, returns the same value as the signature algorithm parameterised with a valid hash algorithm.
Description
This macro identifies algorithms that can be used with psa_sign_hash()
that use the exact message hash value as an input the signature operation. For example, if PSA_ALG_IS_HASH_AND_SIGN
(
alg
)
is true, the following call sequence is equivalent to psa_sign_message
(
key
,
alg
,
msg
,
msg_len
, ...)
:
psa_hash_operation_t op = {0}; uint8_t hash[PSA_HASH_MAX_SIZE]; size_t hash_len; psa_hash_setup(&op, PSA_ALG_GET_HASH(alg)); psa_hash_update(&op, msg, msg_len); psa_hash_finish(&op, hash, sizeof(hash), &hash_len); psa_sign_hash(key, alg, hash, hash_len, ...);
This excludes hashandsign algorithms that require a encoded or modified hash for the signature step in the algorithm, such as PSA_ALG_RSA_PKCS1V15_SIGN_RAW
. For such algorithms, PSA_ALG_IS_SIGN_HASH()
is true but PSA_ALG_IS_HASH_AND_SIGN()
is false.
PSA_ALG_ANY_HASH
(macro)
When setting a hashandsign algorithm in a key policy, permit any hash algorithm.
#define PSA_ALG_ANY_HASH ((psa_algorithm_t)0x020000ff)
This value can be used to form the permitted algorithm attribute of a key policy for a signature algorithm that is parametrized by a hash. A key with this policy can then be used to perform operations using the same signature algorithm parametrized with any supported hash.
A signature algorithm created using this macro is a wildcard algorithm, and PSA_ALG_IS_WILDCARD()
will return true.
This value must not be used to build other algorithms that are parametrized over a hash. For any valid use of this macro to build an algorithm alg
, PSA_ALG_IS_HASH_AND_SIGN
(
alg
)
is true.
This value must not be used to build an algorithm specification to perform an operation. It is only valid for setting the permitted algorithm in a key policy.
Usage
For example, suppose that PSA_xxx_SIGNATURE
is one of the following macros:
PSA_ALG_RSA_PKCS1V15_SIGN
PSA_ALG_RSA_PSS
PSA_ALG_RSA_PSS_ANY_SALT
PSA_ALG_ECDSA
PSA_ALG_DETERMINISTIC_ECDSA
The following sequence of operations shows how PSA_ALG_ANY_HASH
can be used in a key policy:
Set the key usage flags using
PSA_ALG_ANY_HASH
, for example:psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_MESSAGE); // or VERIFY_MESSAGE psa_set_key_algorithm(&attributes, PSA_xxx_SIGNATURE(PSA_ALG_ANY_HASH));
Import or generate key material.
Call
psa_sign_message()
orpsa_verify_message()
, passing an algorithm built fromPSA_xxx_SIGNATURE
and a specific hash. Each call to sign or verify a message can use a different hash algorithm.psa_sign_message(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...); psa_sign_message(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...); psa_sign_message(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...);
PSA_SIGN_OUTPUT_SIZE
(macro)
Sufficient signature buffer size for psa_sign_message()
and psa_sign_hash()
.
#define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \ /* implementationdefined value */
Parameters

key_type
 An asymmetric key type. This can be a key pair type or a public key type.

key_bits
 The size of the key in bits.

alg
 The signature algorithm.
Returns
A sufficient signature buffer size for the specified asymmetric signature algorithm and key parameters. An implementation can return either 0
or a correct size for an asymmetric signature algorithm and key parameters that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified.
Description
If the size of the signature buffer is at least this large, it is guaranteed that psa_sign_message()
and psa_sign_hash()
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_SIGNATURE_MAX_SIZE
.
PSA_SIGNATURE_MAX_SIZE
(macro)
A sufficient signature buffer size for psa_sign_message()
and psa_sign_hash()
, for any of the supported key types and asymmetric signature algorithms.
#define PSA_SIGNATURE_MAX_SIZE /* implementationdefined value */
If the size of the signature buffer is at least this large, it is guaranteed that psa_sign_message()
and psa_sign_hash()
will not fail due to an insufficient buffer size.
See also PSA_SIGN_OUTPUT_SIZE()
.