Stateless Hash-Based Digital Signature Algorithm (SLH-DSA)

SLH-DSA is the post-quantum, hash-based digital signature scheme standardized by NIST in FIPS 205. Its keys are in Crypto.PublicKey.SLHDSA.

FIPS 205 defines two variants:

  • SLH-DSA, where the message is signed directly (recommended).

  • HashSLH-DSA, where the message is first hashed, and only the resulting digest is signed. This should only be used by applications that cannot process the whole message at once when signing, because it requires a hash function with enough collision resistance.

This module supports both variants, with any of the twelve parameter sets of FIPS 205, and the six parameter sets of the draft SP 800-230, whose support is experimental: do not use them in production.

A signature also depends on a context: up to 255 bytes that separate different protocols or applications using the same key (empty by default). The same context must be used to sign and to verify.

By default, the signature is hedged: it also depends on fresh random bytes, which protects against fault and side-channel attacks. With deterministic=True, it only depends on the key, the context and the message. Both kinds of signatures are verified in the same way.

A sender can use a private key (loaded from a file) to sign a message:

from Crypto.PublicKey import SLHDSA
from Crypto.Signature import slhdsa

message = b'I give my permission to order #4355'
key = SLHDSA.import_key(open("private_slhdsa.pem").read())
signer = slhdsa.new(key)
signature = signer.sign(message)

The receiver can use the matching public key to verify the authenticity of the received message:

from Crypto.PublicKey import SLHDSA
from Crypto.Signature import slhdsa

message = b'I give my permission to order #4355'
key = SLHDSA.import_key(open("public_slhdsa.pem").read())
verifier = slhdsa.new(key)
try:
    verifier.verify(message, signature)
    print("The message is authentic")
except ValueError:
    print("The message is not authentic")

For HashSLH-DSA, pass a hash object that has processed the message, instead of the message itself:

from Crypto.Hash import SHA256
from Crypto.PublicKey import SLHDSA
from Crypto.Signature import slhdsa

message = b'I give my permission to order #4355'
key = SLHDSA.import_key(open("private_slhdsa.pem").read())
signer = slhdsa.new(key, context=b'my application')
signature = signer.sign(SHA256.new(message))

The hash function can be SHA-2 (Crypto.Hash.SHA224, Crypto.Hash.SHA256, Crypto.Hash.SHA384, Crypto.Hash.SHA512, also truncated), SHA-3 (Crypto.Hash.SHA3_224, Crypto.Hash.SHA3_256, Crypto.Hash.SHA3_384, Crypto.Hash.SHA3_512) or SHAKE (Crypto.Hash.SHAKE128 and Crypto.Hash.SHAKE256, with 256 and 512 bits of output). To keep the security level of the key, FIPS 205 (Section 10.2.2) asks for a function with at least as much collision resistance as the parameter set: for instance, SHA-256 or SHAKE128 for the parameter sets of category 1, and SHA-512 or SHAKE256 for those of category 5.

Signing is slow, especially with the s parameter sets of FIPS 205, and even more with those of SP 800-230 (several minutes): with threads, new() can use several CPU cores (threads=0 for all of them). The signature is the same with any number of threads.

SLH-DSA and HashSLH-DSA signatures (FIPS 205)

Crypto.Signature.slhdsa.new(key, *, context=None, deterministic=False, randfunc=None, threads=1)

Create a signature object SLHDSASigScheme that can perform or verify an SLH-DSA signature (FIPS 205).

Parameters:

key (Crypto.PublicKey.SLHDSA.SLHDSAKey) – The key to use for computing the signature (private keys only) or for verifying one.

Keyword Arguments:
  • context (bytes) – Up to 255 bytes of context, a constant byte string to separate different protocols or different applications of the same key. If None (default), the context is empty.

  • deterministic (boolean) – If False (default), the signature is hedged: it depends on fresh random bytes too (the recommended variant). If True, the signature is deterministic: it only depends on the key, the context and the message. Verification is the same in both cases.

  • randfunc (callable) – The RNG for the hedged signatures: a function that returns the requested number of random bytes. If None, Crypto.Random.get_random_bytes() is used. It cannot be combined with deterministic=True.

  • threads (integer) – The maximum number of threads used to sign (default: 1, no extra threads; 0 for all CPU cores). The signature does not depend on the number of threads. Verification always uses one thread (it is fast).

Return type:

SLHDSASigScheme

class Crypto.Signature.slhdsa.SLHDSASigScheme(key, context, deterministic, randfunc, threads)

An SLH-DSA signature object. Do not instantiate directly. Use Crypto.Signature.slhdsa.new().

can_sign()

Return True if this signature object can be used for signing messages.

Return type:

bool

sign(msg_or_hash)

Compute the SLH-DSA signature of a message.

Parameters:

msg_or_hash (bytes or a hash object) –

One of:

Return type:

bytes

Returns:

The signature as bytes (from 3856 to 49856 bytes, depending on the parameter set).

Raises:

TypeError – if the key is not a private key.

verify(msg_or_hash, signature)

Check if an SLH-DSA signature is authentic.

Parameters:
  • msg_or_hash (bytes or a hash object) – The message that was signed, as for sign().

  • signature (bytes) – The signature to verify.

Raises:

ValueError – if the signature is not authentic.

Return type:

None