Danger
This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.
DSA
Note
DSA is a legacy algorithm and should generally be avoided in favor of choices like EdDSA using curve25519 or ECDSA.
DSA is a public-key algorithm for signing messages.
Generation
- cryptography.hazmat.primitives.asymmetric.dsa.generate_private_key(key_size)[source]
Added in version 0.5.
Changed in version 3.0: Added support for 4096-bit keys for some legacy applications that continue to use DSA despite the wider cryptographic community’s ongoing protestations.
Generate a DSA private key from the given key size. This function will generate a new set of parameters and key in one step.
- Parameters:
key_size (int) – The length of the modulus in bits. It should be either 1024, 2048, 3072, or 4096. For keys generated in 2015 this should be at least 2048 (See page 41).
- Returns:
An instance of
DSAPrivateKey
.
- cryptography.hazmat.primitives.asymmetric.dsa.generate_parameters(key_size)[source]
Added in version 0.5.
Changed in version 3.0: Added support for 4096-bit keys for some legacy applications that continue to use DSA despite the wider cryptographic community’s ongoing protestations.
Generate DSA parameters.
- Parameters:
key_size (int) – The length of
p
. It should be either 1024, 2048, 3072, or 4096. For keys generated in 2015 this should be at least 2048 (See page 41).- Returns:
An instance of
DSAParameters
.
Signing
Using a DSAPrivateKey
instance.
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import dsa
>>> private_key = dsa.generate_private_key(
... key_size=1024,
... )
>>> data = b"this is some data I'd like to sign"
>>> signature = private_key.sign(
... data,
... hashes.SHA256()
... )
The signature
is a bytes
object, whose contents is DER encoded as
described in RFC 3279. This can be decoded using
decode_dss_signature()
.
If your data is too large to be passed in a single call, you can hash it
separately and pass that value using
Prehashed
.
>>> from cryptography.hazmat.primitives.asymmetric import utils
>>> chosen_hash = hashes.SHA256()
>>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
>>> sig = private_key.sign(
... digest,
... utils.Prehashed(chosen_hash)
... )
Verification
Verification is performed using a
DSAPublicKey
instance.
You can get a public key object with
load_pem_public_key()
,
load_der_public_key()
,
public_key()
, or
public_key()
.
>>> public_key = private_key.public_key()
>>> public_key.verify(
... signature,
... data,
... hashes.SHA256()
... )
verify()
takes the signature in the same format as is returned by
sign()
.
verify()
will raise an InvalidSignature
exception if the signature isn’t valid.
If your data is too large to be passed in a single call, you can hash it
separately and pass that value using
Prehashed
.
>>> chosen_hash = hashes.SHA256()
>>> hasher = hashes.Hash(chosen_hash)
>>> hasher.update(b"data & ")
>>> hasher.update(b"more data")
>>> digest = hasher.finalize()
>>> public_key.verify(
... sig,
... digest,
... utils.Prehashed(chosen_hash)
... )
Numbers
- class cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers(p, q, g)[source]
Added in version 0.5.
The collection of integers that make up a set of DSA parameters.
- parameters()
- Returns:
A new instance of
DSAParameters
.
- class cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers(y, parameter_numbers)[source]
Added in version 0.5.
The collection of integers that make up a DSA public key.
- parameter_numbers
- Type:
The
DSAParameterNumbers
associated with the public key.
- public_key()
- Returns:
A new instance of
DSAPublicKey
.
- class cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers(x, public_numbers)[source]
Added in version 0.5.
The collection of integers that make up a DSA private key.
Warning
Revealing the value of
x
will compromise the security of any cryptographic operations performed.- public_numbers
- Type:
The
DSAPublicNumbers
associated with the private key.
- private_key()
- Returns:
A new instance of
DSAPrivateKey
.
Key interfaces
- class cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters[source]
Added in version 0.3.
DSA parameters.
- generate_private_key()[source]
Added in version 0.5.
Generate a DSA private key. This method can be used to generate many new private keys from a single set of parameters.
- Returns:
An instance of
DSAPrivateKey
.
- parameter_numbers()[source]
Create a
DSAParameterNumbers
object.- Returns:
A
DSAParameterNumbers
instance.
- class cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey[source]
Added in version 0.3.
A DSA private key.
- public_key()[source]
- Returns:
An DSA public key object corresponding to the values of the private key.
- sign(data, algorithm)[source]
Added in version 1.5.
Changed in version 1.6:
Prehashed
can now be used as analgorithm
.Sign one block of data which can be verified later by others using the public key.
- Parameters:
data (bytes-like) – The message string to sign.
algorithm – An instance of
HashAlgorithm
orPrehashed
if thedata
you want to sign has already been hashed.
- Return bytes:
Signature.
- private_numbers()[source]
Create a
DSAPrivateNumbers
object.- Returns:
A
DSAPrivateNumbers
instance.
- private_bytes(encoding, format, encryption_algorithm)[source]
Allows serialization of the key to bytes. Encoding (
PEM
orDER
), format (TraditionalOpenSSL
, orPKCS8
) and encryption algorithm (such asBestAvailableEncryption
orNoEncryption
) are chosen to define the exact serialization.- Parameters:
encoding – A value from the
Encoding
enum.format – A value from the
PrivateFormat
enum.encryption_algorithm – An instance of an object conforming to the
KeySerializationEncryption
interface.
- Return bytes:
Serialized key.
- class cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey[source]
Added in version 0.3.
A DSA public key.
- public_numbers()[source]
Create a
DSAPublicNumbers
object.- Returns:
A
DSAPublicNumbers
instance.
- public_bytes(encoding, format)[source]
Allows serialization of the key to bytes. Encoding (
PEM
orDER
) and format (SubjectPublicKeyInfo
) are chosen to define the exact serialization.- Parameters:
encoding – A value from the
Encoding
enum.format – A value from the
PublicFormat
enum.
- Return bytes:
Serialized key.
- verify(signature, data, algorithm)[source]
Added in version 1.5.
Changed in version 1.6:
Prehashed
can now be used as analgorithm
.Verify one block of data was signed by the private key associated with this public key.
- Parameters:
signature (bytes-like) – The signature to verify.
data (bytes-like) – The message string that was signed.
algorithm – An instance of
HashAlgorithm
orPrehashed
if thedata
you want to sign has already been hashed.
- Returns:
None
- Raises:
cryptography.exceptions.InvalidSignature – If the signature does not validate.