dsa.rst

DSA

cryptography.hazmat.primitives.asymmetric.dsa

Note

DSA is a legacy algorithm and should generally be avoided in favor of choices like EdDSA using curve25519</hazmat/primitives/asymmetric/ed25519> or ECDSA</hazmat/primitives/asymmetric/ec>.

DSA is a public-key algorithm for signing messages.

Generation

generate_private_key(key_size, backend=None)

0.5

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.

param int key_size

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).

param backend

An optional instance of ~cryptography.hazmat.backends.interfaces.DSABackend.

return

An instance of ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.

raises cryptography.exceptions.UnsupportedAlgorithm

This is raised if the provided backend does not implement ~cryptography.hazmat.backends.interfaces.DSABackend

generate_parameters(key_size, backend=None)

0.5

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.

param int key_size

The length of ~DSAParameterNumbers.q. It should be either 1024, 2048, 3072, or 4096. For keys generated in 2015 this should be at least 2048 (See page 41).

param backend

An optional instance of ~cryptography.hazmat.backends.interfaces.DSABackend.

return

An instance of ~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters.

raises cryptography.exceptions.UnsupportedAlgorithm

This is raised if the provided backend does not implement ~cryptography.hazmat.backends.interfaces.DSABackend

Signing

Using a ~cryptography.hazmat.primitives.asymmetric.dsa.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 3279. This can be decoded using ~cryptography.hazmat.primitives.asymmetric.utils.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 ~cryptography.hazmat.primitives.asymmetric.utils.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 ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey instance. You can get a public key object with ~cryptography.hazmat.primitives.serialization.load_pem_public_key, ~cryptography.hazmat.primitives.serialization.load_der_public_key, ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers.public_key , or ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.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 ~cryptography.exceptions.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 ~cryptography.hazmat.primitives.asymmetric.utils.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

0.5

The collection of integers that make up a set of DSA parameters.

p

type

int

The public modulus.

q

type

int

The sub-group order.

g

type

int

The generator.

parameters(backend=None)

param backend

An optional instance of ~cryptography.hazmat.backends.interfaces.DSABackend.

returns

A new instance of ~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters.

0.5

The collection of integers that make up a DSA public key.

y

type

int

The public value y.

parameter_numbers

type

~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers

The ~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers associated with the public key.

public_key(backend=None)

param backend

An optional instance of ~cryptography.hazmat.backends.interfaces.DSABackend.

returns

A new instance of ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey.

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.

x

type

int

The private value x.

public_numbers

type

~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers

The ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers associated with the private key.

private_key(backend=None)

param backend

An optional instance of ~cryptography.hazmat.backends.interfaces.DSABackend.

returns

A new instance of ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.

Key interfaces

0.3

DSA parameters.

generate_private_key()

0.5

Generate a DSA private key. This method can be used to generate many new private keys from a single set of parameters.

return

An instance of ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.

0.5

Extends DSAParameters.

parameter_numbers()

Create a ~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers object.

returns

A ~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers instance.

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()

return

~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey

An DSA public key object corresponding to the values of the private key.

parameters()

return

~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters

The DSAParameters object associated with this private key.

key_size

type

int

The bit length of ~DSAParameterNumbers.q.

sign(data, algorithm)

1.5

1.6 ~cryptography.hazmat.primitives.asymmetric.utils.Prehashed can now be used as an algorithm.

Sign one block of data which can be verified later by others using the public key.

param bytes data

The message string to sign.

param algorithm

An instance of ~cryptography.hazmat.primitives.hashes.HashAlgorithm or ~cryptography.hazmat.primitives.asymmetric.utils.Prehashed if the data you want to sign has already been hashed.

return bytes

Signature.

0.8

This interface contains additional methods relating to serialization. Any object with this interface also has all the methods from DSAPrivateKey.

private_numbers()

Create a ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers object.

returns

A ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers instance.

private_bytes(encoding, format, encryption_algorithm)

Allows serialization of the key to bytes. Encoding ( ~cryptography.hazmat.primitives.serialization.Encoding.PEM or ~cryptography.hazmat.primitives.serialization.Encoding.DER), format ( ~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL, ~cryptography.hazmat.primitives.serialization.PrivateFormat.OpenSSH or ~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8) and encryption algorithm (such as ~cryptography.hazmat.primitives.serialization.BestAvailableEncryption or ~cryptography.hazmat.primitives.serialization.NoEncryption) are chosen to define the exact serialization.

param encoding

A value from the ~cryptography.hazmat.primitives.serialization.Encoding enum.

param format

A value from the ~cryptography.hazmat.primitives.serialization.PrivateFormat enum.

param encryption_algorithm

An instance of an object conforming to the ~cryptography.hazmat.primitives.serialization.KeySerializationEncryption interface.

return bytes

Serialized key.

0.3

A DSA public key.

key_size

type

int

The bit length of ~DSAParameterNumbers.q.

parameters()

return

~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters

The DSAParameters object associated with this public key.

public_numbers()

Create a ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers object.

returns

A ~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers instance.

public_bytes(encoding, format)

Allows serialization of the key to bytes. Encoding ( ~cryptography.hazmat.primitives.serialization.Encoding.PEM or ~cryptography.hazmat.primitives.serialization.Encoding.DER) and format ( ~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo) are chosen to define the exact serialization.

param encoding

A value from the ~cryptography.hazmat.primitives.serialization.Encoding enum.

param format

A value from the ~cryptography.hazmat.primitives.serialization.PublicFormat enum.

return bytes

Serialized key.

verify(signature, data, algorithm)

1.5

1.6 ~cryptography.hazmat.primitives.asymmetric.utils.Prehashed can now be used as an algorithm.

Verify one block of data was signed by the private key associated with this public key.

param bytes signature

The signature to verify.

param bytes data

The message string that was signed.

param algorithm

An instance of ~cryptography.hazmat.primitives.hashes.HashAlgorithm or ~cryptography.hazmat.primitives.asymmetric.utils.Prehashed if the data you want to sign has already been hashed.

raises cryptography.exceptions.InvalidSignature

If the signature does not validate.

0.8

Alias for DSAPublicKey.