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 implement `DSABackend`

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 implement `DSABackend`

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

  p
    Type

      int

    The public modulus.

  q
    Type

      int

    The sub-group order.

  g
    Type

      int

    The generator.

  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.

  y
    Type

      int

    The public value `y`.

  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.

  x
    Type

      int

    The private value `x`.

  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.

  key_size
    Type

      int

    The bit length of `q`.

  sign(data, algorithm)

    New in version 1.5.

    Changed in version 1.6: `Prehashed` can now be used as an `algorithm`.

    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` or `Prehashed` if the `data` 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` or `DER`), format ( `TraditionalOpenSSL`, `OpenSSH` or `PKCS8`) and encryption algorithm (such as `BestAvailableEncryption` or `NoEncryption`) 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.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.

  key_size
    Type

      int

    The bit length of `q`.

  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` or `DER`) 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)

    New in version 1.5.

    Changed in version 1.6: `Prehashed` can now be used as an `algorithm`.

    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` or `Prehashed` if the `data` 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`.