10.9 Asymmetric signature

An asymmetric signature algorithm provides two functions:

  • Sign: Calculate a message signature using a private, or secret, key.

  • Verify: Check that a signature matches a message using a public key.

Successful verification indicates that the message signature was calculated using the private key that is associated with the public key.

In the Crypto API, an asymmetric-sign function requires an asymmetric key pair; and an asymmetric-verify function requires an asymmetric public key or key pair.

Signature schemes

The Crypto API supports the following signature schemes:

Types of signature algorithm

There are three categories of asymmetric signature algorithm in the Crypto API:

  • Hash-and-sign algorithms, that have two distinct phases:

    • Calculate a hash of the message

    • Calculate a signature over the hash

    For these algorithms, the asymmetric signature API allows applications to either calculate the full message signature, or calculate the signature of a pre-computed hash. For example, this enables the application to use a multi-part hash operation to calculate the hash of a large message, prior to calculating or verifying a signature on the calculated hash.

    The following algorithms are in this category:

    PSA_ALG_RSA_PKCS1V15_SIGN
    PSA_ALG_RSA_PSS
    PSA_ALG_RSA_PSS_ANY_SALT
    PSA_ALG_ECDSA
    PSA_ALG_DETERMINISTIC_ECDSA
    PSA_ALG_ED25519PH
    PSA_ALG_ED448PH

  • Message signature algorithms that do not separate the message processing from the signature calculations. This approach can provide better security against certain types of attack.

    For these algorithms, it is not possible to inject a pre-computed hash into the middle of the algorithm. An application can choose to calculate a message hash, and sign that instead of the message — but this is not functionally equivalent to signing the message, and eliminates the security benefits of signing the message directly.

    Some of these algorithms still permit the signature of a large message to be calculated, or verified, by providing the message data in fragments. This is possible when the algorithm only processes the message data once. See the individual algorithm descriptions for details.

    The following algorithms are in this category:

    PSA_ALG_PURE_EDDSA
    PSA_ALG_EDDSA_CTX

  • Specialized signature algorithms, that use part of a standard signature algorithm within a specific protocol. It is recommended that these algorithms are only used for that purpose, with inputs as specified by the higher-level protocol. See the individual algorithm descriptions for details on their usage.

    The following algorithms are in this category:

    PSA_ALG_RSA_PKCS1V15_SIGN_RAW
    PSA_ALG_ECDSA_ANY

Signature functions

The Crypto API provides several functions for calculating and verifying signatures:

  • The single-part signature and verification functions, psa_sign_message() and psa_verify_message(), take a message as one of their inputs, and perform the sign or verify algorithm.

    These functions can be used on any hash-and-sign, or message signature, algorithms. See also PSA_ALG_IS_SIGN_MESSAGE().

  • The single-part functions, psa_sign_hash() and psa_verify_hash(), typically take a message hash as one of their inputs, and perform the sign or verify algorithm.

    These functions can be used on any hash-and-sign signature algorithm. It is recommended that the input to these functions is a hash, computed using the corresponding hash algorithm. To determine which hash algorithm to use, the macro PSA_ALG_GET_HASH() can be called on the signature algorithm identifier.

    These functions can also be used on the specialized signature algorithms, with a hash or encoded-hash as input. See also PSA_ALG_IS_SIGN_HASH().

  • Many modern signature algorithms have been designed to also accept a context parameter to provide domain separation. Version 1.4 of the Crypto API introduced four new functions that accept contexts: psa_sign_message_with_context(), psa_sign_hash_with_context(), psa_verify_message_with_context(), and psa_verify_hash_with_context().

    If called with a zero-length context, these functions produce the same signature as the associated function without a context parameter.

    Note

    If a signature scheme treats the absence of a context parameter differently to a zero-length context, the Crypto API defines distinct algorithm identifiers for the two variants. For example, when using a 255-bit key with EdDSA, PSA_ALG_PURE_EDDSA implements Ed25519 (without a context) and PSA_ALG_EDDSA_CTX implements Ed25519ctx (with a context, which can be zero-length). See EdDSA signature algorithms.

    It is an error to provide a non-zero-length context with an algorithm that does not accept contexts.

    Code written to be cryptographically agile can use the new functions, provided it guards against providing a non-zero-length context with an algorithm that does not support them.

    The PSA_ALG_SIGN_SUPPORTS_CONTEXT() macro can be used to determine if the implementation of an algorithm supports the use of non-zero-length contexts.

See Asymmetric signature functions.

10.9.1 RSA 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) /* 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. This includes PSA_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 hash-and-sign signature algorithm can be used with both the message and hash signature functions. RSA PKCS#1 v1.5 does not have a context parameter. However, the sign or verify with context functions can be used with a zero-length context.

This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] §8.2 under the name RSASSA-PKCS1-v1_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 EMSA-PKCS1-V1_5-ENCODE() in [RFC8017] §9.2. \(H\) is the message digest, computed using the hash_alg hash algorithm.

Compatible key types

PSA_KEY_TYPE_RSA_KEY_PAIR
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 specialized signature algorithm can only be used with the psa_sign_hash() and psa_verify_hash() functions. RSA PKCS#1 v1.5 does not have a context parameter. However, psa_sign_hash_with_context() or psa_verify_hash_with_context() can be used with a zero-length context.

This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] §8.2 under the name RSASSA-PKCS1-v1_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 EMSA-PKCS1-V1_5-ENCODE() in [RFC8017] §9.2. \(T\) is normally the DER encoding of the DigestInfo structure produced by step 2 in the message encoding algorithm, but it can be any byte string within the available length.

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_KEY_PAIR
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) /* 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. This includes PSA_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 hash-and-sign signature algorithm can be used with both the message and hash signature functions. RSA PSS does not have a context parameter. However, the sign or verify with context functions can be used with a zero-length context.

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 RSASSA-PSS, 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, hash_alg, is used to hash the input message, to create the salted hash, and for the mask generation.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest, computed using the hash_alg hash algorithm.

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_KEY_PAIR
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.

Added in version 1.1.

#define PSA_ALG_RSA_PSS_ANY_SALT(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. This includes PSA_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 hash-and-sign signature algorithm can be used with both the message and hash signature functions. RSA PSS does not have a context parameter. However, the sign or verify with context functions can be used with a zero-length context.

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 RSASSA-PSS, 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 RSASSA-PSS signature algorithm is accepted.

  • The specified hash algorithm, hash_alg, is used to hash the input message, to create the salted hash, and for the mask generation.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest, computed using the hash_alg hash algorithm.

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_KEY_PAIR
PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

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) /* specification-defined 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) /* specification-defined 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.

Added in version 1.1.

#define PSA_ALG_IS_RSA_PSS_ANY_SALT(alg) /* specification-defined 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.

Added in version 1.1.

#define PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg) /* specification-defined 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().

10.9.2 ECDSA signature algorithms

PSA_ALG_ECDSA (macro)

The randomized ECDSA signature scheme, with hashing.

#define PSA_ALG_ECDSA(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. This includes PSA_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 hash-and-sign signature algorithm can be used with both the message and hash signature functions. ECDSA does not have a context parameter. However, the sign or verify with context functions can be used with a zero-length context.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest, computed using the hash_alg hash algorithm.

This algorithm is randomized: each invocation returns a different, equally valid signature.

The ECDSA 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) [X9-62], with a random per-message 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 a big-endian \(m\)-octet string, where \(m\) is the integer for which \(2^{8(m-1)} \leq q < 2^{8m}\), and \(q\) is the order of the elliptic curve.

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.

Note

A verifier cannot 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.

When PSA_ALG_ECDSA(hash_alg) is used as a permitted algorithm in a key policy, this permits:

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(family)
PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

PSA_ALG_ECDSA_ANY (macro)

The randomized ECDSA signature scheme, without hashing.

#define PSA_ALG_ECDSA_ANY ((psa_algorithm_t) 0x06000600)

This specialized signature algorithm can only be used with the psa_sign_hash() and psa_verify_hash() functions. ECDSA does not have a context parameter. However, psa_sign_hash_with_context() or psa_verify_hash_with_context() can be used with a zero-length context.

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.

Warning

This algorithm is only recommended to sign or verify a sequence of bytes that are a pre-computed hash. Note that the input is padded with zeros on the left or truncated on the right as required to fit the curve size.

This algorithm cannot be used with the wildcard key policy PSA_ALG_ECDSA(PSA_ALG_ANY_HASH). It is only permitted when PSA_ALG_ECDSA_ANY is the key’s permitted-algorithm policy.

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(family)
PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

PSA_ALG_DETERMINISTIC_ECDSA (macro)

Deterministic ECDSA signature scheme, with hashing.

#define PSA_ALG_DETERMINISTIC_ECDSA(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. This includes PSA_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 hash-and-sign signature algorithm can be used with both the message and hash signature functions. ECDSA does not have a context parameter. However, the sign or verify with context functions can be used with a zero-length context.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest, computed using the hash_alg hash algorithm.

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.

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.

Note

A verifier cannot 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.

When PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) is used as a permitted algorithm in a key policy, this permits:

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(family)
PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

PSA_ALG_IS_ECDSA (macro)

Whether the specified algorithm is ECDSA.

#define PSA_ALG_IS_ECDSA(alg) /* specification-defined 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) /* specification-defined 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) /* specification-defined 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().

10.9.3 EdDSA signature algorithms

The PureEdDSA and HashEdDSA digital signature algorithms are defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]. They are used with the Edwards25519 and Edwards448 elliptic curve keys, see PSA_ECC_FAMILY_TWISTED_EDWARDS.

  • PureEdDSA is a set of message-signing algorithms, that cannot be split into a hash step, followed by a signature or verification step.

  • HashEdDSA is a pair of hash-and-sign algorithms, with a specified hash algorithm associated with each key size.

Both PureEdDSA and HashEdDSA can be used with contexts, which enables domain-separation when signatures are made of different message structures with the same key. For EdDSA, the context is an arbitrary byte string between zero and 255 bytes in length.

The development of EdDSA resulted in a total of five distinct algorithms:

  • Ed25519: the original PureEdDSA algorithm for the Edwards25519 curve, which does not accept a context.

  • Ed25519ctx: a second PureEdDSA algorithm for the Edwards25519 curve, with a context parameter.

  • Ed448: the PureEdDSA algorithm for the Edwards448 curve, with a context parameter.

  • Ed25519ph: the HashEdDSA algorithm for the Edwards25519 curve, with a context parameter.

  • Ed448ph: the HashEdDSA algorithm for the Edwards448 curve, with a context parameter.

Table 15 shows the algorithm identifiers in the Crypto API, and how they are used to select the appropriate EdDSA algorithm.

Table 15 EdDSA algorithm identifiers

Algorithm identifier

With 255-bit key

With 448-bit key

Sign/verify hash

Support non-zero-length context

PSA_ALG_PURE_EDDSA

Ed25519

Ed448

No

No

PSA_ALG_ED25519PH

Ed25519ph

Invalid

Yes

Yes

PSA_ALG_ED448PH

Invalid

Ed448ph

Yes

Yes

PSA_ALG_EDDSA_CTX

Ed25519ctx

Ed448

No

Yes

Note

Ed25519ctx produces a distinct signature to Ed25519, even with a zero-length context.

PSA_ALG_PURE_EDDSA (macro)

Edwards-curve digital signature algorithm without pre-hashing (PureEdDSA), with zero-length context.

Added in version 1.1.

#define PSA_ALG_PURE_EDDSA ((psa_algorithm_t) 0x06000800)

This message-signature algorithm can be used with the psa_sign_message() and psa_verify_message() functions. With a zero-length context, PSA_ALG_PURE_EDDSA can also be used with the psa_sign_message_with_context() and psa_verify_message_with_context() functions. It cannot be used to sign hashes.

This is the PureEdDSA digital signature algorithm defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032], with zero-length context.

PureEdDSA requires an elliptic curve key on a twisted Edwards curve (see PSA_ECC_FAMILY_TWISTED_EDWARDS). The following curves are supported:

  • Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the concatenation of \(R\) and \(S\) as defined by [RFC8032] §5.1.6.

  • Edwards448: the Ed448 algorithm is computed, with a zero-length context. The output signature is a 114-byte string: the concatenation of \(R\) and \(S\) as defined by [RFC8032] §5.2.6.

Note

To sign or verify the pre-computed hash of a message using EdDSA, the HashEdDSA algorithms (PSA_ALG_ED25519PH and PSA_ALG_ED448PH) can be used. The signature produced by HashEdDSA is distinct from that produced by PureEdDSA.

Note

To sign or verify a message with a non-zero-length context using PureEdDSA, use the PSA_ALG_EDDSA_CTX algorithm.

With an Edwards25519 curve key, PSA_ALG_EDDSA_CTX with a zero-length context creates different signatures to PSA_ALG_PURE_EDDSA.

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)
PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

PSA_ALG_EDDSA_CTX (macro)

Edwards-curve digital signature algorithm without pre-hashing (PureEdDSA), with a context.

Added in version 1.4.

#define PSA_ALG_EDDSA_CTX ((psa_algorithm_t) 0x06000A00)

This message-signature algorithm can be used with both the message and message with context signature functions. It cannot be used to sign hashes.

This is the PureEdDSA digital signature algorithm defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032], with a context parameter. The context parameter can be between zero and 255 bytes in length.

PureEdDSA requires an elliptic curve key on a twisted Edwards curve (see PSA_ECC_FAMILY_TWISTED_EDWARDS). The following curves are supported:

  • Edwards25519: the Ed25519ctx algorithm is computed. The output signature is a 64-byte string: the concatenation of \(R\) and \(S\) as defined by [RFC8032] §5.1.6.

  • Edwards448: the Ed448 algorithm is computed, with a zero-length context. The output signature is a 114-byte string: the concatenation of \(R\) and \(S\) as defined by [RFC8032] §5.2.6.

To use a non-zero-length context, use the message-signature functions that accept a context parameter, psa_sign_message_with_context() and psa_verify_message_with_context() The psa_sign_message() and psa_verify_message() functions use a zero-length context when computing or verifying signatures.

Note

To sign or verify the pre-computed hash of a message using EdDSA, the HashEdDSA algorithms (PSA_ALG_ED25519PH and PSA_ALG_ED448PH) can be used. The signature produced by HashEdDSA is distinct from that produced by PureEdDSA.

Note

With an Edwards25519 curve key, PSA_ALG_EDDSA_CTX with a zero-length context creates different signatures to PSA_ALG_PURE_EDDSA.

Usage

This is a message signing algorithm. To calculate a signature, use one of the following approaches:

Verifying a signature is similar, using psa_verify_message() or psa_verify_message_with_context().

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)
PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

PSA_ALG_ED25519PH (macro)

Edwards-curve digital signature algorithm with pre-hashing (HashEdDSA), using the Edwards25519 curve.

Added in version 1.1.

#define PSA_ALG_ED25519PH ((psa_algorithm_t) 0x0600090B)

This hash-and-sign signature algorithm can be used with both the message and hash signature functions.

This calculates the Ed25519ph algorithm as specified in Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032] §5.1, and requires an Edwards25519 curve key.

The pre-hash function is SHA-512, see PSA_ALG_SHA_512. When used to sign or verify a hash, the hash parameter is the SHA-512 message digest.

The signature functions without a context parameter use a zero-length context when computing or verifying signatures. To use a non-zero-length context, use the signature functions that accept a context parameter, such as psa_sign_hash_with_context() or psa_verify_message_with_context() The context parameter can be between zero and 255 bytes in length.

Implementation note

When used to sign or verify a hash, the hash parameter to the call should be used as \(\text{PH}(M)\) in the algorithms defined in [RFC8032] §5.1.

Usage

This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches:

Verifying a signature is similar, using one of the following approaches:

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)
PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

PSA_ALG_ED448PH (macro)

Edwards-curve digital signature algorithm with pre-hashing (HashEdDSA), using the Edwards448 curve.

Added in version 1.1.

#define PSA_ALG_ED448PH ((psa_algorithm_t) 0x06000915)

This hash-and-sign signature algorithm can be used with both the message and hash signature functions.

This calculates the Ed448ph algorithm as specified in Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032] §5.2, and requires an Edwards448 curve key.

The pre-hash function is the first 64 bytes of the output from SHAKE256, see PSA_ALG_SHAKE256_512. When used to sign or verify a hash, the hash parameter is the truncated SHAKE256 message digest.

The signature functions without a context parameter use a zero-length context when computing or verifying signatures. To use a non-zero-length context, use the signature functions that accept a context parameter, for example, psa_sign_hash_with_context() or psa_verify_message_with_context() The context parameter can be between zero and 255 bytes in length.

Implementation note

When used to sign or verify a hash, the hash parameter to the call should be used as \(\text{PH}(M)\) in the algorithms defined in [RFC8032] §5.2.

Usage

This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches:

Verifying a signature is similar, using one of the following approaches:

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)
PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

PSA_ALG_IS_HASH_EDDSA (macro)

Whether the specified algorithm is HashEdDSA.

Added in version 1.1.

#define PSA_ALG_IS_HASH_EDDSA(alg) /* specification-defined 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.

10.9.4 Asymmetric signature functions

psa_sign_message (function)

Sign a message with a private key. For hash-and-sign 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 permit the usage PSA_KEY_USAGE_SIGN_MESSAGE.

alg

An asymmetric signature algorithm: a value of type psa_algorithm_t such that PSA_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) where key_type and key_bits are the type and bit-size respectively of key.

  • PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.

signature_length

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 of signature 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() or PSA_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 that permits signing a message.

  • key is not an asymmetric key pair, that is compatible with alg.

  • 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 that permits signing a message.

  • key is not supported for use with alg.

  • 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

If the algorithm has a context parameter, a zero-length context is used. To provide a context value, use psa_sign_message_with_context() instead.

Note

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

psa_sign_message_with_context (function)

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

Added in version 1.4.

psa_status_t psa_sign_message_with_context(psa_key_id_t key,
                                           psa_algorithm_t alg,
                                           const uint8_t * input,
                                           size_t input_length,
                                           const uint8_t * context,
                                           size_t context_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 permit the usage PSA_KEY_USAGE_SIGN_MESSAGE.

alg

An asymmetric signature algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_SIGN_MESSAGE(alg) is true.

input

The input message to sign.

input_length

Size of the input buffer in bytes.

context

The context to use for this signature.

context_length

Size of the context 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) where key_type and key_bits are the type and bit-size respectively of key.

  • PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.

signature_length

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 of signature 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() or PSA_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 that permits signing a message with a non-zero-length context.

  • key is not an asymmetric key pair, that is compatible with alg.

  • input_length is too large for the algorithm and key type.

  • context_length is not valid for the algorithm and key type.

  • context is not a valid input value 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 that permits signing a message.

  • key is not supported for use with alg.

  • The implementation does not support this value of context_length for alg.

  • 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

If a context parameter is not required, psa_sign_message() can be used instead.

Note

To perform a multi-part hash-and-sign signature algorithm, first use a multi-part hash operation and then pass the resulting hash to psa_sign_hash_with_context(). 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 hash-and-sign 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 permit the usage PSA_KEY_USAGE_VERIFY_MESSAGE.

alg

An asymmetric signature algorithm: a value of type psa_algorithm_t such that PSA_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 the input message with algorithm alg using the private key corresponding to key.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • alg is not an asymmetric signature algorithm that permits verifying a message.

  • key is not a public key or an asymmetric key pair, that is compatible with alg.

  • 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 that permits verifying a message.

  • 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

If the algorithm has a context parameter, a zero-length context is used. To provide a context value, use psa_verify_message_with_context() instead.

Note

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

psa_verify_message_with_context (function)

Verify the signature of a message with a public key and a supplied context. For hash-and-sign algorithms, this includes the hashing step.

Added in version 1.4.

psa_status_t psa_verify_message_with_context(psa_key_id_t key,
                                             psa_algorithm_t alg,
                                             const uint8_t * input,
                                             size_t input_length,
                                             const uint8_t * context,
                                             size_t context_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 permit the usage PSA_KEY_USAGE_VERIFY_MESSAGE.

alg

An asymmetric signature algorithm: a value of type psa_algorithm_t such that PSA_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.

context

The context to use for this signature.

context_length

Size of the context 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 the input message with algorithm alg using the private key corresponding to key.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • alg is not an asymmetric signature algorithm that permits verifying a message with a non-zero-length context.

  • key is not a public key or an asymmetric key pair, that is compatible with alg.

  • input_length is too large for the algorithm and key type.

  • context_length is not valid for the algorithm and key type.

  • context is not a valid input value 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 that permits verifying a message.

  • key is not supported for use with alg.

  • The implementation does not support this value of context_length for 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

If a context parameter is not required, psa_verify_message() can be used instead.

Note

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

psa_sign_hash (function)

Sign a pre-computed 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 permit 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 that PSA_ALG_IS_SIGN_HASH(alg) is true.

hash

The input to sign. This is usually the hash of a message.

See the description of this function, or the description of individual signature algorithms, for details of the 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) where key_type and key_bits are the type and bit-size respectively of key.

  • PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.

signature_length

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 of signature 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() or PSA_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 that permits signing a pre-computed hash.

  • key is not an asymmetric key pair, that is compatible with alg.

  • hash_length is not valid for the algorithm and key type.

  • hash is not a valid input value 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 that permits signing a pre-computed hash.

  • key is not supported for use with alg.

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

For hash-and-sign signature algorithms, the hash input to this function is the hash of the message to sign. The algorithm used to calculate this hash is encoded in the signature algorithm. For such algorithms, hash_length must equal the length of the hash output: hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg)).

Specialized signature algorithms can apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. For example, see PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

If the algorithm has a context parameter, a zero-length context is used. To provide a context value, use psa_sign_hash_with_context() instead.

psa_sign_hash_with_context (function)

Sign a pre-computed hash with a private key and a supplied context.

Added in version 1.4.

psa_status_t psa_sign_hash_with_context(psa_key_id_t key,
                                        psa_algorithm_t alg,
                                        const uint8_t * hash,
                                        size_t hash_length,
                                        const uint8_t * context,
                                        size_t context_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 permit 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 that PSA_ALG_IS_SIGN_HASH(alg) is true.

hash

The input to sign. This is usually the hash of a message.

See the description of this function, or the description of individual signature algorithms, for details of the acceptable inputs.

hash_length

Size of the hash buffer in bytes.

context

The context to use for this signature.

context_length

Size of the context 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) where key_type and key_bits are the type and bit-size respectively of key.

  • PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.

signature_length

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 of signature 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() or PSA_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 that permits signing a pre-computed hash with a context.

  • key is not an asymmetric key pair, that is compatible with alg.

  • hash_length is not valid for the algorithm and key type.

  • hash is not a valid input value for the algorithm and key type.

  • context_length is not valid for the algorithm and key type.

  • context is not a valid input value 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 that permits signing a pre-computed hash.

  • The implementation does not support this value of context_length for alg.

  • key is not supported for use with alg.

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

For hash-and-sign signature algorithms, the hash input to this function is the hash of the message to sign. The algorithm used to calculate this hash is encoded in the signature algorithm. For such algorithms, hash_length must equal the length of the hash output: hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg)).

Specialized signature algorithms can apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. For example, see PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

If a context parameter is not required, psa_sign_hash() can be used instead.

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 permit 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 that PSA_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 description of this function, or the description of individual signature algorithms, for details of the 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 signing hash with algorithm alg using the private key corresponding to key.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • alg is not an asymmetric signature algorithm that permits verifying a pre-computed hash.

  • key is not a public key or an asymmetric key pair, that is compatible with alg.

  • hash_length is not valid for the algorithm and key type.

  • hash is not a valid input value 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 that permits verifying a pre-computed hash.

  • 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

For hash-and-sign signature algorithms, the hash input to this function is the hash of the message to verify. The algorithm used to calculate this hash is encoded in the signature algorithm. For such algorithms, hash_length must equal the length of the hash output: hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg)).

Specialized signature algorithms can apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. For example, see PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

If the algorithm has a context parameter, a zero-length context is used. To provide a context value, use psa_verify_hash_with_context() instead.

psa_verify_hash_with_context (function)

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

Added in version 1.4.

psa_status_t psa_verify_hash_with_context(psa_key_id_t key,
                                          psa_algorithm_t alg,
                                          const uint8_t * hash,
                                          size_t hash_length,
                                          const uint8_t * context,
                                          size_t context_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 permit 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 that PSA_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 description of this function, or the description of individual signature algorithms, for details of the acceptable inputs.

hash_length

Size of the hash buffer in bytes.

context

The context to use for this signature.

context_length

Size of the context 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 signing hash with algorithm alg using the private key corresponding to key.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • alg is not an asymmetric signature algorithm that permits verifying a pre-computed hash with a context.

  • key is not a public key or an asymmetric key pair, that is compatible with alg.

  • hash_length is not valid for the algorithm and key type.

  • hash is not a valid input value for the algorithm and key type.

  • context_length is not valid for the algorithm and key type.

  • context is not a valid input value 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 that permits verifying a pre-computed hash.

  • The implementation does not support this value of context_length for alg.

  • 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

For hash-and-sign signature algorithms, the hash input to this function is the hash of the message to verify. The algorithm used to calculate this hash is encoded in the signature algorithm. For such algorithms, hash_length must equal the length of the hash output: hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg)).

Specialized signature algorithms can apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. For example, see PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

If a context parameter is not required, psa_verify_hash() can be used instead.

10.9.5 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) /* specification-defined 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 a pre-computed 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.

Description

This macro evaluates to 1 for hash-and-sign and message-signature algorithms.

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) /* specification-defined 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 macro evaluates to 1 for hash-and-sign and specialized signature algorithms.

PSA_ALG_IS_HASH_AND_SIGN (macro)

Whether the specified algorithm is a hash-and-sign algorithm that signs exactly the hash value.

#define PSA_ALG_IS_HASH_AND_SIGN(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a hash-and-sign 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 parameterized 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, ...):

uint8_t hash[PSA_HASH_MAX_SIZE];
size_t hash_len;
psa_hash_compute(PSA_ALG_GET_HASH(alg), msg, msg_len,
                 hash, sizeof(hash), &hash_len);
psa_sign_hash(key, alg, hash, hash_len, ...);

PSA_ALG_SIGN_SUPPORTS_CONTEXT (macro)

Whether the specified signature algorithm can be used with a non-zero-length context.

Added in version 1.4.

#define PSA_ALG_SIGN_SUPPORTS_CONTEXT(alg) /* implementation-defined value */

Parameters

alg

A signature algorithm identifier: a value of type psa_algorithm_t such that PSA_ALG_IS_SIGN(alg) is true.

Returns

1 if alg is a signature algorithm that can be used with a non-zero-length context. 0 if alg is a signature algorithm that cannot be used with a non-zero-length context. This macro can return either 0 or 1 if alg is not a supported signature algorithm identifier.

A wildcard signature algorithm policy, using PSA_ALG_ANY_HASH, returns the same value as the signature algorithm parameterized with a valid hash algorithm.

Description

This macro identifies signature algorithms that have a context parameter, and can be used with the appropriate functions that support non-zero-length contexts.

PSA_ALG_ANY_HASH (macro)

When setting a hash-and-sign 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 cannot be used to build an algorithm specification to perform an operation. If used in this way, the operation will fail with an error.

Usage

For example, suppose that PSA_xxx_SIGNATURE is one of the following macros:

The following sequence of operations shows how PSA_ALG_ANY_HASH can be used in a key policy:

  1. 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));

  2. Import or generate key material.

  3. Call psa_sign_message() or psa_verify_message(), passing an algorithm built from PSA_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) \
    /* implementation-defined 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 /* implementation-defined 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().