@amritk/nish-x86_64-linux 0.14.0 → 0.16.0

package/runtime/runtime-os.c

@@ -52,6 +52,14 @@ extern char **environ;
 
 #include "nish.h"
 
+/* Darwin's <fcntl.h> declares `O_NOFOLLOW` only at its full C level, and the
+   strict level the two macros above select is the one that binds the right
+   `realpath`, so the flag is spelled here with Darwin's own value
+   (<sys/fcntl.h>: 0x00000100). Linux and WASI declare it at POSIX 2008. */
+#if defined(__APPLE__) && !defined(O_NOFOLLOW)
+#define O_NOFOLLOW 0x00000100
+#endif
+
 /* The same spelling runtime.c uses for its own cold paths: a function that
    reports and exits is never on a path worth optimising for. */
 #define NISH_COLD __attribute__((noreturn, cold, noinline))
@@ -63,6 +71,12 @@ static NISH_COLD void nish_io_fail(const char *what, const nish_str *path) {
   _exit(1);
 }
 
+/* The longest string or array a read hands back: 2^31 - 1, the same limit
+   runtime.c's `NISH_ARRAY_MAX` puts on a push. Under --number-mode i32
+   `length` is an `i32`, so one byte more reads back negative and bounds-check
+   elimination trusts it (docs/security/runtime.md, RT-1). */
+#define NISH_LENGTH_MAX 2147483647
+
 /* `readFileSyncOrNull(path)`: null rather than a message, so a program can
    turn a missing file into its own diagnostic and carry on.
  *
@@ -84,11 +98,16 @@ static NISH_COLD void nish_io_fail(const char *what, const nish_str *path) {
  * rather than `stat` on the path, so the answer is about the file that was
  * opened and not about whatever the name means a moment later. */
 nish_str *nish_read_file_or_null(const nish_str *path) {
-  int fd = open(path->data, O_RDONLY);
+  int fd = open(nish_cpath(path), O_RDONLY);
   if (fd < 0) return 0;
   struct stat st;
   off_t len = fstat(fd, &st) == 0 && !S_ISDIR(st.st_mode) ? lseek(fd, 0, SEEK_END) : -1;
-  if (len < 0) {
+  /* A file longer than a length can say is refused before anything is
+     allocated, as an unreadable one is: null here, null from
+     `readFileBytesSync`, and `cannot read` from `readFileSync`. The bytes read
+     below are never more than `len`, so a file that grows meanwhile cannot
+     pass the limit either. */
+  if (len < 0 || len > NISH_LENGTH_MAX) {
     close(fd);
     return 0;
   }
@@ -123,8 +142,14 @@ nish_str *nish_read_file(const nish_str *path) {
   return s;
 }
 
+/* `O_NOFOLLOW` (docs/security/runtime.md, RT-4): a symbolic link as the last
+   component of the path is refused, as an unwritable file is, rather than
+   followed to whatever file it names. `nish file.ts` writes `file.ll` beside
+   its source, so a link planted at that name in a checkout would otherwise
+   truncate any file the user can write. A link among the directories on the
+   way is still followed. */
 static void nish_put_file(const nish_str *path, const nish_str *data, int flags) {
-  int fd = open(path->data, O_WRONLY | O_CREAT | flags, 0644);
+  int fd = open(nish_cpath(path), O_WRONLY | O_CREAT | O_NOFOLLOW | flags, 0644);
   if (fd < 0) nish_io_fail("write ", path);
   for (uint64_t done = 0; done < data->len;) {
     ssize_t n = write(fd, data->data + done, data->len - done);
@@ -149,14 +174,14 @@ void nish_append_file(const nish_str *path, const nish_str *data) { nish_put_fil
    answer to that question. */
 _Bool nish_is_dir(const nish_str *path) {
   struct stat st;
-  return stat(path->data, &st) == 0 && S_ISDIR(st.st_mode);
+  return stat(nish_cpath(path), &st) == 0 && S_ISDIR(st.st_mode);
 }
 
 /* One directory, not recursive. The retry is the `stat` above rather than
    `errno == EEXIST` so that a plain file at the path answers false, which is
    what the promise "a directory is there afterwards" means. */
 _Bool nish_mkdir(const nish_str *path) {
-  return mkdir(path->data, 0777) == 0 || nish_is_dir(path);
+  return mkdir(nish_cpath(path), 0777) == 0 || nish_is_dir(path);
 }
 
 /* `posix_spawnp` is one libc call where fork/execvp/waitpid would be three,
@@ -168,7 +193,7 @@ _Bool nish_mkdir(const nish_str *path) {
    two arguments answered differently, so the argv vector, the wait and the
    signal convention are written once; it is `static`, so a program that spawns
    nothing still loses all three to `--gc-sections`. */
-static int32_t nish_spawn_impl(const nish_array *argv, const char *out, const char *err) {
+static int32_t nish_spawn_impl(const nish_array *argv, const nish_str *out, const nish_str *err) {
 #ifdef __wasi__
   (void)argv;
   (void)out;
@@ -181,18 +206,27 @@ static int32_t nish_spawn_impl(const nish_array *argv, const char *out, const ch
      path out of here has anything to free. */
   char **v = nish_alloc_struct((argv->len + 1) * sizeof *v);
   uint64_t i = 0;
-  for (; i < argv->len; i++) v[i] = s[i]->data;
+  /* An argument holding a NUL is refused rather than cut short at it, which
+     would run a different command line from the one the program built: it is
+     the one whose C string is not its own bytes. */
+  for (; i < argv->len; i++) {
+    v[i] = (char *)nish_cpath(s[i]);
+    if (v[i] != s[i]->data) return -1;
+  }
   v[i] = 0;
   posix_spawn_file_actions_t fa;
   posix_spawn_file_actions_t *fap = 0;
-  if (out || err) {
-    if (posix_spawn_file_actions_init(&fa)) return -1;
-    fap = &fa;
+  const nish_str *to[2] = { out, err };
+  for (int k = 0; k < 2; k++) {
+    if (!to[k]) continue;
+    if (!fap) {
+      if (posix_spawn_file_actions_init(&fa)) return -1;
+      fap = &fa;
+    }
     /* The child opens the file, not this process: a redirect that this process
        performed would have to be undone afterwards, and a failed open would
        leave its own stdout pointing at the file. */
-    if (out) posix_spawn_file_actions_addopen(fap, 1, out, O_WRONLY | O_CREAT | O_TRUNC, 0644);
-    if (err) posix_spawn_file_actions_addopen(fap, 2, err, O_WRONLY | O_CREAT | O_TRUNC, 0644);
+    posix_spawn_file_actions_addopen(fap, k + 1, nish_cpath(to[k]), O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW, 0644);
   }
   pid_t pid;
   int status;
@@ -210,14 +244,15 @@ int32_t nish_spawn(const nish_array *argv) { return nish_spawn_impl(argv, 0, 0);
    to a file, which is what comparing a program's output against a golden needs
    — `nish_spawn` answers a status and the output is gone. An **empty** path
    leaves that stream inherited, so one call can capture stdout and let stderr
-   through to the terminal. Each file is created or truncated at 0644, as
-   `writeFileSync` does.
+   through to the terminal. Each file is created or truncated at 0644 and a
+   symbolic link at its name is refused, as `writeFileSync` does; the child
+   then fails to start, and the answer is -1.
 
    Two streams must not name one path: each would be opened separately, with
    its own offset, and the two would overwrite each other rather than
    interleave. Capturing them apart and concatenating is the way to merge. */
 int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_str *err) {
-  return nish_spawn_impl(argv, out->len ? out->data : 0, err->len ? err->data : 0);
+  return nish_spawn_impl(argv, out->len ? out : 0, err->len ? err : 0);
 }
 
 /* `readdirSync(path)`: the listing a driver needs to discover its own inputs.
@@ -240,7 +275,7 @@ nish_array *nish_readdir(const nish_str *path) {
   (void)path;
   return 0;
 #else
-  DIR *d = opendir(path->data);
+  DIR *d = opendir(nish_cpath(path));
   if (!d) return 0;
   nish_array *a = nish_alloc_struct(sizeof *a);
   *a = (nish_array){ 0, 0, 0 };
@@ -252,15 +287,30 @@ nish_array *nish_readdir(const nish_str *path) {
     ((nish_str **)a->data)[a->len++] = nish_str_new(n, strlen(n));
   }
   closedir(d);
-  /* Insertion sort over pointers: a directory is short, and `qsort` would cost
-     a comparator symbol and its unwind entry for a call that is never hot. */
+  /* Heapsort over pointers, in place. It was an insertion sort, on the theory
+     that a directory is short, but whoever fills the directory decides that:
+     100,000 names took 2.5 billion compares and 12.5 s, where this takes 3.0
+     million and 0.07 s (docs/security/runtime.md, RT-5). It needs no scratch
+     memory, and unlike `qsort` costs no comparator symbol or unwind entry. */
   nish_str **v = (nish_str **)a->data;
-  for (uint64_t i = 1; i < a->len; i++) {
-    nish_str *s = v[i];
-    uint64_t j = i;
-    while (j && strcmp(v[j - 1]->data, s->data) > 0) {
-      v[j] = v[j - 1];
-      j--;
+  /* Each pass sifts one name down the max-heap `v[0, end)`: first every
+     parent from the middle up, which builds the heap, then the name the
+     largest is swapped out for, which shrinks the heap by one. */
+  uint64_t i = a->len / 2, end = a->len;
+  while (end > 1) {
+    nish_str *s;
+    if (i) {
+      s = v[--i];
+    } else {
+      s = v[--end];
+      v[end] = v[0];
+    }
+    uint64_t j = i, c;
+    while ((c = 2 * j + 1) < end) {
+      if (c + 1 < end && strcmp(v[c]->data, v[c + 1]->data) < 0) c++;
+      if (strcmp(s->data, v[c]->data) >= 0) break;
+      v[j] = v[c];
+      j = c;
     }
     v[j] = s;
   }
@@ -290,13 +340,8 @@ int64_t nish_monotonic_nanos(void) {
    string with the lifetime every other one has. NULL for an unset variable,
    which is the language's `string | null`. Contract: nish.h. */
 nish_str *nish_getenv(const nish_str *name) {
-  const char *v = getenv(name->data);
-  if (!v) return 0;
-  uint64_t len = strlen(v);
-  nish_str *s = nish_alloc_struct(8 + len + 1);
-  s->len = len;
-  memcpy(s->data, v, len + 1);
-  return s;
+  const char *v = getenv(nish_cpath(name));
+  return v ? nish_str_new(v, strlen(v)) : 0;
 }
 
 /* ---- Symlinks (WP19 §5a item 4): `realpathSync(path)`, the one path
@@ -321,12 +366,7 @@ nish_str *nish_getenv(const nish_str *name) {
    it resolves. Contract: nish.h. */
 nish_str *nish_realpath(const nish_str *path) {
   char buf[PATH_MAX];
-  if (!realpath(path->data, buf)) return 0;
-  uint64_t len = strlen(buf);
-  nish_str *s = nish_alloc_struct(8 + len + 1);
-  s->len = len;
-  memcpy(s->data, buf, len + 1);
-  return s;
+  return realpath(nish_cpath(path), buf) ? nish_str_new(buf, strlen(buf)) : 0;
 }
 
 /* ---- What machine this is (WP14 §7a): `process.platform` and `process.arch`,

package/runtime/runtime-parallel.c

@@ -109,7 +109,11 @@ void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t gra
   if (grain < 1) grain = 1;
   /* Never more threads than there is work for at the requested granularity,
    * and never more than the machine has. */
-  int64_t chunks = (len + grain - 1) / grain;
+  /* Rounded up without `len + grain - 1`, which overflows -- undefined
+     behaviour, and in practice a negative count that ran the whole range on
+     one thread -- once `len` is within `grain` of 2^63
+     (docs/security/runtime.md, RT-8). */
+  int64_t chunks = len / grain + (len % grain != 0);
   int64_t n = nish_cpu_count();
   if (n > NISH_PAR_MAX) n = NISH_PAR_MAX;
   if (chunks < n) n = chunks;

package/runtime/runtime-wasm.c

@@ -40,7 +40,14 @@ _Static_assert(offsetof(struct nish_arena, chunks) == 24, "arena layout is ABI")
 extern unsigned char __heap_base;
 #define NISH_PAGE ((uint64_t)65536)
 
-/* Slow path of the inlined allocator (`size` is already 8-byte rounded). */
+/* Slow path of the inlined allocator (`size` is already 8-byte rounded).
+ *
+ * `need` has to fit the 32-bit address space, and is checked before anything
+ * is grown (docs/security/runtime.md, RT-7). Without that, an `off + size` that
+ * wrapped 2^64 looked small and moved the offset backwards, and a page count
+ * past 2^32 truncated to the `uintptr_t` `memory.grow` takes: a request of
+ * 2^48 bytes grew nothing, claimed 2^48 bytes of capacity, and the next block
+ * landed at `buf + off` reduced mod 2^32, on top of live data. */
 void *nish_arena_grow(uint64_t size) {
   if (!nish_arena.buf) {
     uintptr_t base = ((uintptr_t)&__heap_base + 7) & ~(uintptr_t)7;
@@ -48,6 +55,7 @@ void *nish_arena_grow(uint64_t size) {
     nish_arena.cap = (uint64_t)__builtin_wasm_memory_size(0) * NISH_PAGE - base;
   }
   uint64_t need = nish_arena.off + size;
+  if (need < size || need > (uintptr_t)-1 - (uintptr_t)nish_arena.buf) __builtin_trap();
   if (need > nish_arena.cap) {
     uint64_t pages = (need - nish_arena.cap + NISH_PAGE - 1) / NISH_PAGE;
     if (__builtin_wasm_memory_grow(0, (uintptr_t)pages) == (uintptr_t)-1) __builtin_trap();
@@ -58,9 +66,12 @@ void *nish_arena_grow(uint64_t size) {
   return p;
 }
 
+/* `size <= cap - off` rather than `off + size <= cap`, which a size near 2^64
+   wraps into a yes; a size that rounding wraps to 0 is trapped the same way. */
 void *nish_alloc_struct(uint64_t size) {
+  if (size > (uint64_t)-8) __builtin_trap();
   size = (size + 7) & ~(uint64_t)7;
-  if (nish_arena.buf && nish_arena.off + size <= nish_arena.cap) {
+  if (nish_arena.buf && size <= nish_arena.cap - nish_arena.off) {
     void *p = nish_arena.buf + nish_arena.off;
     nish_arena.off += size;
     return p;
@@ -77,7 +88,15 @@ void nish_arena_release(uint64_t mark) { nish_arena.off = mark ? mark - (uintptr
 /* ---- Arrays: %struct.nish_array = type { i64, i64, i8* } */
 typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array;
 
+/* The length limit runtime.c's `nish_array_grow` and `nish_alloc_array` keep:
+   2^31 - 1 elements, so an i32-mode `length` is never negative. Past it the
+   wasm runtime traps, as it does for every other failure. */
+#define NISH_ARRAY_MAX 2147483647u
+
 nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len) {
+  /* With `len` in range, `len * elem_size` cannot wrap for any element
+     smaller than 8 GiB, and a product past 4 GiB traps in the grow. */
+  if (len > NISH_ARRAY_MAX) __builtin_trap();
   nish_array *a = (nish_array *)nish_alloc_struct(sizeof *a);
   a->len = a->cap = len;
   a->data = (char *)nish_alloc_struct(len * elem_size);
@@ -86,6 +105,10 @@ nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len) {
 
 void nish_array_grow(nish_array *a, uint64_t elem_size) {
   uint64_t cap = a->cap ? a->cap * 2 : 4;
+  if (cap > NISH_ARRAY_MAX) {
+    if (a->len >= NISH_ARRAY_MAX) __builtin_trap();
+    cap = NISH_ARRAY_MAX;
+  }
   char *data = (char *)nish_alloc_struct(cap * elem_size);
   if (a->len) __builtin_memcpy(data, a->data, (uintptr_t)(a->len * elem_size)); /* memory.copy (-mbulk-memory) */
   a->data = data;

package/runtime/runtime.c

@@ -83,7 +83,13 @@ static NISH_COLD void nish_die(const char *msg) {
   (void)!write(2, msg, strlen(msg));
   _exit(1);
 }
-#define nish_oom() nish_die("nish: out of memory\n")
+/* A function rather than a macro around `nish_die`: seven call sites each
+   loading the message's address cost more than one more symbol does. */
+static NISH_COLD void nish_oom(void) { nish_die("nish: out of memory\n"); }
+
+/* The most elements an array and the most bytes a string may hold: see
+   `nish_array_grow` and `nish_str_concat`. */
+#define NISH_ARRAY_MAX 2147483647u
 
 /* Slow path (size 8-byte rounded): push a chunk (>= 64 KB), bump from it. */
 void *nish_arena_grow(uint64_t size) {
@@ -196,9 +202,16 @@ nish_str *nish_str_new(const char *bytes, uint64_t len) {
   return s;
 }
 
+/* A string never passes 2^31 - 1 bytes, for the reason an array never passes
+   that many elements (`NISH_ARRAY_MAX`, below): under --number-mode i32 a
+   longer one's `length` reads back negative and bounds-check elimination
+   trusts it (docs/security/runtime.md, RT-2). `a + b` past it fails as an
+   allocation does. */
 nish_str *nish_str_concat(const nish_str *a, const nish_str *b) {
-  nish_str *s = nish_alloc_struct(8 + a->len + b->len + 1);
-  s->len = a->len + b->len;
+  uint64_t len = a->len + b->len;
+  if (len > NISH_ARRAY_MAX) nish_oom();
+  nish_str *s = nish_alloc_struct(8 + len + 1);
+  s->len = len;
   memcpy(s->data, a->data, a->len);
   memcpy(s->data + a->len, b->data, b->len);
   s->data[s->len] = 0;
@@ -1106,8 +1119,12 @@ double nish_random(void) {
 /* ---- Arrays: %struct.nish_array = type { i64, i64, i8* }, cold paths */
 typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array;
 
-/* Host entry (WP8): `len` uninitialised elements, len == cap */
+/* Host entry (WP8): `len` uninitialised elements, len == cap. A `len` past
+   `NISH_ARRAY_MAX` fails as an allocation does, which also keeps
+   `len * elem_size` from wrapping into a short block behind a long header
+   (docs/security/runtime.md, RT-7). */
 nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len) {
+  if (len > NISH_ARRAY_MAX) nish_oom();
   nish_array *a = nish_alloc_struct(sizeof *a);
   *a = (nish_array){ len, len, nish_alloc_struct(len * elem_size) };
   return a;
@@ -1160,9 +1177,26 @@ double nish_parse_number(const nish_str *s, int32_t mode) {
  * `sizeof` one element, which for a record element type (WP15 section 2a) is
  * the whole struct, so this relocates the elements themselves rather than a
  * block of pointers to them. Compiled code may therefore hold no pointer into
- * `data` across a push, and the checker refuses the programs that would. */
-void nish_array_grow(nish_array *a, uint64_t elem_size) {
+ * `data` across a push, and the checker refuses the programs that would.
+ *
+ * A push never takes an array past 2^31 - 1 elements (docs/security/codegen.md,
+ * K1-6). Under --number-mode i32 `length` is an `i32`, and one element more
+ * read back as a negative or a short length everywhere, a hash or a tag
+ * compare included. This file cannot tell which mode compiled its caller, so
+ * the limit holds in both, and the push past it fails as an allocation does,
+ * through `nish_oom`. `new Array(n)` checks its own `n` in the IR.
+ *
+ * `noinline`: under LTO the grown body was inlined into every push site, and
+ * the extra compare moved register allocation in the hot loops around them
+ * (+0.2% to +2% instructions over bench/instructions.json's map rows). Out of
+ * line, every one of those rows runs fewer instructions than it did before, and
+ * the call costs nothing on a path that runs once per doubling. */
+__attribute__((noinline)) void nish_array_grow(nish_array *a, uint64_t elem_size) {
   uint64_t cap = a->cap ? a->cap * 2 : 4;
+  if (cap > NISH_ARRAY_MAX) {
+    if (a->len >= NISH_ARRAY_MAX) nish_oom();
+    cap = NISH_ARRAY_MAX;
+  }
   char *data = nish_alloc_struct(cap * elem_size);
   if (a->len) memcpy(data, a->data, a->len * elem_size);
   a->data = data;

package/runtime/shim.mjs

@@ -740,6 +740,21 @@ 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,12 +3,13 @@
 #
 #   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm]
 #
-# The C runtime is four 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),
 # <dir>/runtime-parallel.c, the half that divides a range of work across
-# threads, and <dir>/runtime-host.c, the wall clock, entropy, file times and
-# signals. Each of those files says why they are compiled and measured apart.
+# 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.
@@ -84,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 four translation units, and a caller names one: whoever passes
-# <dir>/runtime.c gets <dir>/runtime-os.c, <dir>/runtime-parallel.c and
-# <dir>/runtime-host.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
@@ -98,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 runtime-host.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

@@ -19,22 +19,46 @@ whatever program imports it, and subject to the same rules as `examples/` or
 ## `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, and K4's key exchange, in pure Nish (decision S1), each module
-imported by its own specifier. Every one is written from its specification
-rather than ported, and reproduces that 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 and X25519 also run their vectors in `f64` (`crypto_*_f64`).
+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`).
+
+Every module here was security-audited (#363); the records are in
+[`docs/security/`](../docs/security/README.md), and how to report a
+vulnerability is in [`SECURITY.md`](../SECURITY.md). Two limits hold across the
+modules. **Lengths stop at 2^31 − 1.** No array built by `push` or `new Array`,
+and no array or string the runtime makes (a file read, a concatenation, a
+template), can pass 2^31 − 1 elements or bytes, and the one-shot functions
+below refuse a longer input as each row says. A string built by `join` still
+can, and under `--number-mode i32` its `length` is then wrong, which nothing in
+`std` can tell (CG-3, open): a program built in that mode must not hand these
+functions anything built from such a string. **Secrets are not wiped.** Private keys,
+nonces and intermediate state stay in arena memory after a call returns, until
+that memory is reused, because the language has no store the optimiser is
+barred from removing (ECC-2, X509-7, open).
 
 | 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/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`. `sha256` panics on an array longer than 2^31 − 1 bytes | 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`. The one-shot `sha512` and `sha384` panic on an array longer than 2^31 − 1 bytes | 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`. The one-shot functions panic on a message longer than 2^31 − 1 bytes | 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, for an `info` longer than 2^31 − 1 bytes, and for a PRK shorter than 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, and so does an array longer than 2^31 − 1 bytes | — |
+| [`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`, as does a text longer than 2^31 − 1 bytes; `base64urlEncode` panics on such an array | 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, Wycheproof `x25519_test` |
+| [`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, Wycheproof `chacha20_poly1305` (all 325 cases) |
+| [`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`, as does an `AesKey` not made by `aesKey`; one whose H is zero opens nothing | FIPS 197, SP 800-38D, RFC 9001 §5.4.3, Wycheproof `aes_gcm` (all 316 cases; the 103 AES-192 ones check that the key is refused) |
+| [`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 (`crypto/x509.ts`'s `x509DerSignatureRS` converts one). A malformed key, a point off the curve or an `r` or `s` out of range answers `null` or `false`, never a panic. ECDSA is malleable, and `p256Verify` accepts a high `s`: when `(r, s)` verifies, so does `(r, n − s)` | RFC 6979 A.2.5, Wycheproof `ecdsa_secp256r1_sha256`, `_sha256_p1363`, `_sha512` and `_sha512_p1363` |
+| [`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), `x509DerSignatureRS` (a DER ECDSA-Sig-Value as the `r || s` `crypto/p256.ts` takes), `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`. `x509ParseCertificate` and `x509ParseChain` parse and do not validate: there is no path validation, no extension is read or exposed, and no clock is consulted. `pemToDer` refuses a file in which any block, of any label, is malformed. `x509MintSelfSigned` refuses a common name that is not UTF-8 or holds a NUL, and its key and serial must come from `crypto.getRandomValues`, which the module cannot call itself without refusing wasm32 (X509-6) | X.690, RFC 5280, RFC 7468, RFC 5915, RFC 5208 / 5958; certificates checked against OpenSSL |
 
 Three rules hold across the modules:
 
@@ -45,16 +69,57 @@ Three rules hold across the modules:
   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, not yet by proof.** 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, 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. What checks
-  that the machine code kept that shape is WP34 N6 — the `ctSelect` / `ctEq`
-  builtins behind an optimisation barrier, and a disassembly check — and it is
-  not built yet, so this is the discipline and not a verified property.
+  low-order `u` gives, and RFC 7748 §6.1 leaves the check to the protocol.
+  Nothing in this tree makes that check yet (TLS 1.3, WP34 T1, is planned to),
+  so every caller doing a key exchange must refuse an all-zero answer itself,
+  with `timingSafeEqual` against 32 zero bytes, since the answer is a secret.
+- **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, a secret-addressed load, or a divide or square
+  root of a secret (whose latency follows its operands) in them. It reads what
+  `clang -O2` emits for each target's baseline CPU, and only the functions a
+  fixture names: the fixtures are copies of each module's straight-line cores,
+  so the module functions themselves, and every loop, rest on review.
+  [`docs/security/ct-verification.md`](../docs/security/ct-verification.md)
+  lists every secret-handling function no fixture reads. 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/hmac.ts`'s
+    verifiers compare in the first shape.
+  - `tests/cases/ct_asm_k1_ct`: copies of `timingSafeEqual`'s loop at 32 and
+    48 bytes and `timingSafeEqualAt`'s at a 16-byte window.
+  - `tests/cases/ct_asm_k1_base64url`: the two character maps verbatim, and
+    one encode group and one decode group. The length-driven loops, the
+    decoder's store guard and the encoder's string building 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
 

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.