adapter

Crypto Adapter contract and utilities.

This module defines the behaviour contract that all crypto providers must implement, along with helper functions for creating default options.

Adapter Contract

A crypto provider handles:

Lifecycle management (init/shutdown)
Key exchange handshake (start/continue)
Secure context management
Encryption and decryption
Key rotation (rekeying)
Health monitoring

Implementing a Provider

To implement a custom provider, create a module that provides a function returning a CryptoAdapter record with all required functions:

pub fn new() -> CryptoAdapter {
  CryptoAdapter(
    init: my_init,
    shutdown: my_shutdown,
    handshake_start: my_handshake_start,
    handshake_continue: my_handshake_continue,
    secure_context: my_secure_context,
    encrypt: my_encrypt,
    decrypt: my_decrypt,
    rekey: my_rekey,
    health: my_health,
    metrics: my_metrics,
  )
}

See distribute/crypto/noop_adapter for a reference implementation.

Types

CryptoAdapter

</>

Crypto adapter behaviour contract.

All crypto implementations must provide these 10 core functions.

pub type CryptoAdapter {
  CryptoAdapter(
    init: fn(types.ProviderOptions) -> Result(
      types.ProviderHandle,
      types.CryptoError,
    ),
    shutdown: fn(types.ProviderHandle) -> Result(
      Nil,
      types.CryptoError,
    ),
    handshake_start: fn(
      types.ProviderHandle,
      String,
      String,
      option.Option(types.HandshakeMessage),
    ) -> Result(types.HandshakeResult, types.CryptoError),
    handshake_continue: fn(
      types.ProviderHandle,
      types.HandshakeState,
      types.HandshakeMessage,
    ) -> Result(types.HandshakeResult, types.CryptoError),
    secure_context: fn(types.ProviderHandle, String) -> option.Option(
      types.SecureContext,
    ),
    encrypt: fn(
      types.ProviderHandle,
      types.SecureContext,
      BitArray,
    ) -> Result(BitArray, types.CryptoError),
    decrypt: fn(
      types.ProviderHandle,
      types.SecureContext,
      BitArray,
    ) -> Result(BitArray, types.CryptoError),
    rekey: fn(types.ProviderHandle, String) -> Result(
      Nil,
      types.CryptoError,
    ),
    health: fn(types.ProviderHandle) -> types.HealthStatus,
    metrics: fn(types.ProviderHandle) -> types.CryptoMetrics,
  )
}

Constructors

CryptoAdapter(
  init: fn(types.ProviderOptions) -> Result(
    types.ProviderHandle,
    types.CryptoError,
  ),
  shutdown: fn(types.ProviderHandle) -> Result(
    Nil,
    types.CryptoError,
  ),
  handshake_start: fn(
    types.ProviderHandle,
    String,
    String,
    option.Option(types.HandshakeMessage),
  ) -> Result(types.HandshakeResult, types.CryptoError),
  handshake_continue: fn(
    types.ProviderHandle,
    types.HandshakeState,
    types.HandshakeMessage,
  ) -> Result(types.HandshakeResult, types.CryptoError),
  secure_context: fn(types.ProviderHandle, String) -> option.Option(
    types.SecureContext,
  ),
  encrypt: fn(types.ProviderHandle, types.SecureContext, BitArray) -> Result(
    BitArray,
    types.CryptoError,
  ),
  decrypt: fn(types.ProviderHandle, types.SecureContext, BitArray) -> Result(
    BitArray,
    types.CryptoError,
  ),
  rekey: fn(types.ProviderHandle, String) -> Result(
    Nil,
    types.CryptoError,
  ),
  health: fn(types.ProviderHandle) -> types.HealthStatus,
  metrics: fn(types.ProviderHandle) -> types.CryptoMetrics,
)

Arguments

init: Initialize the provider with options. Returns an opaque handle for subsequent operations.
shutdown: Shutdown the provider gracefully. Should zero sensitive memory where possible.
handshake_start: Start a handshake with a remote node. Returns initial handshake state and optional first message to send.
handshake_continue: Continue an in-progress handshake with an incoming message. Returns updated state, established context, or error.
secure_context: Get the secure context for a node if established.
encrypt: Encrypt plaintext using a secure context. Returns ciphertext or error.
decrypt: Decrypt ciphertext using a secure context. Returns plaintext or error.
rekey: Trigger a rekey for a specific node. Rotates the encryption keys for the connection.
health: Get current health status.
metrics: Get provider metrics.

Values

default_options

</>

pub fn default_options(name: String) -> types.ProviderOptions

Create default provider options.

Provides sensible defaults:

is_development: False
key_rotation_interval_ms: 0 (no auto-rotation)
handshake_timeout_ms: 30000 (30 seconds)

development_options

</>

pub fn development_options(name: String) -> types.ProviderOptions

Create development provider options.

Warning: These options are for development only and should never be used in production. The provider will be marked as insecure.