nish:secret
Key material as an opaque value that the checker keeps from leaving the program by any road but one, and that is zeroed, with a store no optimiser may remove, before the function that made it lets go of it.
The nish:secret builtin module, whose source is std/secret.ts. A program imports it as nish:secret; the compiler refuses nish/secret. The language reference is the normative list.
import {
Secret,
expose,
exposeWith,
secret,
wipe,
} from "nish:secret";
import { Secret, expose, exposeWith, secret, wipe } from "nish:secret";
import { hmacSha256 } from "nish/crypto/hmac";
const tag = (key: u8[], message: u8[]): u8[] => hmacSha256(key, message);
export const main = (): i32 => {
const key: Secret<u8[]> = secret(readKey()); // moved in; `readKey()` is fresh
const mac: u8[] = exposeWith(key, message(), tag); // the one way in, and what leaves
wipe(key); // a volatile llvm.memset
console.log(mac.length);
return 0;
};
expose
f(value): the one way to read a Secret.
exposeWith
f(value, arg), under expose's rules, because the arrow expose runs captures nothing.
secret
value, wrapped.
wipe
Zero every byte of the value, with a volatile store the optimiser may not remove.
Secret
Key material: an array of integers or a record of integer fields, held opaque.
The one builtin module with source behind it, std/secret.ts, imported
only by this name (nish/secret is NL2453) and copied into each module that
uses it, so it writes no .ll of its own. A Secret local needs no
annotation: const k = secret(v) is Secret<T> for the T that v is,
under every rule. Under Node (runtime/nish.mjs) a Secret is a plain
wrapper and wipe zero-fills it.
A Secret may not reach a template hole (NL2431), a builtin's argument
(NL2432), === against anything but a Secret or null (NL2433), a
condition (NL2434), an index (NL2435), a member access outside
std/secret.ts (NL2436), new (NL2437), or an array element, a Result
payload or a type argument (NL2429); it lives in a local, a parameter or a
holder's readonly field. The function that made one returns it or wipes
it on every path (NL2439 to NL2443), and a copy is refused (NL2444, NL2446).
A Secret parameter is borrowed: the callee neither returns it (NL2546)
nor wipes it (NL2548).
What a `Secret` may hold
One run of integers, so that wipe reaches
every byte with one store: an array of integers (u8[], u32[], i64[],
...) or a class or interface whose every field is an integer.
Secret<string> is not key material (NL2428).
The wipe
One llvm.memset with its volatile flag set, over an array's
whole capacity, since a pop leaves the old element in the buffer, or a
record's sizeof. LLVM never removes, merges or narrows a volatile memory
intrinsic, so the store survives every optimisation, inlining included. It
does not reach a buffer a push outgrew, which is no longer the array's,
or a string. secureZero is the global for a bare u8[] that never was a
Secret.
Rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#secrets-nishsecret and https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#a-secret-field
Functions
expose
f(value): the one way to read a Secret. f is a top-level function
named at the call or an arrow written there, judged once the whole-program
facts are in. It reaches no I/O and no C through any depth of calls
(NL2448), panics or exits only with a literal, keeps nothing of value
(NL2449), and declares a return type that holds no Secret (NL2451; an
arrow writes it down, NL2452): that type is what leaves.
const expose: <T, R>(s: Secret<T>, f: (value: T) => R) => R
sSecret<T>required
The Secret to read, borrowed: it can be exposed again, and is
still to be wiped.
f(value: T) => RrequiredThe function the value is handed to.
returnsRWhat f answers.
exposeWith
f(value, arg), under expose's rules, because the arrow expose runs
captures nothing. f writes nothing through arg either (NL2450), which
would be a road out its result type does not name.
const exposeWith: <T, A, R>(
s: Secret<T>,
arg: A,
f: (value: T, arg: A) => R,
) => R
sSecret<T>requiredThe Secret to read, borrowed.
argArequiredThe second argument f is handed, read only.
f(value: T, arg: A) => RrequiredThe function the value and arg are handed to.
returnsRWhat f answers.
secret
value, wrapped. value is one nothing else holds: an array or object
literal, null, a ternary of fresh values, a new whose constructor
keeps no this, a call whose callee answers a fresh value, or a local
that is the sole reference to its value. A local handed in is moved and
may not be read again (NL2445); a parameter, a field or an element is
refused (NL2447); a local with a second reference is NL2512, naming it.
Pass a copy instead: const copy: u8[] = new Array<u8>(raw.length); copy.set(raw), then secret(copy).
const secret: <T>(value: T) => Secret<T>
valueTrequiredThe key material, of a shape a Secret may hold (NL2428).
returnsSecret<T>
The Secret, holding value itself and not a copy, so its
storage is the storage wipe later zeroes. It needs an owner: a
const or let, a return, or wipe (NL2439 otherwise).
wipe
Zero every byte of the value, with a volatile store the optimiser may not
remove. The Secret may not be read again (NL2443). A holder's field is
wiped only in that holder's own wipe() (NL2547).
const wipe: <T>(target: Secret<T>) => void
targetSecret<T>required
The Secret, never a nullable one: narrow it first
(NL2438).
Zero an array or record of integers that expose's function holds, with
the same volatile store. Anything else, a string included, is NL2438.
const wipe: (target: object) => void
targetobjectrequiredThe array or record of integers.
Classes
Secret
Key material: an array of integers or a record of integer fields, held
opaque. Made by secret, read only through expose, and wiped or
returned by the function that made it.
class Secret<T>

