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
SLHDSASigSchemethat 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). IfTrue, 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 withdeterministic=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:
- 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
Trueif this signature object can be used for signing messages.- Return type:
- sign(msg_or_hash)¶
Compute the SLH-DSA signature of a message.
- Parameters:
msg_or_hash (bytes or a hash object) –
One of:
the message to sign (
bytes, for SLH-DSA);a hash object that has processed the message (for HashSLH-DSA), of
Crypto.Hash.SHA224,Crypto.Hash.SHA256,Crypto.Hash.SHA384,Crypto.Hash.SHA512(also truncated),Crypto.Hash.SHA3_224,Crypto.Hash.SHA3_256,Crypto.Hash.SHA3_384,Crypto.Hash.SHA3_512,Crypto.Hash.SHAKE128orCrypto.Hash.SHAKE256. The output of a SHAKE object must not have been read yet.
- Return type:
- 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:
- Raises:
ValueError – if the signature is not authentic.
- Return type: