silk/x25519

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Owned ephemeral X25519 keys and portable shared-secret agreement.

When to use

Use X25519 for RFC 7748 public-key derivation and ephemeral agreement. Generate production keys with explicit secure Random provision.

Details

Inputs and results use 32-byte little-endian encodings. Scalar import clamps bytes and derives a canonical public key. Agreement consumes the key, masks and reduces the peer coordinate, and rejects an all-zero result. Private arithmetic uses bounded local storage, without an allocator or crypto provider.

Gotchas

Feed the shared result into the protocol's key derivation. Agreement alone does not authenticate a peer or implement TLS. Never import the same scalar for distinct ephemeral exchanges. Ownership does not guarantee physical secret erasure. Functional vectors and generated-code inspection do not establish production security or universal constant-time behavior.

Import as X25519 with import silk.x25519 { X25519 }.

Public declarations: 2.

X25519Error

pub union X25519Error

A rejected X25519 input or shared result, without secret bytes in the error.

InvalidScalarLength

X25519Error.InvalidScalarLength: X25519Error

A scalar encoding whose length is not 32 bytes.

InvalidPeerLength

X25519Error.InvalidPeerLength: X25519Error

A peer coordinate encoding whose length is not 32 bytes.

AllZeroSharedSecret

X25519Error.AllZeroSharedSecret: X25519Error

A peer input that yields an all-zero shared result.

X25519

pub struct X25519

An owned ephemeral scalar and its canonical public coordinate, consumed by agreement.

Associated function X25519.fromSecret

pub fn fromSecret<'life0>(bytes: &'life0 [u8]) -> silk/result.Result<silk/x25519.X25519, silk/x25519.X25519Error>

Imports and clamps exactly 32 borrowed scalar bytes, deriving their canonical public key.

Details

A different input length returns InvalidScalarLength. Every 32-byte scalar encoding is admitted after RFC 7748 clamping. The input is copied into private owned storage; no borrow or allocator is retained.

Gotchas

Use generate with explicit Random provision for production ephemeral keys. Reimporting the same scalar reuses its key.

Associated function X25519.generate

pub effect<'static> fn generate() -> X25519 ? &mut Random

Obtains exactly 32 fresh Random bytes, clamps them and derives their canonical public key.

Details

Each invocation makes one complete 32-byte request through exclusive Random. No allocator is required. The returned key retains neither provider nor input borrow.

Gotchas

Provider failure remains fatal. There is no insecure fallback or entropy retry. Fresh draws can coincide by chance; this operation guarantees fresh acquisition, not global uniqueness.

Method X25519.publicKey

pub fn publicKey<'life0>(self: &'life0 silk/x25519.X25519) -> Array<u8, 32>

Returns the canonical 32-byte public coordinate while borrowing the ephemeral key.

Details

The returned bytes encode X25519(secret, basepoint 9), little-endian. Reading them does not consume the key.

Method X25519.agree

pub fn agree<'life0>(self: X25519, peer: &'life0 [u8]) -> silk/result.Result<Array<u8, 32>, silk/x25519.X25519Error>

Consumes the ephemeral key and returns a nonzero shared result, or a typed peer rejection.

Details

The peer must contain exactly 32 bytes; otherwise InvalidPeerLength is returned. Its high bit is masked and noncanonical coordinates are reduced modulo 2^255−19, including twist coordinates. An all-zero result returns AllZeroSharedSecret without publishing the secret. No on-curve restriction is imposed. The peer is borrowed only for this operation and no allocator or provider is required.

Gotchas

The key is consumed on success and failure. The shared result must enter protocol key derivation before encryption. This operation does not authenticate the peer or guarantee erasure of private scalar and intermediate copies.