x25519.rst

X25519 key exchange

cryptography.hazmat.primitives.asymmetric.x25519

X25519 is an elliptic curve Diffie-Hellman key exchange using Curve25519. 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.x25519 import X25519PrivateKey >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF >>> # Generate a private key for use in the exchange. >>> private_key = X25519PrivateKey.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 = X25519PrivateKey.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 = X25519PrivateKey.generate() >>> peer_public_key_2 = X25519PrivateKey.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

2.0

generate()

Generate an X25519 private key.

returns

X25519PrivateKey

from_private_bytes(data)

2.5

A class method for loading an X25519 key encoded as ~cryptography.hazmat.primitives.serialization.Encoding.Raw.

param bytes data

32 byte private key.

returns

X25519PrivateKey

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

public_key()

returns

X25519PublicKey

exchange(peer_public_key)

param X25519PublicKey peer_public_key

The public key for the peer.

returns bytes

A shared key.

private_bytes(encoding, format, encryption_algorithm)

2.5

Allows serialization of the key to bytes. Encoding ( ~cryptography.hazmat.primitives.serialization.Encoding.PEM, ~cryptography.hazmat.primitives.serialization.Encoding.DER, or ~cryptography.hazmat.primitives.serialization.Encoding.Raw) and format ( ~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8 or ~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw ) 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. If the encoding is ~cryptography.hazmat.primitives.serialization.Encoding.Raw then format must be ~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw , otherwise it must be ~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8.

param encryption_algorithm

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

return bytes

Serialized key.

2.0

from_public_bytes(data)

param bytes data

32 byte public key.

returns

X25519PublicKey

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

public_bytes(encoding, format)

Allows serialization of the key to bytes. Encoding ( ~cryptography.hazmat.primitives.serialization.Encoding.PEM, ~cryptography.hazmat.primitives.serialization.Encoding.DER, or ~cryptography.hazmat.primitives.serialization.Encoding.Raw) and format ( ~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo or ~cryptography.hazmat.primitives.serialization.PublicFormat.Raw ) 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. If the encoding is ~cryptography.hazmat.primitives.serialization.Encoding.Raw then format must be ~cryptography.hazmat.primitives.serialization.PublicFormat.Raw , otherwise it must be ~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo.

returns bytes

The public key bytes.