Beta

2.4 Stateless Hash-based signatures

2.4.1 Stateless Hash-based signature keys

The Crypto API supports Stateless Hash-based digital signatures (SLH-DSA), as defined in FIPS Publication 205: Stateless Hash-Based Digital Signature Standard [FIPS205].

psa_slh_dsa_family_t (typedef)

The type of identifiers of a Stateless hash-based DSA parameter set.

Added in version 1.3.

typedef uint8_t psa_slh_dsa_family_t;

The parameter-set identifier is required to create an SLH-DSA key using the PSA_KEY_TYPE_SLH_DSA_KEY_PAIR() or PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY() macros.

The specific SLH-DSA parameter set within a family is identified by the key_bits attribute of the key.

The range of SLH-DSA family identifier values is divided as follows:

0x00

Reserved. Not allocated to an SLH-DSA parameter-set family.

0x01 - 0x7f

SLH-DSA parameter-set family identifiers defined by this standard. Unallocated values in this range are reserved for future use.

0x80 - 0xff

Invalid. Values in this range must not be used.

The least significant bit of an SLH-DSA family identifier is a parity bit for the whole key type. See SLH-DSA key encoding for details of the encoding of asymmetric key types.

PSA_KEY_TYPE_SLH_DSA_KEY_PAIR (macro)

SLH-DSA key pair: both the private key and public key.

Added in version 1.3.

#define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) /* specification-defined value */

Parameters

set

A value of type psa_slh_dsa_family_t that identifies the SLH-DSA parameter-set family to be used.

Description

The key attribute size of of an SLH-DSA key pair is the bit-size of each component in the SLH-DSA keys defined in [FIPS205]. That is, for a parameter set with security parameter \(n\), the bit-size in the key attributes is \(8n\). See the documentation of each SLH-DSA parameter-set family for details.

Compatible algorithms

Key format

Warning

The key format may change in a final version of this API. The standardization of exchange formats for SHL-DSA public and private keys is in progress, but final documents have not been published. See Internet X.509 Public Key Infrastructure: Algorithm Identifiers for SLH-DSA [LAMPS-SLHDSA].

The current proposed format is based on the expected outcome of that process.

A SLH-DSA key pair is defined in [FIPS205] §9.1 as the four \(n\)-byte values, \(SK\text{.seed}\), \(SK\text{.prf}\), \(PK\text{.seed}\), and \(PK\text{.root}\), where \(n\) is the security parameter.

In calls to psa_import_key() and psa_export_key(), the key-pair data format is the concatenation of the four octet strings:

\[SK\text{.seed}\ ||\ SK\text{.prf}\ ||\ PK\text{.seed}\ ||\ PK\text{.root}\]

See PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY for the data format used when exporting the public key with psa_export_public_key().

Key derivation

A call to psa_key_derivation_output_key() will draw output bytes as follows:

  • \(n\) bytes are drawn as \(SK\text{.seed}\).

  • \(n\) bytes are drawn as \(SK\text{.prf}\).

  • \(n\) bytes are drawn as \(PK\text{.seed}\).

Here, \(n\) is the security parameter for the selected SLH-DSA parameter set.

The private key \((SK\text{.seed},SK\text{.prf},PK\text{.seed},PK\text{.root})\) is generated from these values as defined by slh_keygen_internal() in [FIPS205] §9.1.

PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY (macro)

SLH-DSA public key.

Added in version 1.3.

#define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) /* specification-defined value */

Parameters

set

A value of type psa_slh_dsa_family_t that identifies the SLH-DSA parameter-set family to be used.

Description

The key attribute size of an SLH-DSA public key is the same as the corresponding private key. See PSA_KEY_TYPE_SLH_DSA_KEY_PAIR() and the documentation of each SLH-DSA parameter-set family for details.

Compatible algorithms

Key format

Warning

The key format may change in a final version of this API. The standardization of exchange formats for SHL-DSA public and private keys is in progress, but final documents have not been published. See Internet X.509 Public Key Infrastructure: Algorithm Identifiers for SLH-DSA [LAMPS-SLHDSA].

The current proposed format is based on the expected outcome of that process.

A SLH-DSA public key is defined in [FIPS205] §9.1 as two \(n\)-byte values, \(PK\text{.seed}\) and \(PK\text{.root}\), where \(n\) is the security parameter.

In calls to psa_import_key(), psa_export_key(), and psa_export_public_key(), the public-key data format is the concatenation of the two octet strings:

\[PK\text{.seed}\ ||\ PK\text{.root}\]

PSA_SLH_DSA_FAMILY_SHA2_S (macro)

SLH-DSA family for the SLH-DSA-SHA2-NNNs parameter sets.

Added in version 1.3.

#define PSA_SLH_DSA_FAMILY_SHA2_S ((psa_slh_dsa_family_t) 0x02)

This family comprises the following parameter sets:

  • SLH-DSA-SHA2-128s : key_bits = 128

  • SLH-DSA-SHA2-192s : key_bits = 192

  • SLH-DSA-SHA2-256s : key_bits = 256

They are defined in [FIPS205].

PSA_SLH_DSA_FAMILY_SHA2_F (macro)

SLH-DSA family for the SLH-DSA-SHA2-NNNf parameter sets.

Added in version 1.3.

#define PSA_SLH_DSA_FAMILY_SHA2_F ((psa_slh_dsa_family_t) 0x04)

This family comprises the following parameter sets:

  • SLH-DSA-SHA2-128f : key_bits = 128

  • SLH-DSA-SHA2-192f : key_bits = 192

  • SLH-DSA-SHA2-256f : key_bits = 256

They are defined in [FIPS205].

PSA_SLH_DSA_FAMILY_SHAKE_S (macro)

SLH-DSA family for the SLH-DSA-SHAKE-NNNs parameter sets.

Added in version 1.3.

#define PSA_SLH_DSA_FAMILY_SHAKE_S ((psa_slh_dsa_family_t) 0x0b)

This family comprises the following parameter sets:

  • SLH-DSA-SHAKE-128s : key_bits = 128

  • SLH-DSA-SHAKE-192s : key_bits = 192

  • SLH-DSA-SHAKE-256s : key_bits = 256

They are defined in [FIPS205].

PSA_SLH_DSA_FAMILY_SHAKE_F (macro)

SLH-DSA family for the SLH-DSA-SHAKE-NNNf parameter sets.

Added in version 1.3.

#define PSA_SLH_DSA_FAMILY_SHAKE_F ((psa_slh_dsa_family_t) 0x0d)

This family comprises the following parameter sets:

  • SLH-DSA-SHAKE-128f : key_bits = 128

  • SLH-DSA-SHAKE-192f : key_bits = 192

  • SLH-DSA-SHAKE-256f : key_bits = 256

They are defined in [FIPS205].

PSA_KEY_TYPE_IS_SLH_DSA (macro)

Whether a key type is an SLH-DSA key, either a key pair or a public key.

Added in version 1.3.

#define PSA_KEY_TYPE_IS_SLH_DSA(type) /* specification-defined value */

Parameters

type

A key type: a value of type psa_key_type_t.

PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR (macro)

Whether a key type is an SLH-DSA key pair.

Added in version 1.3.

#define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \
    /* specification-defined value */

Parameters

type

A key type: a value of type psa_key_type_t.

PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY (macro)

Whether a key type is an SLH-DSA public key.

Added in version 1.3.

#define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \
    /* specification-defined value */

Parameters

type

A key type: a value of type psa_key_type_t.

PSA_KEY_TYPE_SLH_DSA_GET_FAMILY (macro)

Extract the parameter-set family from an SLH-DSA key type.

Added in version 1.3.

#define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) /* specification-defined value */

Parameters

type

An SLH-DSA key type: a value of type psa_key_type_t such that PSA_KEY_TYPE_IS_SLH_DSA(type) is true.

Returns: psa_dh_family_t

The SLH-DSA parameter-set family id, if type is a supported SLH-DSA key. Unspecified if type is not a supported SLH-DSA key.

2.4.2 Stateless Hash-based signature algorithms

These algorithms extend those defined in PSA Certified Crypto API [PSA-CRYPT] §10.7 Asymmetric signature, for use with the signature functions.

The SLH-DSA signature and verification scheme is defined in FIPS Publication 205: Stateless Hash-Based Digital Signature Standard [FIPS205]. SLH-DSA has twelve parameter sets which provide differing security strengths, trade-off between signature size and computation cost, and selection between SHA2 and SHAKE-based hashing.

SLH-DSA keys are fairly compact, 32, 48, or 64 bytes for the public key, and double that for the key pair. SLH-DSA signatures are much larger than those for RSA and Elliptic curve schemes, between 7.8kB and 49kB depending on the selected parameter set. An SLH-DSA signature has the structure described in [FIPS205] §9.2, Figure 17.

See [FIPS205] §11 for details on the parameter sets, and the public key and generated signature sizes.

The generation of an SLH-DSA key depends on the full parameter specification. The encoding of each parameter set into the key attributes is described in Stateless Hash-based signature keys.

[FIPS205] defines pure and pre-hashed variants of the signature scheme, which can either be hedged (randomized) or deterministic. Four algorithms are defined to support these variants: PSA_ALG_SLH_DSA, PSA_ALG_DETERMINISTIC_SLH_DSA, PSA_ALG_HASH_SLH_DSA(), and PSA_ALG_DETERMINISTIC_HASH_SLH_DSA().

Hedged and deterministic signatures

Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every signing operation when given identical inputs. Deterministic signatures do not require additional random data, and result in an identical signature for the same inputs.

Signature verification does not distinguish between a hedged and a deterministic signature. Either hedged or deterministic algorithms can be used when verifying a signature.

When computing a signature, the key’s permitted-algorithm policy must match the requested algorithm, treating hedged and deterministic versions as distinct. When verifying a signature, the hedged and deterministic versions of each algorithm are considered equivalent when checking the key’s permitted-algorithm policy.

Note

The hedged version provides message secrecy and some protection against side-channels. [FIPS205] recommends that users should use the hedged version if either of these issues are a concern. The deterministic variant should only be used if the implementation does not include any source of randomness.

Implementation note

[FIPS205] recommends that implementations use an approved random number generator to provide the random value in the hedged version. However, it notes that use of the hedged variant with a weak RNG is generally preferable to the deterministic variant.

Rationale

The use of fresh randomness, or not, when computing a signature seems like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in [FIPS205].

However, the Crypto API gives distinct algorithm identifiers for the hedged and deterministic variants for the following reasons:

  • [FIPS205] §9.1 recommends that SLH-DSA signing keys are only used to compute either deterministic, or hedged, signatures, but not both. Supporting this recommendation requires separate algorithm identifiers, and requiring an exact policy match for signature computation.

  • Enable an application use case to require a specific variant.

Pure and pre-hashed algorithms

The pre-hashed signature computation HashSLH-DSA generates distinct signatures to a pure signature SLH-DSA, with the same key and message hashing algorithm.

An SLH-DSA signature can only be verified with an SLH-DSA algorithm. A HashSLH-DSA signature can only be verified with a HashSLH-DSA algorithm.

Contexts

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 empty context string is used when computing or verifying SLH-DSA signatures.

A future version of this specification may add suitable functions and extend this algorithm to support contexts.

PSA_ALG_SLH_DSA (macro)

Stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA).

Added in version 1.3.

#define PSA_ALG_SLH_DSA ((psa_algorithm_t) 0x06004000)

This algorithm can only be used with the psa_sign_message() and psa_verify_message() functions.

This is the pure SLH-DSA digital signature algorithm, defined by FIPS Publication 205: Stateless Hash-Based Digital Signature Standard [FIPS205], using hedging. SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation.

This algorithm is randomized: each invocation returns a different, equally valid signature. See the notes on hedged signatures.

When PSA_ALG_SLH_DSA is used as a permitted algorithm in a key policy, this permits:

Note

To sign or verify the pre-computed hash of a message using SLH-DSA, the HashSLH-DSA algorithms (PSA_ALG_HASH_SLH_DSA() and PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()) can also be used with psa_sign_hash() and psa_verify_hash().

The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA.

Compatible key types

PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()
PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY() (signature verification only)

PSA_ALG_DETERMINISTIC_SLH_DSA (macro)

Deterministic stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA).

Added in version 1.3.

#define PSA_ALG_DETERMINISTIC_SLH_DSA ((psa_algorithm_t) 0x06004100)

This algorithm can only be used with the psa_sign_message() and psa_verify_message() functions.

This is the pure SLH-DSA digital signature algorithm, defined by [FIPS205], without hedging. SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation.

This algorithm is deterministic: each invocation with the same inputs returns an identical signature.

Warning

It is recommended to use the hedged PSA_ALG_SLH_DSA algorithm instead, when supported by the implementation. See the notes on deterministic signatures.

When PSA_ALG_DETERMINISTIC_SLH_DSA is used as a permitted algorithm in a key policy, this permits:

Note

To sign or verify the pre-computed hash of a message using SLH-DSA, the HashSLH-DSA algorithms (PSA_ALG_HASH_SLH_DSA() and PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()) can also be used with psa_sign_hash() and psa_verify_hash().

The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA.

Compatible key types

PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()
PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY() (signature verification only)

PSA_ALG_HASH_SLH_DSA (macro)

Stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA).

Added in version 1.3.

#define PSA_ALG_HASH_SLH_DSA(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 HashSLH-DSA signature algorithm, using hash_alg to pre-hash the message.

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 pre-hashed SLH-DSA digital signature algorithm, defined by [FIPS205], using hedging. SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation.

Note

For the pre-hashing, [FIPS205] §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set.

This algorithm is randomized: each invocation returns a different, equally valid signature. See the notes on hedged signatures.

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

Note

The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA.

Usage

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

  • Call psa_sign_message() with the message.

  • Calculate the hash of the message with psa_hash_compute(), or with a multi-part hash operation, using the hash_alg hash algorithm. Note that hash_alg can be extracted from the signature algorithm using PSA_ALG_GET_HASH(sig_alg). Then sign the calculated hash with psa_sign_hash().

Verifying a signature is similar, using psa_verify_message() or psa_verify_hash() instead of the signature function.

Compatible key types

PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()
PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY() (signature verification only)

PSA_ALG_DETERMINISTIC_HASH_SLH_DSA (macro)

Deterministic stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA).

Added in version 1.3.

#define PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(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 HashSLH-DSA signature algorithm, using hash_alg to pre-hash the message.

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 pre-hashed SLH-DSA digital signature algorithm, defined by [FIPS205], without hedging. SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation.

Note

For the pre-hashing, [FIPS205] §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set.

This algorithm is deterministic: each invocation with the same inputs returns an identical signature.

Warning

It is recommended to use the hedged PSA_ALG_HASH_SLH_DSA() algorithm instead, when supported by the implementation. See the notes on deterministic signatures.

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

Note

The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA.

Usage

See PSA_ALG_HASH_SLH_DSA() for example usage.

Compatible key types

PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()
PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY() (signature verification only)

PSA_ALG_IS_SLH_DSA (macro)

Whether the specified algorithm is SLH-DSA.

Added in version 1.3.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an SLH-DSA algorithm, 0 otherwise.

This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

PSA_ALG_IS_HASH_SLH_DSA (macro)

Whether the specified algorithm is HashSLH-DSA.

Added in version 1.3.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a HashSLH-DSA algorithm, 0 otherwise.

This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA (macro)

Whether the specified algorithm is deterministic HashSLH-DSA.

Added in version 1.3.

#define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \
    /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a deterministic HashSLH-DSA 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_HASH_SLH_DSA() and PSA_ALG_IS_HEDGED_HASH_SLH_DSA().

PSA_ALG_IS_HEDGED_HASH_SLH_DSA (macro)

Whether the specified algorithm is hedged HashSLH-DSA.

Added in version 1.3.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a hedged HashSLH-DSA 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_HASH_SLH_DSA() and PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA().