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;
};

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) => Rrequired

The function the value is handed to.

returnsR

What 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>required

The Secret to read, borrowed.

argArequired

The second argument f is handed, read only.

f(value: T, arg: A) => Rrequired

The function the value and arg are handed to.

returnsR

What 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>
valueTrequired

The 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
targetobjectrequired

The 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>