kryptos/xdh

X25519 and X448 (XDH) key agreement.

XDH provides Diffie-Hellman key agreement using Montgomery curves X25519 and X448. These curves are designed specifically for key agreement and offer excellent performance with strong security properties.

Example

import kryptos/xdh

// Alice generates a key pair
let #(alice_private, alice_public) = xdh.generate_key_pair(xdh.X25519)

// Bob generates a key pair
let #(bob_private, bob_public) = xdh.generate_key_pair(xdh.X25519)

// Both compute the same shared secret
let assert Ok(alice_shared) = xdh.compute_shared_secret(alice_private, bob_public)
let assert Ok(bob_shared) = xdh.compute_shared_secret(bob_private, alice_public)
// alice_shared == bob_shared

Types

Curve

</>

Supported curves for XDH key agreement.

pub type Curve {
  X25519
  X448
}

Constructors

```
X25519
```
X25519 curve (Curve25519). 32-byte keys and shared secret.
```
X448
```
X448 curve (Curve448). 56-byte keys and shared secret.

PrivateKey

</>

An XDH private key.

pub type PrivateKey

PublicKey

</>

An XDH public key.

pub type PublicKey

Values

compute_shared_secret

</>

pub fn compute_shared_secret(
  private_key: PrivateKey,
  peer_public_key: PublicKey,
) -> Result(BitArray, Nil)

Computes a shared secret using XDH key agreement.

Both parties compute the same shared secret by combining their private key with the other party’s public key.

Returns Error(Nil) if the keys use different curves, the result is an all-zero shared secret (low-order point attack), or another error occurs.

The raw shared secret should be passed through a KDF (like HKDF) before use as a symmetric key.

curve

</>

pub fn curve(key: PrivateKey) -> Curve

Returns the curve for an XDH private key.

Parameters

key: The private key

Returns

The curve used by this key.

from_bytes

</>

pub fn from_bytes(
  curve: Curve,
  private_bytes: BitArray,
) -> Result(#(PrivateKey, PublicKey), Nil)

Imports a private key from raw bytes.

The bytes should be the raw private key scalar:

X25519: 32 bytes
X448: 56 bytes

Returns the private key and its corresponding public key, or Error(Nil) if the bytes are invalid.

from_der

</>

pub fn from_der(
  der: BitArray,
) -> Result(#(PrivateKey, PublicKey), Nil)

Imports an XDH private key from DER-encoded data.

The key must be in PKCS#8 format.

Parameters

der: DER-encoded key data

Returns

Ok(#(private_key, public_key)) on success, Error(Nil) on failure.

from_pem

</>

pub fn from_pem(
  pem: String,
) -> Result(#(PrivateKey, PublicKey), Nil)

Imports an XDH private key from PEM-encoded data.

The key must be in PKCS#8 format.

Parameters

pem: PEM-encoded key string

Returns

Ok(#(private_key, public_key)) on success, Error(Nil) on failure.

generate_key_pair

</>

pub fn generate_key_pair(
  curve: Curve,
) -> #(PrivateKey, PublicKey)

Generates a new XDH key pair.

Parameters

curve: The curve to use for key generation (X25519 or X448)

Returns

A tuple of #(private_key, public_key).

key_size

</>

pub fn key_size(curve: Curve) -> Int

Returns the key size in bytes for the given curve.

X25519: 32 bytes
X448: 56 bytes

public_key_curve

</>

pub fn public_key_curve(key: PublicKey) -> Curve

Returns the curve for an XDH public key.

Parameters

key: The public key

Returns

The curve used by this key.

public_key_from_bytes

</>

pub fn public_key_from_bytes(
  curve: Curve,
  public_bytes: BitArray,
) -> Result(PublicKey, Nil)

Imports a public key from raw bytes.

The bytes should be the raw public key point:

X25519: 32 bytes
X448: 56 bytes

Returns the public key or Error(Nil) if the bytes are invalid.

public_key_from_der

</>

pub fn public_key_from_der(
  der: BitArray,
) -> Result(PublicKey, Nil)

Imports an XDH public key from DER-encoded data.

The key must be in SPKI format.

Parameters

der: DER-encoded key data

Returns

Ok(public_key) on success, Error(Nil) on failure.

public_key_from_pem

</>

pub fn public_key_from_pem(pem: String) -> Result(PublicKey, Nil)

Imports an XDH public key from PEM-encoded data.

The key must be in SPKI format.

Parameters

pem: PEM-encoded key string

Returns

Ok(public_key) on success, Error(Nil) on failure.

public_key_from_private_key

</>

pub fn public_key_from_private_key(key: PrivateKey) -> PublicKey

Derives the public key from an XDH private key.

Parameters

key: The private key

Returns

The corresponding public key.

public_key_to_bytes

</>

pub fn public_key_to_bytes(key: PublicKey) -> BitArray

Exports a public key to raw bytes.

Returns the raw public key point:

X25519: 32 bytes
X448: 56 bytes

public_key_to_der

</>

pub fn public_key_to_der(key: PublicKey) -> Result(BitArray, Nil)

Exports an XDH public key to DER format.

The key is exported in SPKI format.

Parameters

key: The public key to export

Returns

Ok(der_data) on success, Error(Nil) on failure.

public_key_to_pem

</>

pub fn public_key_to_pem(key: PublicKey) -> Result(String, Nil)

Exports an XDH public key to PEM format.

The key is exported in SPKI format.

Parameters

key: The public key to export

Returns

Ok(pem_string) on success, Error(Nil) on failure.

to_bytes

</>

pub fn to_bytes(key: PrivateKey) -> BitArray

Exports a private key to raw bytes.

Returns the raw private key scalar:

X25519: 32 bytes
X448: 56 bytes

to_der

</>

pub fn to_der(key: PrivateKey) -> Result(BitArray, Nil)

Exports an XDH private key to DER format.

The key is exported in PKCS#8 format.

Parameters

key: The private key to export

Returns

Ok(der_data) on success, Error(Nil) on failure.

to_pem

</>

pub fn to_pem(key: PrivateKey) -> Result(String, Nil)

Exports an XDH private key to PEM format.

The key is exported in PKCS#8 format.

Parameters

key: The private key to export

Returns

Ok(pem_string) on success, Error(Nil) on failure.