SLH-DSA

SLH-DSA (Stateless Hash-Based Digital Signature Algorithm) is the post-quantum signature algorithm standardized by NIST in FIPS 205. It is derived from SPHINCS+.

This module generates, builds, imports and exports SLH-DSA keys. To sign messages and verify signatures with them, use Crypto.Signature.slhdsa (see Usage).

Its security only depends on the properties of the underlying hash function (SHA-2 or SHAKE), which makes it a conservative choice. Compared to ML-DSA, keys are very small, but signatures are much larger and signing is much slower.

FIPS 205 defines twelve parameter sets: for each NIST security category, there are two hash families (SHA2 or SHAKE), and a choice between small signatures (s) or fast signing (f):

Parameter set

Constant

NIST security category

Public key (bytes)

Private key (bytes)

Signature (bytes)

SLH-DSA-SHA2-128s

SLHDSA.SLH_DSA_SHA2_128s

1

32

64

7856

SLH-DSA-SHAKE-128s

SLHDSA.SLH_DSA_SHAKE_128s

1

32

64

7856

SLH-DSA-SHA2-128f

SLHDSA.SLH_DSA_SHA2_128f

1

32

64

17088

SLH-DSA-SHAKE-128f

SLHDSA.SLH_DSA_SHAKE_128f

1

32

64

17088

SLH-DSA-SHA2-192s

SLHDSA.SLH_DSA_SHA2_192s

3

48

96

16224

SLH-DSA-SHAKE-192s

SLHDSA.SLH_DSA_SHAKE_192s

3

48

96

16224

SLH-DSA-SHA2-192f

SLHDSA.SLH_DSA_SHA2_192f

3

48

96

35664

SLH-DSA-SHAKE-192f

SLHDSA.SLH_DSA_SHAKE_192f

3

48

96

35664

SLH-DSA-SHA2-256s

SLHDSA.SLH_DSA_SHA2_256s

5

64

128

29792

SLH-DSA-SHAKE-256s

SLHDSA.SLH_DSA_SHAKE_256s

5

64

128

29792

SLH-DSA-SHA2-256f

SLHDSA.SLH_DSA_SHA2_256f

5

64

128

49856

SLH-DSA-SHAKE-256f

SLHDSA.SLH_DSA_SHAKE_256f

5

64

128

49856

Pass one of these constants as the param_set argument. They are the members of the enum ParamSet, and the value of each member is the name of its parameter set (for instance, 'SLH-DSA-SHA2-128s'). The six parameter sets of SP 800-230 are also members, but their support is experimental and they must not be used in production (see SP 800-230 parameter sets).

On a recent x86-64 CPU, signing takes from a few tens of milliseconds (f sets) to about a second (s sets, slower with SHAKE than with SHA2), and verifying a few milliseconds. Generating a key (or building it from a private key) takes from about a millisecond (f) to a few hundred milliseconds (s).

The private key (SLHDSAKey.sk) and the public key (SLHDSAKey.pk) are encoded as in FIPS 205: the private key is made of four values of n bytes (SK.seed, SK.prf, PK.seed, PK.root), and the public key is its second half (PK.seed and PK.root).

The implementation follows FIPS 205 in Python, with the functions that compute most of the hashes in C (on top of the SHA-2 and SHAKE code of PyCryptodome). On CPUs with the Intel SHA extensions, SHA-256 uses them. On CPUs with AVX2 and BMI2, the SHAKE parameter sets compute 4 hashes at once.

Parameter sets with at most 224 signatures

Warning

The support for these parameter sets is experimental: do not use them in production.

They come from the initial public draft of NIST SP 800-230 (April 2026), which is not final yet: they may still change. Keys and signatures made with them may not be compatible with the final standard, nor with future versions of this module, which may change or remove these parameter sets without a deprecation period.

The security of a key relies on it signing at most 224 messages (about 16 million), across all the devices that share it, for its entire lifetime. Use them only if you can guarantee that.

SP 800-230 defines six more parameter sets, with smaller signatures and faster verification than FIPS 205, for applications that sign rarely and verify often (like software, firmware and certificates). They have a single XMSS tree (d = 1), with w = 4 or 8 instead of 16:

Parameter set

Constant

NIST security category

Public key (bytes)

Private key (bytes)

Signature (bytes)

SLH-DSA-SHA2-128-24

SLHDSA.SLH_DSA_SHA2_128_24

1

32

64

3856

SLH-DSA-SHAKE-128-24

SLHDSA.SLH_DSA_SHAKE_128_24

1

32

64

3856

SLH-DSA-SHA2-192-24

SLHDSA.SLH_DSA_SHA2_192_24

3

48

96

7752

SLH-DSA-SHAKE-192-24

SLHDSA.SLH_DSA_SHAKE_192_24

3

48

96

7752

SLH-DSA-SHA2-256-24

SLHDSA.SLH_DSA_SHA2_256_24

5

64

128

14944

SLH-DSA-SHAKE-256-24

SLHDSA.SLH_DSA_SHAKE_256_24

5

64

128

14944

The price is the time to generate a key (or to build it from a private key) and to sign: about a billion hashes each, which takes several minutes on one CPU core. Use the threads parameter of generate(), construct() and Crypto.Signature.slhdsa.new() to spread the work over several cores.

SP 800-230 also allows an implementation to store parts of the hypertree to sign faster: this module does not do that.

Generation

You can generate a new SLH-DSA key:

>>> from Crypto.PublicKey import SLHDSA
>>>
>>> key = SLHDSA.generate(param_set=SLHDSA.SLH_DSA_SHA2_128s)
>>> sk = key.sk           # 64 bytes, keep it secret
>>> pk = key.pk           # 32 bytes, the public key

and rebuild it later from its private key, or get the public key:

>>> key = SLHDSA.construct(param_set=SLHDSA.SLH_DSA_SHA2_128s, sk=sk)
>>> pub_key = SLHDSA.construct(param_set=SLHDSA.SLH_DSA_SHA2_128s, pk=pk)
>>> pub_key == key.public_key()
True

construct() checks that the private key is consistent (that PK.root matches the other values). With the SP 800-230 parameter sets, generate() and construct() take several minutes: use their threads parameter (for instance, threads=0 for all CPU cores).

To store a private key, prefer SLHDSAKey.export_key() with a passphrase (see the next section): the raw private key is not protected.

Import and Export

You can export an SLH-DSA key as defined in RFC 9909: a public key as an X.509 SubjectPublicKeyInfo, a private key as a PKCS#8 OneAsymmetricKey, optionally protected with a passphrase. These are the usual formats for public and private keys. The encoding is DER (binary, the default) or PEM (text, RFC 7468):

with open("myprivatekey.pem", "wt") as f:
    f.write(key.export_key(format="PEM", passphrase="secret"))

with open("mypublickey.der", "wb") as f:
    f.write(key.public_key().export_key())

and import it later (the format is detected automatically):

with open("myprivatekey.pem", "rt") as f:
    key = SLHDSA.import_key(f.read(), "secret")

import_key() also accepts X.509 certificates. Like construct(), it checks that a private key is consistent, which takes as long as generating a key (use its threads parameter).

Only the keys for pure SLH-DSA (with the OIDs id-slh-dsa-*) are supported, not those restricted to HashSLH-DSA (id-hash-slh-dsa-*). The keys of the SP 800-230 parameter sets cannot be exported or imported: there are no OIDs for them yet.

Usage

To sign messages and verify signatures with SLH-DSA keys, use Crypto.Signature.slhdsa.

API

SLH-DSA keys (FIPS 205): the parameter sets, the key class, and the functions to generate, build and import keys.

class Crypto.PublicKey.SLHDSA.ParamSet(value)

The SLH-DSA parameter sets of FIPS 205 (Section 11), and those of the initial public draft of NIST SP 800-230 (Table 1). The value of each member is its name in FIPS 205 or SP 800-230.

In FIPS 205, the s sets have small signatures and slow signing, the f sets have fast signing and larger signatures.

The -24 sets of SP 800-230 have smaller signatures and faster verification, but much slower signing and key generation (minutes), and each key must sign at most 2^24 messages. SP 800-230 is a draft: these sets may still change. Their support is experimental: do not use them in production.

SLH_DSA_SHA2_128s = 'SLH-DSA-SHA2-128s'

NIST security category 1, SHA-256

SLH_DSA_SHAKE_128s = 'SLH-DSA-SHAKE-128s'

NIST security category 1, SHAKE256

SLH_DSA_SHA2_128f = 'SLH-DSA-SHA2-128f'

NIST security category 1, SHA-256

SLH_DSA_SHAKE_128f = 'SLH-DSA-SHAKE-128f'

NIST security category 1, SHAKE256

SLH_DSA_SHA2_192s = 'SLH-DSA-SHA2-192s'

NIST security category 3, SHA-256 and SHA-512

SLH_DSA_SHAKE_192s = 'SLH-DSA-SHAKE-192s'

NIST security category 3, SHAKE256

SLH_DSA_SHA2_192f = 'SLH-DSA-SHA2-192f'

NIST security category 3, SHA-256 and SHA-512

SLH_DSA_SHAKE_192f = 'SLH-DSA-SHAKE-192f'

NIST security category 3, SHAKE256

SLH_DSA_SHA2_256s = 'SLH-DSA-SHA2-256s'

NIST security category 5, SHA-256 and SHA-512

SLH_DSA_SHAKE_256s = 'SLH-DSA-SHAKE-256s'

NIST security category 5, SHAKE256

SLH_DSA_SHA2_256f = 'SLH-DSA-SHA2-256f'

NIST security category 5, SHA-256 and SHA-512

SLH_DSA_SHAKE_256f = 'SLH-DSA-SHAKE-256f'

NIST security category 5, SHAKE256

SLH_DSA_SHA2_128_24 = 'SLH-DSA-SHA2-128-24'

NIST security category 1, SHA-256, at most 2^24 signatures (draft SP 800-230, experimental)

SLH_DSA_SHAKE_128_24 = 'SLH-DSA-SHAKE-128-24'

NIST security category 1, SHAKE256, at most 2^24 signatures (draft SP 800-230, experimental)

SLH_DSA_SHA2_192_24 = 'SLH-DSA-SHA2-192-24'

NIST security category 3, SHA-256 and SHA-512, at most 2^24 signatures (draft SP 800-230, experimental)

SLH_DSA_SHAKE_192_24 = 'SLH-DSA-SHAKE-192-24'

NIST security category 3, SHAKE256, at most 2^24 signatures (draft SP 800-230, experimental)

SLH_DSA_SHA2_256_24 = 'SLH-DSA-SHA2-256-24'

NIST security category 5, SHA-256 and SHA-512, at most 2^24 signatures (draft SP 800-230, experimental)

SLH_DSA_SHAKE_256_24 = 'SLH-DSA-SHAKE-256-24'

NIST security category 5, SHAKE256, at most 2^24 signatures (draft SP 800-230, experimental)

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_128s = ParamSet.SLH_DSA_SHA2_128s

Same as ParamSet.SLH_DSA_SHA2_128s

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_128s = ParamSet.SLH_DSA_SHAKE_128s

Same as ParamSet.SLH_DSA_SHAKE_128s

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_128f = ParamSet.SLH_DSA_SHA2_128f

Same as ParamSet.SLH_DSA_SHA2_128f

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_128f = ParamSet.SLH_DSA_SHAKE_128f

Same as ParamSet.SLH_DSA_SHAKE_128f

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_192s = ParamSet.SLH_DSA_SHA2_192s

Same as ParamSet.SLH_DSA_SHA2_192s

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_192s = ParamSet.SLH_DSA_SHAKE_192s

Same as ParamSet.SLH_DSA_SHAKE_192s

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_192f = ParamSet.SLH_DSA_SHA2_192f

Same as ParamSet.SLH_DSA_SHA2_192f

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_192f = ParamSet.SLH_DSA_SHAKE_192f

Same as ParamSet.SLH_DSA_SHAKE_192f

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_256s = ParamSet.SLH_DSA_SHA2_256s

Same as ParamSet.SLH_DSA_SHA2_256s

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_256s = ParamSet.SLH_DSA_SHAKE_256s

Same as ParamSet.SLH_DSA_SHAKE_256s

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_256f = ParamSet.SLH_DSA_SHA2_256f

Same as ParamSet.SLH_DSA_SHA2_256f

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_256f = ParamSet.SLH_DSA_SHAKE_256f

Same as ParamSet.SLH_DSA_SHAKE_256f

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_128_24 = ParamSet.SLH_DSA_SHA2_128_24

Same as ParamSet.SLH_DSA_SHA2_128_24

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_128_24 = ParamSet.SLH_DSA_SHAKE_128_24

Same as ParamSet.SLH_DSA_SHAKE_128_24

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_192_24 = ParamSet.SLH_DSA_SHA2_192_24

Same as ParamSet.SLH_DSA_SHA2_192_24

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_192_24 = ParamSet.SLH_DSA_SHAKE_192_24

Same as ParamSet.SLH_DSA_SHAKE_192_24

Crypto.PublicKey.SLHDSA.SLH_DSA_SHA2_256_24 = ParamSet.SLH_DSA_SHA2_256_24

Same as ParamSet.SLH_DSA_SHA2_256_24

Crypto.PublicKey.SLHDSA.SLH_DSA_SHAKE_256_24 = ParamSet.SLH_DSA_SHAKE_256_24

Same as ParamSet.SLH_DSA_SHAKE_256_24

class Crypto.PublicKey.SLHDSA.SLHDSAKey(*, param_set, sk=None, pk=None, threads=1)

Class defining an SLH-DSA key (private or public). Do not instantiate directly. Use generate() or construct() instead.

Variables:

param_set (ParamSet) – The parameter set.

has_private()

True if this key can be used for making signatures.

Return type:

bool

property sk: bytes

The private key, encoded as in FIPS 205 (Figure 15): SK.seed, SK.prf, PK.seed and PK.root, each n bytes long.

property pk: bytes

The public key, encoded as in FIPS 205 (Figure 16): PK.seed and PK.root, each n bytes long.

public_key()

A matching SLH-DSA public key.

Return type:

SLHDSAKey

Returns:

a new SLHDSAKey object

export_key(*, format='DER', passphrase=None, protection=None, prot_params=None, randfunc=None, threads=1)

Export this SLH-DSA key, as defined in RFC 9909 (for pure SLH-DSA).

A public key is encoded as an X.509 SubjectPublicKeyInfo.

A private key is encoded as a PKCS#8 OneAsymmetricKey (in the clear, or encrypted if passphrase is set), which contains the private key of FIPS 205 (sk).

The parameter sets of SP 800-230 have no OID yet: their keys cannot be exported (ValueError).

Parameters:
  • format (string) –

    • 'DER' (default): binary encoding, as bytes.

    • 'PEM': textual encoding of RFC 7468, as a string, with the label PUBLIC KEY, PRIVATE KEY or ENCRYPTED PRIVATE KEY.

  • passphrase (bytes or string) – (Private keys only) The passphrase to protect the private key with PBES2 (PKCS#8 EncryptedPrivateKeyInfo).

  • protection (string) – (Private keys only) The encryption scheme, when passphrase is set. For all possible protection schemes, refer to the encryption parameters of PKCS#8. The default is 'PBKDF2WithHMAC-SHA256AndAES256-CBC'.

  • prot_params (dict) – (Private keys only) The parameters to derive the encryption key from the passphrase, when passphrase is set. For all possible values, refer to the encryption parameters of PKCS#8. The defaults meet the OWASP recommendations (with the default protection): there is no need to set them.

  • randfunc (callable) – (Private keys only) The RNG for the salt and the IV of the encryption. If None, Crypto.Random.get_random_bytes() is used.

  • threads (integer) – (Private keys only) The maximum number of threads used to derive the encryption key with scrypt (default: 1, no extra threads; 0 for all CPU cores). Only useful with a scrypt protection and a parallelization larger than 1 in prot_params. The output does not depend on the number of threads.

Warning

If you don’t provide a passphrase, the private key will be exported in the clear!

Return type:

Union[bytes, str]

Returns:

bytes (for 'DER') or a multi-line string (for 'PEM') with the encoded key.

Crypto.PublicKey.SLHDSA.generate(*, param_set, randfunc=None, threads=1)

Generate a new SLH-DSA private key (FIPS 205, Algorithm 21).

Parameters:
  • param_set (ParamSet) – Mandatory. The parameter set, for instance SLHDSA.SLH_DSA_SHA2_128s.

  • randfunc (callable) – Optional. The RNG to read the three seeds from (SK.seed, SK.prf and PK.seed, n bytes each, in this order). If None, Crypto.Random.get_random_bytes() is used.

  • threads (integer) – Optional. The maximum number of threads used to generate the key (default: 1, no extra threads; 0 for all CPU cores). The key does not depend on the number of threads.

Returns:

a new private key

Return type:

SLHDSAKey

Crypto.PublicKey.SLHDSA.construct(*, param_set, sk=None, pk=None, threads=1)

Build an SLH-DSA key (private or public) from its components.

Parameters:
  • param_set (ParamSet) – Mandatory. The parameter set, for instance SLHDSA.SLH_DSA_SHA2_128s.

  • sk (bytes) – The private key, encoded as in FIPS 205 (4 n bytes). Its consistency is checked: its PK.root must be the root of the hypertree, which takes as long as generating a key.

  • pk (bytes) – The public key, encoded as in FIPS 205 (2 n bytes).

  • threads (integer) – The maximum number of threads used to check the private key (default: 1, no extra threads; 0 for all CPU cores).

At least one of sk and pk must be present. If both are present, they must match, otherwise ValueError is raised.

Returns:

a new SLH-DSA key object

Return type:

SLHDSAKey

Crypto.PublicKey.SLHDSA.import_key(encoded, passphrase=None, *, max_iteration_count=None, threads=1, max_memory=None)

Import an SLH-DSA key (public or private), as defined in RFC 9909 (for pure SLH-DSA).

Parameters:
  • encoded (bytes or string) –

    The SLH-DSA key to import, in DER format (bytes), or in PEM format (RFC 7468, as a string or as bytes). It can be:

    • For a public key: an X.509 SubjectPublicKeyInfo, or an X.509 certificate (the signature of the certificate is not checked).

    • For a private key: a PKCS#8 OneAsymmetricKey (version 1 or 2, in the clear or encrypted).

    The OID must be one of id-slh-dsa-*: the keys for HashSLH-DSA only (id-hash-slh-dsa-*) are not supported. The parameters of the AlgorithmIdentifier must be absent (or NULL, which is tolerated).

    In PEM format, the label must match the content: PUBLIC KEY, CERTIFICATE (or X509 CERTIFICATE, X.509 CERTIFICATE), PRIVATE KEY or ENCRYPTED PRIVATE KEY. The legacy PEM encryption (with the Proc-Type header) is not supported.

    A private key is checked as with construct() (its PK.root must be the root of the hypertree), which takes as long as generating a key. If it also contains the public key (in the publicKey field of a OneAsymmetricKey version 2), it must match.

  • passphrase (bytes or string) – The passphrase to decrypt an encrypted private key (PKCS#8 EncryptedPrivateKeyInfo). It is ignored if the key is not encrypted.

  • max_iteration_count (integer) – The maximum value allowed for the PBKDF2 iteration count or the scrypt cost N·r·p/8 (that is, N for the usual r=8 and p=1) of an encrypted private key. A malicious key could require an extremely high number of iterations, tying up the CPU for hours. The default value is None: a limit for each KDF, which keeps the key derivation to about one minute at most (see the limits for decryption). Set it to 0 to disable the check.

  • threads (integer) – The maximum number of threads used to check a private key, and to derive the decryption key with scrypt (default: 1, no extra threads; 0 for all CPU cores). For scrypt, only a private key protected with a parallelization parameter larger than 1 can use them.

  • max_memory (integer) – The maximum memory (in bytes) for the key derivation of an encrypted private key, as a limit on the total of all threads together. The default value is None (a limit of 256 MiB). Set it to 0 to disable the check.

Returns:

a new SLH-DSA key object

Return type:

SLHDSAKey

Raises:
  • PassphraseRequiredError – (a ValueError) when the private key is encrypted, but no passphrase was provided.

  • IncorrectPassphraseError – (a ValueError) when the private key cannot be decrypted with the passphrase (most likely, the passphrase is wrong).

  • ValueError – when the key cannot be parsed, it is not an SLH-DSA key (or it is a HashSLH-DSA key), or its components do not match.