@stablelib/x25519

@stablelib/x25519 implements the X25519 key agreement protocol based on Curve25519 elliptic curve cryptography. It provides both low-level cryptographic primitives for direct scalar multiplication operations and a high-level key agreement interface for building secure communication protocols.

Package Information

• Package Name: @stablelib/x25519
• Package Type: npm
• Language: TypeScript
• Installation: npm install @stablelib/x25519

Core Imports

import {
  generateKeyPair,
  sharedKey,
  PUBLIC_KEY_LENGTH,
  SECRET_KEY_LENGTH,
  SHARED_KEY_LENGTH
} from "@stablelib/x25519";
import {
  X25519KeyAgreement,
  OFFER_MESSAGE_LENGTH,
  ACCEPT_MESSAGE_LENGTH
} from "@stablelib/x25519/keyagreement";

For CommonJS:

const {
  generateKeyPair,
  sharedKey,
  PUBLIC_KEY_LENGTH,
  SECRET_KEY_LENGTH,
  SHARED_KEY_LENGTH
} = require("@stablelib/x25519");
const {
  X25519KeyAgreement,
  OFFER_MESSAGE_LENGTH,
  ACCEPT_MESSAGE_LENGTH
} = require("@stablelib/x25519/keyagreement");

Basic Usage

import { generateKeyPair, sharedKey } from "@stablelib/x25519";

// Generate ephemeral key pairs for both parties
const alice = generateKeyPair();
const bob = generateKeyPair();

// Compute shared secret (both parties compute the same value)
const aliceShared = sharedKey(alice.secretKey, bob.publicKey);
const bobShared = sharedKey(bob.secretKey, alice.publicKey);

// aliceShared equals bobShared - use this for symmetric encryption
console.log("Shared key established:", aliceShared);

Architecture

@stablelib/x25519 is built around two main components:

• Low-level primitives: Direct access to X25519 scalar multiplication, key generation, and shared key computation for maximum flexibility
• High-level protocol: X25519KeyAgreement class implementing a complete key agreement protocol with offer/accept pattern for interactive key exchange
• Security features: Secure memory wiping, timing attack protection, and optional validation of shared key results
• TypeScript integration: Full type safety with proper interfaces for key pairs and protocol messages

Capabilities

Low-level X25519 Operations

Core X25519 cryptographic primitives for key generation and shared key computation. Provides direct access to Curve25519 scalar multiplication operations.

function generateKeyPair(prng?: RandomSource): KeyPair;
function generateKeyPairFromSeed(seed: Uint8Array): KeyPair;
function sharedKey(mySecretKey: Uint8Array, theirPublicKey: Uint8Array, rejectZero?: boolean): Uint8Array;

interface KeyPair {
  publicKey: Uint8Array;
  secretKey: Uint8Array;
}

Low-level Operations

High-level Key Agreement Protocol

Interactive key agreement protocol using ephemeral key pairs with offer/accept pattern. Suitable for building secure communication protocols.

class X25519KeyAgreement implements KeyAgreement {
  constructor(secretSeed?: Uint8Array, prng?: RandomSource);
  offer(): Uint8Array;
  accept(offerMsg: Uint8Array): Uint8Array;
  finish(acceptMsg: Uint8Array): this;
  getSharedKey(): Uint8Array;
}

Key Agreement Protocol

Constants

const PUBLIC_KEY_LENGTH: number;    // 32 bytes
const SECRET_KEY_LENGTH: number;    // 32 bytes  
const SHARED_KEY_LENGTH: number;    // 32 bytes

Types

interface KeyPair {
  publicKey: Uint8Array;
  secretKey: Uint8Array;
}

interface RandomSource {
  randomBytes(length: number): Uint8Array;
  isAvailable: boolean;
}

Security Considerations

• Authentication Required: X25519 by itself does not provide authentication. It must be combined with signatures or other authentication methods to prevent man-in-the-middle attacks.
• Key Material Processing: The result of sharedKey() is raw output from scalar multiplication and MUST be processed through a key derivation function (KDF) before use as encryption keys. Never use the raw shared key directly for encryption or authentication.
• Memory Security: Use the clean() method on X25519KeyAgreement instances and consider wiping sensitive key material when no longer needed.
• Zero Key Rejection: The rejectZero parameter in sharedKey() can detect certain types of invalid public keys that would result in all-zero shared secrets.