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 |
|
1 |
32 |
64 |
7856 |
SLH-DSA-SHAKE-128s |
|
1 |
32 |
64 |
7856 |
SLH-DSA-SHA2-128f |
|
1 |
32 |
64 |
17088 |
SLH-DSA-SHAKE-128f |
|
1 |
32 |
64 |
17088 |
SLH-DSA-SHA2-192s |
|
3 |
48 |
96 |
16224 |
SLH-DSA-SHAKE-192s |
|
3 |
48 |
96 |
16224 |
SLH-DSA-SHA2-192f |
|
3 |
48 |
96 |
35664 |
SLH-DSA-SHAKE-192f |
|
3 |
48 |
96 |
35664 |
SLH-DSA-SHA2-256s |
|
5 |
64 |
128 |
29792 |
SLH-DSA-SHAKE-256s |
|
5 |
64 |
128 |
29792 |
SLH-DSA-SHA2-256f |
|
5 |
64 |
128 |
49856 |
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 |
|
1 |
32 |
64 |
3856 |
SLH-DSA-SHAKE-128-24 |
|
1 |
32 |
64 |
3856 |
SLH-DSA-SHA2-192-24 |
|
3 |
48 |
96 |
7752 |
SLH-DSA-SHAKE-192-24 |
|
3 |
48 |
96 |
7752 |
SLH-DSA-SHA2-256-24 |
|
5 |
64 |
128 |
14944 |
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
ssets have small signatures and slow signing, thefsets have fast signing and larger signatures.The
-24sets 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()orconstruct()instead.- Variables:
param_set (
ParamSet) – The parameter set.
- 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.
- 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 ifpassphraseis 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, asbytes.'PEM': textual encoding of RFC 7468, as a string, with the labelPUBLIC KEY,PRIVATE KEYorENCRYPTED 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
passphraseis 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
passphraseis set. For all possible values, refer to the encryption parameters of PKCS#8. The defaults meet the OWASP recommendations (with the defaultprotection): 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
protectionand aparallelizationlarger than 1 inprot_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!
- 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 instanceSLHDSA.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:
- 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 instanceSLHDSA.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
skandpkmust be present. If both are present, they must match, otherwiseValueErroris raised.- Returns:
a new SLH-DSA key object
- Return type:
- 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 asbytes). 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 theAlgorithmIdentifiermust be absent (orNULL, which is tolerated).In PEM format, the label must match the content:
PUBLIC KEY,CERTIFICATE(orX509 CERTIFICATE,X.509 CERTIFICATE),PRIVATE KEYorENCRYPTED PRIVATE KEY. The legacy PEM encryption (with theProc-Typeheader) 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 thepublicKeyfield of aOneAsymmetricKeyversion 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
0to 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
0to disable the check.
- Returns:
a new SLH-DSA key object
- Return type:
- 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.