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¶
DSA is a public-key algorithm for signing messages.
Generation¶
-
cryptography.hazmat.primitives.asymmetric.dsa.
generate_private_key
(key_size, backend)[source]¶ New in version 0.5.
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 or 3072. For keys generated in 2015 this should be at least 2048 (See page 41). Note that some applications (such as SSH) have not yet gained support for larger key sizes specified in FIPS 186-3 and are still restricted to only the 1024-bit keys specified in FIPS 186-2.
- backend – An 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)[source]¶ New in version 0.5.
Generate DSA parameters using the provided
backend
.Parameters: - key_size (int) – The length of
q
. It should be either 1024, 2048 or 3072. For keys generated in 2015 this should be at least 2048 (See page 41). Note that some applications (such as SSH) have not yet gained support for larger key sizes specified in FIPS 186-3 and are still restricted to only the 1024-bit keys specified in FIPS 186-2. - backend – An 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.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import dsa
>>> private_key = dsa.generate_private_key(
... key_size=1024,
... backend=default_backend()
... )
>>> 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, default_backend())
>>> 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, default_backend())
>>> 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]¶ New in version 0.5.
The collection of integers that make up a set of DSA parameters.
-
parameters
(backend)[source]¶ Parameters: backend – An instance of DSABackend
.Returns: A new instance of DSAParameters
.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPublicNumbers
(y, parameter_numbers)[source]¶ 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)[source]¶ Parameters: backend – An instance of DSABackend
.Returns: A new instance of DSAPublicKey
.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPrivateNumbers
(x, public_numbers)[source]¶ 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)[source]¶ Parameters: backend – An instance of DSABackend
.Returns: A new instance of DSAPrivateKey
.
-
Key interfaces¶
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAParameters
[source]¶ New in version 0.3.
DSA parameters.
-
generate_private_key
()[source]¶ 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
.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAParametersWithNumbers
[source]¶ New in version 0.5.
Extends
DSAParameters
.-
parameter_numbers
()[source]¶ Create a
DSAParameterNumbers
object.Returns: A DSAParameterNumbers
instance.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPrivateKey
[source]¶ New in version 0.3.
A DSA private key. A DSA private key that is not an opaque key also implements
DSAPrivateKeyWithSerialization
to provide serialization methods.-
public_key
()[source]¶ Returns: DSAPublicKey
An DSA public key object corresponding to the values of the private key.
-
parameters
()[source]¶ Returns: DSAParameters
The DSAParameters object associated with this private key.
-
sign
(data, algorithm)[source]¶ 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.
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPrivateKeyWithSerialization
[source]¶ New in version 0.8.
This interface contains additional methods relating to serialization. Any object with this interface also has all the methods from
DSAPrivateKey
.-
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.
- encoding – A value from the
-
-
class
cryptography.hazmat.primitives.asymmetric.dsa.
DSAPublicKey
[source]¶ New in version 0.3.
A DSA public key.
-
parameters
()[source]¶ Returns: DSAParameters
The DSAParameters object associated with this 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.
- encoding – A value from the
-
verify
(signature, data, algorithm)[source]¶ 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
.