@amritk/nish-aarch64-linux 0.13.0 → 0.15.0

package/runtime/shim.mjs

@@ -42,6 +42,7 @@
  * The rewrite rules that call these helpers are listed in docs/wp13-differential.md.
  */
 import child_process from "node:child_process";
+import { webcrypto } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 
@@ -91,6 +92,37 @@ export function bitsToF64(b) {
   return BITS.getFloat64(0);
 }
 
+/**
+ * `ctSelect` / `ctEq` (WP34 N6). A `u32` is a `number` here and a `u64` a
+ * BigInt, so the operands' kind picks the width, and a mix of the two — which
+ * the native checker refuses, and which a `u64` written as a bare literal is
+ * under an unrewritten run — throws the `TypeError` BigInt arithmetic throws
+ * rather than comparing a number with a BigInt and answering zero. JavaScript's
+ * `&` reads a `number` as a signed 32-bit integer, so each answer is put back in
+ * range with `>>> 0` or `asUintN(64, ...)`. These branch: only the native
+ * lowering promises constant time.
+ */
+function ctWide(name, first, second, third) {
+  const wide = typeof first === "bigint";
+  if ((typeof second === "bigint") !== wide || (typeof third === "bigint") !== wide) {
+    throw new TypeError(`${name}: cannot mix a u64 (BigInt) with a u32 (number)`);
+  }
+  return wide;
+}
+
+const U64_ONES = (1n << 64n) - 1n;
+
+export function ctSelect(mask, a, b) {
+  if (ctWide("ctSelect", mask, a, b)) return wrapU64((a & mask) | (b & ~mask));
+  return ((a & mask) | (b & ~mask)) >>> 0;
+}
+
+export function ctEq(a, b) {
+  // `ctEq` has two operands, so the second one stands in for the third.
+  if (ctWide("ctEq", a, b, b)) return wrapU64(a ^ b) === 0n ? U64_ONES : 0n;
+  return (a ^ b) === 0 ? 0xffffffff : 0;
+}
+
 /** Wrap a BigInt to the i64 range: every i64 `+ - * /` and unary minus goes through here. */
 export function wrapI64(x) {
   return BigInt.asIntN(64, x);
@@ -401,6 +433,28 @@ export function updIdx(a, i, f) {
   return v;
 }
 
+/**
+ * `dst.set(src, offset)` (WP34 N2): `TypedArray.prototype.set`'s copy on the
+ * plain array a `u8[]` is here. The source is copied first, so a self-copy or
+ * an overlapping one reads what was there before, as `memmove` does natively;
+ * a range past the end fails with the native panic and its words, where a
+ * typed array would throw a `RangeError` for the same offsets.
+ */
+export function arraySet(dst, src, offset) {
+  // `ToIntegerOrInfinity`: NaN is 0, as `llvm.fptosi.sat` makes it natively.
+  // `Math.trunc` rather than `toIndex`, which converts a bigint: an `i64` or
+  // `u64` offset is a bigint here, and it throws the `TypeError` the typed
+  // array and `Array.prototype.fill` throw for one, instead of being rounded
+  // to the nearest double past 2^53 (docs/RUN_UNDER_NODE.md).
+  const at = offset === undefined ? 0 : Math.trunc(offset) || 0;
+  const end = at + src.length;
+  if (!(at >= 0 && end <= dst.length)) panicSlice(at, end, dst.length);
+  // Two plain arrays overlap only when they are one array, which is the one
+  // case that must read the source before writing it.
+  const from = src === dst ? src.slice() : src;
+  for (let i = 0; i < from.length; i++) dst[at + i] = from[i];
+}
+
 /** `new Array<T>(n)`: `n` zero-filled elements (`0`, `0n`, or `false`). */
 export function newArray(n, zero) {
   return new Array(toIndex(n)).fill(zero);
@@ -434,6 +488,15 @@ export function readFileSyncOrNull(path) {
   }
 }
 
+/** `readFileBytesSync(path)` (WP34 N2): the bytes as a plain array of numbers, or null. */
+export function readFileBytesSync(path) {
+  try {
+    return Array.from(fs.readFileSync(path));
+  } catch {
+    return null;
+  }
+}
+
 export function writeFileSync(path, data) {
   try {
     fs.writeFileSync(path, data, "utf8");
@@ -618,6 +681,80 @@ export function monotonicNanos() {
   return process.hrtime.bigint();
 }
 
+// ---- The host (WP34 N3) ------------------------------------------------------
+
+/**
+ * `statMtimeSync(path)`: Node's `mtimeMs` for the path, or NaN when it cannot
+ * be stat'd, which is the native answer too. `mtimeMs` is the same arithmetic
+ * `runtime-host.c` does, so the two print the same digits, fraction and all.
+ */
+export function statMtimeSync(path) {
+  const st = fs.statSync(path, { throwIfNoEntry: false });
+  if (st === undefined) {
+    return Number.NaN;
+  }
+  return st.mtimeMs;
+}
+
+/**
+ * Node's own fill, taken before `runtime/nish.mjs` puts the one below in its
+ * place on the same object: `webcrypto` is the global `crypto`.
+ */
+const webRandom = webcrypto.getRandomValues.bind(webcrypto);
+
+/**
+ * `crypto.getRandomValues(bytes)` for the plain array a `u8[]` is here. Node's
+ * own takes only a typed array, so the bytes are drawn into one and copied
+ * across. More than 65,536 fails with the native panic and its words, where
+ * Node would throw a `QuotaExceededError`: the exit status is 1 either way. A
+ * typed array goes straight through.
+ */
+export function getRandomValues(bytes) {
+  if (!Array.isArray(bytes)) {
+    return webRandom(bytes);
+  }
+  if (bytes.length > 65536) {
+    panic(`crypto.getRandomValues: ${bytes.length} bytes asked for, and one call fills at most 65536`);
+  }
+  const drawn = webRandom(new Uint8Array(bytes.length));
+  for (let i = 0; i < drawn.length; i++) {
+    bytes[i] = drawn[i];
+  }
+  return bytes;
+}
+
+/**
+ * `signalFd()` and `readSignal(fd)` have no faithful reading under Node, and
+ * these say so rather than answer something else. Node delivers a signal to
+ * its event loop (`process.on("SIGTERM")`), and a blocking read keeps the loop
+ * from ever running, so no synchronous function here can learn that one
+ * arrived. docs/wp33-round-trip.md §3.5 has the row and the translation.
+ */
+export function signalFd() {
+  throw new Error(
+    "signalFd has no synchronous reading under Node: a signal reaches the event loop, which a blocking readSignal never returns to (docs/wp33-round-trip.md)"
+  );
+}
+
+export function readSignal() {
+  return signalFd();
+}
+
+/**
+ * The `nish:net` functions (WP34 N5) have no faithful reading under Node
+ * either, for `signalFd`'s reason: Node's sockets are asynchronous only, and a
+ * socket becomes readable, writable or connected only to the event loop, which
+ * a program that owns its loop and spins or blocks in it never returns to. So
+ * each throws, naming itself, rather than answer -11 forever; `nish.mjs`
+ * installs one per name.
+ * docs/wp33-round-trip.md is the note that asks for one stated answer.
+ */
+export function noNetReading(name) {
+  throw new Error(
+    `\`${name}\` has no synchronous reading under Node: a socket is ready only to the event loop, which a program that owns its loop never returns to (docs/wp33-round-trip.md)`
+  );
+}
+
 /** `process.argv`: index 0 is the program (the script here, the executable natively), then the arguments. */
 export function argv() {
   return process.argv.slice(1);

package/scripts/build.sh

@@ -3,11 +3,13 @@
 #
 #   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm]
 #
-# The C runtime is three translation units and is named as one: an input
+# The C runtime is five translation units and is named as one: an input
 # <dir>/runtime.c also compiles <dir>/runtime-os.c, the half that wraps the
 # system calls (files, directories, subprocesses, the environment, the clock),
-# and <dir>/runtime-parallel.c, the half that divides a range of work across
-# threads. Each of those files says why they are compiled and measured apart.
+# <dir>/runtime-parallel.c, the half that divides a range of work across
+# threads, <dir>/runtime-host.c, the wall clock, entropy, file times and
+# signals, and <dir>/runtime-net.c, the sockets of `nish:net`. Each of those
+# files says why they are compiled and measured apart.
 #
 # Profiles:
 #   debug  clang defaults: no optimisation, symbols kept. The "before" number.
@@ -83,9 +85,9 @@ done
 [ ${#inputs[@]} -gt 0 ] || { echo "error: no input files" >&2; exit 2; }
 [ -n "$out" ] || { echo "error: -o <out> is required" >&2; exit 2; }
 
-# The runtime is three translation units, and a caller names one: whoever passes
-# <dir>/runtime.c gets <dir>/runtime-os.c and <dir>/runtime-parallel.c compiled
-# beside it. They were one file until the operating-system half was split out
+# The runtime is five translation units, and a caller names one: whoever passes
+# <dir>/runtime.c gets <dir>/runtime-os.c, <dir>/runtime-parallel.c,
+# <dir>/runtime-host.c and <dir>/runtime-net.c compiled beside it. They were one file until the operating-system half was split out
 # for its own size budget, and the parallel half followed for the same reason
 # (each file's header comment says why), and a link line is where those splits
 # would otherwise leak: `nish --link` builds its command line in
@@ -97,7 +99,7 @@ done
 for i in ${inputs[@]+"${inputs[@]}"}; do
   case "$i" in
     */runtime.c|runtime.c)
-      for half in runtime-os.c runtime-parallel.c; do
+      for half in runtime-os.c runtime-parallel.c runtime-host.c runtime-net.c; do
         side="${i%runtime.c}$half"
         have=0
         for j in "${inputs[@]}"; do

package/std/README.md

@@ -16,6 +16,86 @@ whatever program imports it, and subject to the same rules as `examples/` or
 | [`map.ts`](./map.ts) | `reserve(m, n)` and `getOrInsert(m, k, v)` for the global `Map`. Their bodies are the meaning, and what runs under Node: `reserve` does nothing, and `getOrInsert` is a `get`, and a `set` of `v` when the key was missing. Natively the compiler lowers every call in place — `reserve` to the table's `reserveSlots`, which grows the buckets once so that `n` entries fit without a rebuild, and `getOrInsert` to one `probe` and a `valueAt` or an `insertAt` through its answer — so, like `collections.ts`, it writes no `.ll` of its own ([`docs/wp32-map.md`](../docs/wp32-map.md) §9.2, [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)) |
 | [`threads.ts`](./threads.ts) | `parallelMapInto(src, dst, f)` and `parallelReduce(src, f, identity)`: a function over every element of an array, on as many threads as the length is worth. Its bodies are the sequential meaning, which is what runs under Node; the compiler recognises the two templates by module and name, lowers the one loop in each onto `nish_parallel_range`, holds the function to the rules that make that safe, and compiles an importing program with `--threads` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md#data-parallelism-nishthreads)). `tests/link/par_*` are its programs |
 
+## `nish/crypto` — the primitives under TLS 1.3
+
+The first lanes of [WP34](../docs/wp34-hosting-cs.md) §5: K1's hashes, MACs and
+key derivation, K2's and K3's AEADs, K4's key exchange, K5's signatures and
+K6's certificates, in
+pure Nish (decision S1), each module imported by its own specifier. Every one
+is written from its specification, with two exceptions that keep their
+upstream notice: `crypto/aes.ts`'s `ghashMul32` is adapted from BearSSL, and
+`crypto/p256.ts`'s field and scalar arithmetic is ported from fiat-crypto
+([`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md)). Each reproduces its
+specification's published vectors in its `tests/link/crypto_*` programs. The
+performance gate compiles every module with no diagnostics under both
+`--number-mode i32` and `f64`, and the hashes, HMAC, HKDF, X25519,
+ChaCha20-Poly1305, AES-GCM, P-256 and X.509 also run their vectors in `f64`
+(`crypto_*_f64`).
+
+| Module | What it is | Reproduces |
+| --- | --- | --- |
+| [`crypto/sha256.ts`](./crypto/sha256.ts) | `sha256(data)`, and `Sha256`, a streaming hasher: `update(buf, off, len)` over a window of a `u8[]`, `copy()` for the hash of a prefix while the original keeps going, and `digest()`, a fresh 32-byte array. `SHA256_SIZE` and `SHA256_BLOCK` | FIPS 180-4 §6.2 |
+| [`crypto/sha512.ts`](./crypto/sha512.ts) | SHA-512 and SHA-384 on one compression function: `sha512` and `sha384`, and the streaming `Sha512` and `Sha384` with `Sha256`'s three methods; digests of 64 and 48 bytes. `SHA512_SIZE`, `SHA384_SIZE` and `SHA512_BLOCK` | FIPS 180-4 §6.4, §6.5 |
+| [`crypto/hmac.ts`](./crypto/hmac.ts) | `hmacSha256` and `hmacSha384`, the streaming `HmacSha256` and `HmacSha384` (keyed in the constructor, then `update` and `digest`), and `hmacSha256Verify` / `hmacSha384Verify`, which compare a received tag with `timingSafeEqual` | RFC 2104, RFC 4231 §4 |
+| [`crypto/hkdf.ts`](./crypto/hkdf.ts) | `hkdfExtractSha256` / `hkdfExtractSha384` (an empty salt is HashLen zeros) and `hkdfExpandSha256` / `hkdfExpandSha384`, which answer `null` for a length below zero or above 255 × HashLen. TLS 1.3's HKDF-Expand-Label is not here; it belongs with TLS | RFC 5869 §2, Appendix A |
+| [`crypto/ct.ts`](./crypto/ct.ts) | `timingSafeEqual(a, b)`, which reads every byte whatever it holds, and `timingSafeEqualAt(a, aOff, b, bOff, len)` over two windows, which answers `false` for a window outside its array. Two lengths that differ answer `false` at once, because a length is public | — |
+| [`crypto/base64url.ts`](./crypto/base64url.ts) | `base64urlEncode(data)` and `base64urlDecode(text)`, unpadded. Decoding is strict, so every byte string has one spelling: a `=`, a character outside the alphabet, a length of 1 mod 4 or nonzero unused low bits answer `null` | RFC 4648 §5, §10 |
+| [`crypto/x25519.ts`](./crypto/x25519.ts) | `x25519(scalar, u)` and `x25519Base(scalar)`, on ten 25.5-bit limbs in `i64`. Either answers `null` unless its arguments are `X25519_SIZE` (32) bytes; the scalar is clamped on a copy | RFC 7748 §5.2, §6.1 |
+| [`crypto/chacha20poly1305.ts`](./crypto/chacha20poly1305.ts) | `chacha20Poly1305Seal(key, nonce, aad, plaintext)`, which answers the ciphertext followed by the 16-byte tag, and `chacha20Poly1305Open`, which checks the whole tag before it decrypts anything and answers `null` for a message that does not authenticate. Beneath them `chacha20Block`, `chacha20`, `chacha20QuarterRound`, `poly1305` and `poly1305KeyGen`, and `chacha20HeaderMask`, QUIC's 5-byte header-protection mask. Every input of the wrong length answers `null` | RFC 8439 §2, RFC 9001 §5.4.4 |
+| [`crypto/aes.ts`](./crypto/aes.ts) | AES-128 and AES-256, bitsliced four blocks at a time with the Boyar–Peralta S-box circuit, so no table is read: `aesKey(key)` expands a 16- or 32-byte key into an `AesKey`, then `aesEncryptBlock`, `aesGcmSeal` / `aesGcmOpen` (tag last, checked in full before anything is decrypted; any non-empty IV) and `aesHeaderMask`. AES-192 is out of scope, and a wrong length answers `null` | FIPS 197, SP 800-38D, RFC 9001 §5.4.3, Wycheproof `aes_gcm` |
+| [`crypto/p256.ts`](./crypto/p256.ts) | ECDSA over P-256 with RFC 6979's deterministic nonces: `p256PublicKey(priv)` (65-byte uncompressed SEC1), `p256Sign` / `p256Verify` over a digest and `p256SignSha256` / `p256VerifySha256` over a message; a signature is `r` and `s`, 32 big-endian bytes each, not DER. A malformed key, a point off the curve or an `r` or `s` out of range answers `null` or `false`, never a panic | RFC 6979 A.2.5, Wycheproof `ecdsa_secp256r1_sha256` |
+| [`crypto/x509.ts`](./crypto/x509.ts) | DER, PEM and X.509 over P-256: `pemToDer` / `derToPem` (RFC 7468, padded standard base64, strict labels), `x509ParseP256PrivateKey` (SEC1 or PKCS#8), `x509ParseCertificate` / `x509ParseChain` into an `X509Certificate`, `x509VerifySignature` (ecdsa-with-SHA256 under an issuer's key), `x509MintSelfSigned`, the 1-to-14-day self-signed P-256 certificate WebTransport's `serverCertificateHashes` accepts, and `x509CertificateHash`, its SHA-256. DER is read strictly — non-minimal lengths and integers, indefinite lengths and trailing bytes answer `null` | X.690, RFC 5280, RFC 7468, RFC 5915, RFC 5208 / 5958; certificates checked against OpenSSL |
+
+Three rules hold across the modules:
+
+- **A digest ends the computation.** After `digest()` on a hasher or an HMAC, a
+  further `update` or `digest` panics rather than answering a hash over the
+  padding, and so does a window outside its buffer. `Sha256.copy()` on a
+  digested hasher panics too; `Sha512.copy()` and `Sha384.copy()` answer a copy
+  that is itself spent, so any `update` or `digest` on it panics. Either way,
+  copy *before* `digest` when the computation has to go on.
+- **An all-zero X25519 result is returned, not refused.** It is what a
+  low-order `u` gives, and RFC 7748 §6.1 leaves the check to the protocol; TLS
+  1.3 (WP34 T1) makes it. A key exchange outside TLS has to make it itself.
+- **Constant time by construction, and verified where the check reaches.** No
+  module branches on, or indexes by, a secret: comparisons OR the differences
+  into one word and test it once, the ladder swaps with a mask and always runs
+  255 steps, AES reads no table, P-256's window reads all sixteen entries and
+  keeps one by mask, and base64url maps characters by arithmetic on range masks
+  rather than a table. Every branch is on a length, a loop counter or a bit
+  position. WP34 N6 checks that the machine code kept that shape:
+  `tests/ct-asm.js` disassembles golden fixtures on x86-64 and aarch64 and
+  refuses a branch, a call or a secret-addressed load in them. What it holds,
+  per module, is what that module's header says:
+  - `tests/cases/ct_asm_mac` pins the two loop shapes the others are built
+    from, a full tag compare and a masked table read. `crypto/ct.ts` and
+    `crypto/hmac.ts`'s verifiers compare in the first shape and
+    `crypto/base64url.ts` selects by mask, but none of those K1 modules is
+    itself in a fixture, so they remain discipline.
+  - `tests/cases/ct_asm_x25519`: X25519's field multiply, square, add,
+    subtract and multiply by a24, its conditional swap, and one step of the
+    Montgomery ladder, the check following each call into the field functions.
+    The 255-step loop that drives the ladder, the inversion and the encodings
+    remain discipline.
+  - `tests/cases/ct_asm_chacha20poly1305`: Poly1305's key clamp, one block,
+    the final reduction with `s`, and the tag compare. The ChaCha20 rounds and
+    the loops that drive both halves remain discipline.
+  - `tests/cases/ct_asm_aes`: one full bitsliced round, one GHASH multiply and
+    the tag compare. Packing, the key schedule and the loops over blocks
+    remain discipline.
+  - `tests/cases/ct_asm_p256`: fiat's field multiply, square, add and
+    subtract, its scalar multiply and its conditional move; the sixteen-entry
+    table read by a secret digit; the complete doubling and addition; and one
+    window step of the scalar multiplication (four doublings, the table read
+    and an addition), the check following each call into the field functions.
+    The 64-window loop, the table build, the inversions, the encodings and
+    RFC 6979's nonce derivation remain discipline.
+
+  The SHA-2 hashes and HKDF are additions, rotations and xors that branch
+  only on lengths, and are not in a fixture either; nor is `crypto/x509.ts`,
+  whose one secret, a private key, is base64-decoded by range masks and
+  otherwise only copied and handed to `crypto/p256.ts`.
+
 ## How a program imports it
 
 By its package specifier:

package/std/crypto/LICENSE-bearssl

@@ -0,0 +1,21 @@
+Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
+
+Permission is hereby granted, free of charge, to any person obtaining 
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be 
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/std/crypto/LICENSE-fiat-crypto

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2020 the fiat-crypto authors (see the AUTHORS file).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.