Dsa class¶

class crsyspqc.Dsa¶

Digital Signature Algorithm (DSA) functions.

class Alg¶

DSA signature algorithms.

ML_DSA_44: int = 32¶: ML-DSA-44 from FIPS.204 (based on Dilithium2)

ML_DSA_65: int = 33¶: ML-DSA-65 from FIPS.204 (based on Dilithium3)

ML_DSA_87: int = 34¶: ML-DSA-87 from FIPS.204 (based on Dilithium5)

SLH_DSA_SHA2_128S: int = 50¶: SLH-DSA-SHA2-128s from FIPS.205

SLH_DSA_SHA2_128F: int = 51¶: SLH-DSA-SHA2-128f from FIPS.205

SLH_DSA_SHA2_192S: int = 52¶: SLH-DSA-SHA2-192s from FIPS.205

SLH_DSA_SHA2_192F: int = 53¶: SLH-DSA-SHA2-192f from FIPS.205

SLH_DSA_SHA2_256S: int = 54¶: SLH-DSA-SHA2-256s from FIPS.205

SLH_DSA_SHA2_256F: int = 55¶: SLH-DSA-SHA2-256f from FIPS.205

SLH_DSA_SHAKE_128S: int = 58¶: SLH-DSA-SHAKE-128s from FIPS.205

SLH_DSA_SHAKE_128F: int = 59¶: SLH-DSA-SHAKE-128f from FIPS.205

SLH_DSA_SHAKE_192S: int = 60¶: SLH-DSA-SHAKE-192s from FIPS.205

SLH_DSA_SHAKE_192F: int = 61¶: SLH-DSA-SHAKE-192f from FIPS.205

SLH_DSA_SHAKE_256S: int = 62¶: SLH-DSA-SHAKE-256s from FIPS.205

SLH_DSA_SHAKE_256F: int = 63¶: SLH-DSA-SHAKE-256f from FIPS.205

class SigOpts¶

Signature options.

DEFAULT = 0¶: Default options.

DETERMINISTIC = 8192¶: Use deterministic variant when signing [default = add randomness].

INTERNAL = 67108864¶: Use Sign_internal or Verify_internal algorithm (for testing purposes).

EXTERNAL_MU = 134217728¶: Use ExternalMu-ML-DSA.Sign or ExternalMu-ML-DSA.Verify algorithm (ML-DSA only).

class PreHashAlg¶

Hash function identifiers for pre-hash signing.

SHA256: int = 1¶: SHA-256 from FIPS.180-4

SHA384: int = 2¶: SHA-284 from FIPS.180-4

SHA512: int = 3¶: SHA-512 from FIPS.180-4

SHA224: int = 4¶: SHA-224 from FIPS.180-4

SHA512_224: int = 5¶: SHA-512/224 from FIPS.180-4

SHA512_256: int = 6¶: SHA-512/256 from FIPS.180-4

SHA3_224: int = 7¶: SHA3-224 from FIPS.202

SHA3_256: int = 8¶: SHA3-256 from FIPS.202

SHA3_384: int = 9¶: SHA3-384 from FIPS.202

SHA3_512: int = 10¶: SHA3-512 from FIPS.202

SHAKE128_256: int = 11¶: SHAKE-128-256 from FIPS.202

SHAKE256_512: int = 12¶: SHAKE-256-512 from FIPS.202

static keygen(alg, params='')¶

Generate a DSA signing key pair (pk, sk).

Parameters:

alg (Dsa.Alg) – Signature algorithm.
params (str) – Optional parameter to pass known test random material encoded in hexadecimal [default = add fresh randomness]. For SLH-DSA pass a 3*n value SK.seed||SK.prf||PK.seed (48/72/96 bytes). For ML-DSA pass a 32-byte value seed (denoted ξ in FIPS.204).

Returns:

Key pair.

Return type:

bytes

static sign(alg, msg, privatekey, opts=0, context=b'', params='')¶

Generate a DSA signature over a message.

Parameters:

alg (Dsa.Alg) – DSA algorithm.
msg (bytes) – Message to be signed.
privatekey (bytes) – Private key sk.
opts (Dsa.SigOpts) – Signature options.
context (bytes) – Optional context string (maximum 255 bytes)
params (str) – Optional parameter to pass known test random material encoded in hexadecimal [default = add fresh randomness if in hedged mode; else ignored]. For SLH-DSA pass a value addrnd of exactly n bytes (16/24/32 bytes). For ML-DSA pass a 32-byte value rnd.

Returns:

Signature value.

Return type:

bytes

Raises:

Error – If parameters are bad, wrong lengths, etc.

When using the ExternalMu-ML-DSA.Sign option (Dsa.SigOps.EXTERNAL_MU), pass the value of mu instead of the message (ML-DSA only). This must be exactly 64 bytes long. Caller is responsible for computing the value of mu independently prior to input.

For ML-DSA, the private key sk may be passed in expanded form (2560|4032|4896 bytes) or as a 32-byte seed. The key form is detected automatically by its length.

static sign_prehash(alg, msg, hashAlg, privatekey, opts=0, context=b'', params='')¶

Generate a DSA signature over a pre-hashed message.

For the pre-hash variant, the hash digest of the message is passed instead of the message itself. Caller is responsible for computing the hash digest independently prior to input. The hash function used must be identifed in the hashAlg parameter.

Parameters:

alg (Dsa.Alg) – DSA algorithm.
msg (bytes) – Hash digest of message to be signed PH_M = PH(M).
hashAlg (Dsa.PreHashAlg) – Pre-hash function used to create digest.
privatekey (bytes) – Private key sk.
opts (Dsa.SigOpts) – Signature options.
context (bytes) – Optional context string (maximum 255 bytes)
params (str) – Optional parameter to pass known test random material encoded in hexadecimal [default = add fresh randomness if in hedged mode; else ignored]. For SLH-DSA pass a value addrnd of exactly n bytes (16/24/32 bytes). For ML-DSA pass a 32-byte value rnd.

Returns:

Signature value.

Return type:

bytes

Raises:

Error – If parameters are bad, wrong lengths, etc.

For ML-DSA, the private key sk may be passed in expanded form (2560|4032|4896 bytes) or as a 32-byte seed. The key form is detected automatically by its length.

static verify(alg, signature, msg, publickey, context=b'', opts=0)¶

Verify a DSA signature.

Parameters:

alg (Dsa.Alg) – DSA algorithm.
signature (bytes) – Signature value
msg (bytes) – Message to be verified.
publickey (bytes) – Public key pk
context (bytes) – Same context string as used when signing (maximum 255 bytes).
opts (Dsa.SigOpts) – Verify options.

Returns:

True if successfully verified or False if signature is invalid.

Return type:

bool

Raises:

Error – If parameters are bad, wrong lengths, etc.

When using the ExternalMu-ML-DSA.Verify option (Dsa.SigOps.EXTERNAL_MU), pass the value of mu instead of the message (ML-DSA only). This must be exactly 64 bytes long. Caller is responsible for computing the value of mu independently prior to input.

static verify_prehash(alg, signature, msg, hashAlg, publickey, context=b'', opts=0)¶

Verify a DSA signature for a pre-hashed message.

For the pre-hash variant, the hash digest of the message is passed instead of the message itself. Caller is responsible for computing the hash digest independently prior to input. The hash function used must be identifed in the hashAlg parameter.

Parameters:

alg (Dsa.Alg) – DSA algorithm.
signature (bytes) – Signature value
msg (bytes) – Hash digest of message to be verified PH_M = PH(M).
hashAlg (Dsa.PreHashAlg) – Pre-hash function used to create digest.
publickey (bytes) – Public key pk
context (bytes) – Same context string as used when signing (maximum 255 bytes).
opts (Dsa.SigOpts) – Verify options.

Returns:

True if successfully verified or False if signature is invalid.

Return type:

bool

Raises:

Error – If parameters are bad, wrong lengths, etc.

static publickey_from_private(alg, privatekey)¶

Extract the public key from a private key.

Parameters:

alg (Dsa.Alg) – DSA algorithm.
privatekey (bytes) – Private key sk.

Returns:

Public key pk.

Return type:

bytes

static publickey_size(alg)¶

Return length of public key in bytes for given algorithm.

Parameters:: alg (Dsa.Alg) – Signature algorithm.
Returns:: length in bytes.
Return type:: int

Example

>>> Dsa.publickey_size(Dsa.Alg.SLH_DSA_SHA2_128F)
32

static privatekey_size(alg)¶

Return length of private key in bytes for given algorithm.

Parameters:: alg (Dsa.Alg) – Signature algorithm.
Returns:: length in bytes.
Return type:: int

Example

>>> Dsa.privatekey_size(Dsa.Alg.ML_DSA_65)
4032

static signature_size(alg)¶

Return length of signature in bytes for given algorithm.

Parameters:: alg (Dsa.Alg) – Signature algorithm.
Returns:: length in bytes.
Return type:: int

Example

>>> Dsa.signature_size(Dsa.Alg.SLH_DSA_SHAKE_256F)
49856

static alg_name(alg)¶

Get the algorithm name from its Alg code.

Parameters:: alg (Dsa.Alg) – Signature algorithm.
Returns:: Algorithm name.
Return type:: str

Example

>>> Dsa.alg_name(Dsa.Alg.SLH_DSA_SHAKE_256F)
'SLH-DSA-SHAKE-256f'
>>> Dsa.alg_name(Dsa.Alg.ML_DSA_65)
'ML-DSA-65'