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:
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:
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 thatPSA_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:
PSA_ALG_SLH_DSA
as the algorithm in a call topsa_sign_message
()
.PSA_ALG_SLH_DSA
orPSA_ALG_DETERMINISTIC_SLH_DSA
as the algorithm in a call topsa_verify_message
()
.
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_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:
PSA_ALG_DETERMINISTIC_SLH_DSA
as the algorithm in a call topsa_sign_message
()
.PSA_ALG_SLH_DSA
orPSA_ALG_DETERMINISTIC_SLH_DSA
as the algorithm in a call topsa_verify_message
()
.
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_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 thatPSA_ALG_IS_HASH
(
hash_alg
)
is true. This includesPSA_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:
PSA_ALG_HASH_SLH_DSA()
as the algorithm in a call topsa_sign_message
()
andpsa_sign_hash
()
.PSA_ALG_HASH_SLH_DSA()
orPSA_ALG_DETERMINISTIC_HASH_SLH_DSA()
as the algorithm in a call topsa_verify_message
()
andpsa_verify_hash
()
.
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 thehash_alg
hash algorithm. Note thathash_alg
can be extracted from the signature algorithm usingPSA_ALG_GET_HASH
(
sig_alg
)
. 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_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 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 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:
PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()
as the algorithm in a call topsa_sign_message
()
andpsa_sign_hash
()
.PSA_ALG_HASH_SLH_DSA()
orPSA_ALG_DETERMINISTIC_HASH_SLH_DSA()
as the algorithm in a call topsa_verify_message
()
andpsa_verify_hash
()
.
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_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()
.