Module `Secret`Source

Secret key material kept outside the OCaml heap.

A t owns a fixed-length byte buffer allocated in C memory. The bytes never reside in the OCaml heap, so the garbage collector cannot copy them (minor-to-major promotion and compaction copy heap blocks and leave the old copy behind, unzeroed). The buffer is zeroized when destroy is called, when the handle is garbage-collected, and at normal program exit (wipe_all is registered with Stdlib.at_exit).

This is an experimental, unaudited pre-1.0 implementation. Its memory hardening is defense in depth, not a substitute for process isolation or hardware-backed key storage.

What this module guarantees

The payload is never copied by the GC and is not reachable through polymorphic compare, Hashtbl.hash or Marshal (compare and Marshal raise Invalid_argument; Hashtbl.hash ignores the contents).
The payload is overwritten with zeros, using a primitive the C compiler cannot elide, on destroy, on garbage collection of the handle and on normal exit, before its memory is ever reused.
equal runs in time that depends only on the lengths.
Secret bytes reach OCaml values only through documented Scratch-based construction or exposure callbacks and functions whose names contain expose, unsafe or view.

What this module does not (and cannot) guarantee

Copies spilled to the C stack or registers inside cryptographic primitives, or made by the kernel (page cache, socket buffers, hibernation images), or made by callers through expose/unsafe_*.
Key-equivalent data kept by libraries that take string keys and build their own key schedules in the OCaml heap.
Zeroization when the process dies by a signal, Unix._exit or a runtime fatal error: no handler runs.
mlock/core-dump exclusion are best effort: they depend on resource limits and on the platform (no core-dump exclusion on macOS) and their outcome is reported by status, never assumed.
Protection against a root user, ptrace, cold-boot attacks, or a compromised kernel or hypervisor.

Sourcetype t

A secret. Values of this type cannot be compared, hashed or marshalled. A t may be used from any domain. Concurrent read-only operations are safe. Callers must synchronize every mutation with all other accesses to that t, and must not call destroy concurrently with an operation on it (as for Bytes). Calling destroy concurrently more than once is safe.

Sourceexception Destroyed

Raised by every operation that reads or writes a secret after destroy (or after wipe_all). Never a crash.

Sourceexception Entropy_unavailable

Raised by random when the OS has no entropy source (for example on MirageOS) and no fallback was installed with set_entropy_source.

Construction

Sourceval create : ?hardened:bool -> int -> t

create ?hardened n is a zero-filled secret of n bytes (n >= 0).

hardened (default false) requests the page-backed tier: guard pages, a canary, mlock, and exclusion from core dumps where the OS supports it. Each feature is best effort; check status. Cost: at least three OS pages of address space per secret. The default tier uses calloc memory with zero-on-release and is meant for many small or short-lived keys.

Raises Invalid_argument if n < 0 and Out_of_memory if allocation fails.

Sourceval random : ?hardened:bool -> int -> t

random ?hardened n is a secret of n bytes of OS entropy (getrandom/getentropy/BCryptGenRandom) written directly into the secret memory; no copy is made in the OCaml heap. When the platform has no OS source, the generator installed with set_entropy_source is used (it writes into a Scratch buffer that is wiped afterwards).

raises Entropy_unavailable
when no source is available.

Sourceval of_string : ?hardened:bool -> string -> t

of_string s copies s into a new secret. The source string is immutable and cannot be wiped: it stays in the OCaml heap until collected. Prefer random, init, of_bytes or Secret_unix.read_fd when the secret can originate in controlled memory.

Sourceval of_bytes : ?hardened:bool -> wipe_source:bool -> bytes -> t

of_bytes ~wipe_source b copies b. With ~wipe_source:true the source is zeroized afterwards with the same primitive as destroy, including if allocation or copying raises. This cannot reach copies the GC may already have made of b (a bytes allocated in the minor heap is copied when promoted); use Scratch buffers to avoid that.

Sourceval init : ?hardened:bool -> int -> (bytes -> unit) -> t

init n f creates a secret of n bytes and calls f with a temporary mutable Scratch buffer so that a producer (a PRNG, a KDF, a decoder) can initialize it. The buffer is copied into the secret, then zeroized when f returns or raises. If f retains the buffer, it observes only zeroes after init returns. Use Unsafe.init when a zero-copy initializer is required. This is subject to the major-heap compaction limitation documented by Scratch.

Sourceval with_secret : ?hardened:bool -> int -> (t -> 'a) -> 'a

with_secret n f is f (create n); the secret is destroyed when f returns or raises.

Sourceval with_random : ?hardened:bool -> int -> (t -> 'a) -> 'a

with_random n f is f (random n); the random secret is destroyed when f returns or raises.

Inspection

Sourceval length : t -> int

Length in bytes. The length is not considered secret. Usable after destroy.

Sourceval is_destroyed : t -> bool

Sourceval equal : t -> t -> bool

Constant-time equality of the contents (implemented in C). Lengths are compared first with an ordinary branch; the contents comparison takes time proportional to the length and independent of the values. There is deliberately no compare and no hash.

raises Destroyed
if either argument is destroyed.

Sourceval equal_string : t -> string -> bool

Same as equal against an OCaml string (e.g. a received MAC tag).

Sourceval pp : Format.formatter -> t -> unit

Prints <secret:32B> or <secret:destroyed>, never the contents.

Sourcetype lock = [

| `Locked
(*
pages are locked in RAM
*)
| `Failed of int
(*
mlock failed with this errno (ENOMEM: RLIMIT_MEMLOCK; EPERM: no IPC_LOCK)
*)
| `Lost_on_fork
(*
locked before a fork; locks are not inherited, see after_fork
*)
| `Unsupported
(*
this platform cannot lock pages
*)
| `Not_requested
(*
the secret is not hardened
*)

]

Sourcetype status = {

page_backed : bool;
(*
the hardened tier was actually obtained
*)
guard_pages : bool;
canary : bool;
lock : lock;
no_core_dump : [ `Yes | `Unsupported | `Not_requested ];
wipe_on_fork : bool;
viewed : bool;
(*
an unscoped view was handed out
*)
destroyed : bool;

}

Sourceval status : t -> status

Never raises; usable after destroy.

Sourcetype hardening_requirement = [

| `Page_backed
| `Guard_pages
| `Canary
| `Locked
| `No_core_dump
| `Wipe_on_fork

]

Sourceexception Hardening_unavailable of hardening_requirement

Raised by require_hardening with the first requirement that was not met.

Sourceval require_hardening : hardening_requirement list -> t -> t

require_hardening requirements t returns t if every requirement is currently met. Otherwise it destroys t before raising Hardening_unavailable. This makes the function safe to use in a pipeline, for example random ~hardened:true 32 |> require_hardening [`Page_backed; `Locked].

raises Destroyed
if t is already destroyed.

Sourcetype capabilities = {

hardened_tier : bool;
can_lock : bool;
can_exclude_from_dumps : bool;
can_wipe_on_fork : bool;
os_random : bool;
atfork : bool;
zeroize_primitive : string;
(*
e.g. "explicit_bzero"
*)
page_size : int;

}

Sourceval capabilities : unit -> capabilities

What this build and platform can provide. The per-value truth is status.

Mutation

Sourceval fill : t -> char -> unit

Sourceval zero : t -> unit

zero t zeroizes the contents; t stays alive.

Sourceval blit : src:t -> src_off:int -> dst:t -> dst_off:int -> len:int -> unit

memmove between secrets. Raises Invalid_argument on bounds errors.

raises Destroyed

Source

val blit_from_string : 
  string ->
  src_off:int ->
  t ->
  dst_off:int ->
  len:int ->
  unit

Source

val blit_from_bytes : 
  bytes ->
  src_off:int ->
  t ->
  dst_off:int ->
  len:int ->
  unit

Sourceval sub : ?hardened:bool -> t -> off:int -> len:int -> t

A copy of a range (never an alias). Tier defaults to that of the source.

Sourceval copy : ?hardened:bool -> t -> t

Sourceval destroy : t -> unit

Zeroizes the contents now and releases or pools unviewed memory. Memory that has produced an unscoped view is instead permanently retained and is never reused. Idempotent. After this every accessor through the owner raises Destroyed. Destroy secrets as soon as they are no longer needed: relying on the GC delays the wipe until the handle is collected.

Controlled exposure

These are the only ways to get secret bytes into OCaml values.

Sourceval expose : t -> (bytes -> 'a) -> 'a

expose t f calls f with a temporary copy of the contents in a Scratch buffer (allocated directly in the major heap, so the minor collector never duplicates it) and zeroizes the buffer when f returns or raises. f must not retain the buffer. Anything f does with the bytes (Bytes.to_string, Buffer.add_bytes, passing them to a string-keyed API) creates copies this module cannot wipe. Major-heap compaction can also leave a historical copy as documented by Scratch.

raises Destroyed

Sourceval blit_to_bytes : t -> src_off:int -> bytes -> dst_off:int -> len:int -> unit

Copies into a caller-owned buffer (ideally a Scratch buffer).

Sourceval unsafe_to_string : t -> string

A fresh immutable copy that lives in the OCaml heap until collected and cannot be wiped. Only for legacy APIs that retain their key argument. Allocated in the major heap to avoid promotion copies.

Sourcemodule Unsafe : sig ... end

Zero-copy views of the secret memory.

Sourcemodule Scratch : sig ... end

Best-effort scratch buffers allocated directly in the major heap.

Sourcemodule Gc : sig ... end

Best-effort GC hygiene.

Sourcemodule Process : sig ... end

Process-wide hardening. Every feature reports its outcome; nothing is silent. Apply process-global controls during single-threaded startup. In particular, scrub_env must not race another environment access.

Process-level controls

Sourceval wipe_all : unit -> unit

Destroys every live secret in the process. Registered with Stdlib.at_exit at module initialisation, so it runs after all handlers registered later (i.e. after every handler of code that uses this module). Does not run on Unix._exit, signals or runtime fatal errors. Callers must ensure that no secret operation, scoped or unscoped view access, or blocking Secret_unix I/O is in flight. In particular, quiesce worker domains before an explicit process-wide wipe. Wiped storage is released when its owning handle is finalized.

Sourceval live_count : unit -> int

Number of allocated handles not yet finalized (diagnostics).

Sourceval pool_count : unit -> int

Number of released payload blocks held in the reuse pool (diagnostics).

Sourceval parked_count : unit -> int

Number of destroyed payload blocks that had produced an unscoped view and are therefore permanently retained (diagnostics). The library keeps parked and pooled storage reachable, so memory-leak tools report it as reachable memory rather than as a leak; this counter is how to observe the process-lifetime cost of retained unscoped views.

Sourceval set_entropy_source : (bytes -> unit) -> unit

Fallback generator used by random when (capabilities ()).os_random is false (MirageOS). The callback must fill the whole buffer, which is a Scratch buffer wiped afterwards, e.g. set_entropy_source (fun b -> Mirage_crypto_rng.generate_into b (Bytes.length b)). Replacement is atomic across domains.

Sourceval set_fork_policy : [ `Keep | `Wipe_in_child ] -> unit

POSIX only (no-op elsewhere). `Keep (default): the child inherits copies of all secrets; memory locks are lost (see after_fork). `Wipe_in_child: an atfork child handler zeroizes every secret in the child; on Linux, live and subsequently created hardened secrets also get MADV_WIPEONFORK. Switching back to `Keep revokes that advice. Set the policy before starting worker domains or forking.

Sourceval after_fork : unit -> unit

Call in a forked child to re-establish mlock on hardened secrets.

package secret

Module SecretSource