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.