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.

# X448 key exchange

X448 is an elliptic curve Diffie-Hellman key exchange using Curve448. It allows two parties to jointly agree on a shared secret using an insecure channel.

## Exchange Algorithm

For most applications the `shared_key` should be passed to a key derivation function. This allows mixing of additional information into the key, derivation of multiple keys, and destroys any structure that may be present.

    >>> from cryptography.hazmat.primitives import hashes
    >>> from cryptography.hazmat.primitives.asymmetric.x448 import X448PrivateKey
    >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
    >>> # Generate a private key for use in the exchange.
    >>> private_key = X448PrivateKey.generate()
    >>> # In a real handshake the peer_public_key will be received from the
    >>> # other party. For this example we'll generate another private key and
    >>> # get a public key from that. Note that in a DH handshake both peers
    >>> # must agree on a common set of parameters.
    >>> peer_public_key = X448PrivateKey.generate().public_key()
    >>> shared_key = private_key.exchange(peer_public_key)
    >>> # Perform key derivation.
    >>> derived_key = HKDF(
    ...     algorithm=hashes.SHA256(),
    ...     length=32,
    ...     salt=None,
    ...     info=b'handshake data',
    ... ).derive(shared_key)
    >>> # For the next handshake we MUST generate another private key.
    >>> private_key_2 = X448PrivateKey.generate()
    >>> peer_public_key_2 = X448PrivateKey.generate().public_key()
    >>> shared_key_2 = private_key_2.exchange(peer_public_key_2)
    >>> derived_key_2 = HKDF(
    ...     algorithm=hashes.SHA256(),
    ...     length=32,
    ...     salt=None,
    ...     info=b'handshake data',
    ... ).derive(shared_key_2)

## Key interfaces

class cryptography.hazmat.primitives.asymmetric.x448.X448PrivateKey

  New in version 2.5.

  classmethod generate()

    Generate an X448 private key.

    Returns

      `X448PrivateKey`

  classmethod from_private_bytes(data)
    Parameters

      data (bytes-like) – 56 byte private key.

    Returns

      `X448PrivateKey`

        >>> from cryptography.hazmat.primitives import serialization
        >>> from cryptography.hazmat.primitives.asymmetric import x448
        >>> private_key = x448.X448PrivateKey.generate()
        >>> private_bytes = private_key.private_bytes(
        ...     encoding=serialization.Encoding.Raw,
        ...     format=serialization.PrivateFormat.Raw,
        ...     encryption_algorithm=serialization.NoEncryption()
        ... )
        >>> loaded_private_key = x448.X448PrivateKey.from_private_bytes(private_bytes)

  public_key()
    Returns

      `X448PublicKey`

  exchange(peer_public_key)
    Parameters

      peer_public_key (X448PublicKey) – The public key for the peer.

    Returns bytes

      A shared key.

  private_bytes(encoding, format, encryption_algorithm)

    Allows serialization of the key to bytes. Encoding ( `PEM`, `DER`, or `Raw`) and format ( `PKCS8` or `Raw` ) are chosen to define the exact serialization.

    Parameters

      - encoding – A value from the `Encoding` enum.

      - format – A value from the `PrivateFormat` enum. If the `encoding` is `Raw` then `format` must be `Raw` , otherwise it must be `PKCS8`.

      - encryption_algorithm – An instance of an object conforming to the `KeySerializationEncryption` interface.

    Return bytes

      Serialized key.

class cryptography.hazmat.primitives.asymmetric.x448.X448PublicKey

  New in version 2.5.

  classmethod from_public_bytes(data)
    Parameters

      data (bytes) – 56 byte public key.

    Returns

      `X448PublicKey`

        >>> from cryptography.hazmat.primitives import serialization
        >>> from cryptography.hazmat.primitives.asymmetric import x448
        >>> private_key = x448.X448PrivateKey.generate()
        >>> public_key = private_key.public_key()
        >>> public_bytes = public_key.public_bytes(
        ...     encoding=serialization.Encoding.Raw,
        ...     format=serialization.PublicFormat.Raw
        ... )
        >>> loaded_public_key = x448.X448PublicKey.from_public_bytes(public_bytes)

  public_bytes(encoding, format)

    Allows serialization of the key to bytes. Encoding ( `PEM`, `DER`, or `Raw`) and format ( `SubjectPublicKeyInfo` or `Raw` ) are chosen to define the exact serialization.

    Parameters

      - encoding – A value from the `Encoding` enum.

      - format – A value from the `PublicFormat` enum. If the `encoding` is `Raw` then `format` must be `Raw` , otherwise it must be `SubjectPublicKeyInfo`.

    Returns bytes

      The public key bytes.