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, backend=None)¶ New 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).
- backend – An optional instance of
DSABackend
.
Returns: An instance of
DSAPrivateKey
.Raises: cryptography.exceptions.UnsupportedAlgorithm – This is raised if the provided
backend
does not implementDSABackend
-
cryptography.hazmat.primitives.asymmetric.dsa.
generate_parameters
(key_size, backend=None)¶ New 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 using the provided
backend
.Parameters: - key_size (int) – The length of
q
. It should be either 1024, 2048, 3072, or 4096. For keys generated in 2015 this should be at least 2048 (See page 41). - backend – An optional instance of
DSABackend
.
Returns: An instance of
DSAParameters
.Raises: cryptography.exceptions.UnsupportedAlgorithm – This is raised if the provided
backend
does not implementDSABackend
- key_size (int) – The length of
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)¶ New in version 0.5.
The collection of integers that make up a set of DSA parameters.
-
parameters
(backend=None)¶ Parameters: backend – An optional instance of DSABackend
.Returns: A new instance of DSAParameters
.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPublicNumbers
(y, parameter_numbers)¶ New in version 0.5.
The collection of integers that make up a DSA public key.
-
parameter_numbers
¶ Type: DSAParameterNumbers
The
DSAParameterNumbers
associated with the public key.
-
public_key
(backend=None)¶ Parameters: backend – An optional instance of DSABackend
.Returns: A new instance of DSAPublicKey
.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPrivateNumbers
(x, public_numbers)¶ New 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: DSAPublicNumbers
The
DSAPublicNumbers
associated with the private key.
-
private_key
(backend=None)¶ Parameters: backend – An optional instance of DSABackend
.Returns: A new instance of DSAPrivateKey
.
-
Key interfaces¶
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAParameters
¶ New in version 0.3.
DSA parameters.
-
generate_private_key
()¶ New 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
()¶ Create a
DSAParameterNumbers
object.Returns: A DSAParameterNumbers
instance.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPrivateKey
¶ New in version 0.3.
A DSA private key.
-
public_key
()¶ Returns: DSAPublicKey
An DSA public key object corresponding to the values of the private key.
-
parameters
()¶ Returns: DSAParameters
The DSAParameters object associated with this private key.
-
sign
(data, algorithm)¶ New 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) – 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
()¶ Create a
DSAPrivateNumbers
object.Returns: A DSAPrivateNumbers
instance.
-
private_bytes
(encoding, format, encryption_algorithm)¶ Allows serialization of the key to bytes. Encoding (
PEM
orDER
), format (TraditionalOpenSSL
,OpenSSH
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.
- encoding – A value from the
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPrivateKeyWithSerialization
¶ New in version 0.8.
Alias for
DSAPrivateKey
.
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPublicKey
¶ New in version 0.3.
A DSA public key.
-
parameters
()¶ Returns: DSAParameters
The DSAParameters object associated with this public key.
-
public_numbers
()¶ Create a
DSAPublicNumbers
object.Returns: A DSAPublicNumbers
instance.
-
public_bytes
(encoding, format)¶ 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.
- encoding – A value from the
-
verify
(signature, data, algorithm)¶ New 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) – The signature to verify.
- data (bytes) – The message string that was signed.
- algorithm – An instance of
HashAlgorithm
orPrehashed
if thedata
you want to sign has already been hashed.
Raises: cryptography.exceptions.InvalidSignature – If the signature does not validate.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPublicKeyWithSerialization
¶ New in version 0.8.
Alias for
DSAPublicKey
.