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)

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

  Returns:

    An instance of `DSAPrivateKey`.

cryptography.hazmat.primitives.asymmetric.dsa.generate_parameters(key_size)

  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.

  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)

  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()
    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()
    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()
    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`, 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.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.

    Returns:

      None

    Raises:

      cryptography.exceptions.InvalidSignature – If the signature does not validate.