@amritk/nish-x86_64-linux 0.17.0 → 0.20.0

package/std/net/tls/record.ts

@@ -11,12 +11,13 @@
  *
  * **Framing.** A record is a five-byte header — the content type, a legacy
  * version and a 16-bit length — and that many bytes. `TlsRecordReader` holds
- * the bytes of a stream that are not yet a whole record, in a buffer allocated
- * once and big enough for the largest record the RFC allows (2^14 + 256 bytes
- * of body), and says as soon as a header is in whether the record is one this
- * layer will read: a content type it does not know is `unexpected_message`,
- * and a length past the limit is `record_overflow`, before any of the body is
- * waited for. The legacy version is ignored, as §5.1 says it must be.
+ * the bytes of a stream that are not yet a whole record, in a buffer big
+ * enough for the largest record the RFC allows (2^14 + 256 bytes of body),
+ * borrowed from a `BufferPool` only while it holds any, and says as soon as
+ * a header is in whether the record is one this layer will read: a content
+ * type it does not know is `unexpected_message`, and a length past the limit
+ * is `record_overflow`, before any of the body is waited for. The legacy
+ * version is ignored, as §5.1 says it must be.
  *
  * **Protection.** `TlsRecordProtection` is one direction of a connection:
  * cleartext until `install` gives it a suite and a traffic secret, then
@@ -44,24 +45,32 @@
  * derived from it are held in the protection's fields, because a `Secret` may
  * not be one (NL2430), in arrays the protection reuses for every key it is
  * given, and are zeroed when it is installed again or cleared — the key and
- * IV with `secureZero`. The key and IV are derived straight into place, in an
- * HKDF scratch that is wiped after each derivation, and the schedule is
- * expanded into place by `aesKeyInto`. The schedule is `u64` words, which
- * `secureZero` does not take, and are zeroed by ordinary stores that stand
- * because it stays reachable (TLS-2 in `docs/security/tls.md`).
+ * IV with `secureZero`, the schedule with `aesKeyWipe`, the volatile `wipe`
+ * of its round keys (the kernels' powers of H included) and of H. The key and
+ * IV are derived straight into place, in an HKDF scratch that is wiped after
+ * each derivation, and the schedule is expanded into place by `aesKeyInto`
+ * (TLS-2 in `docs/security/tls.md`). A caller that holds the traffic secret
+ * as a `Secret` installs it with `installHeld` and ratchets it in place with
+ * `advanceHeld`, so the secret itself is never plain outside `exposeWith`.
  *
  * The record layer is sans-IO: `nish/net/tls/record-server` runs it over a
  * stream for `TlsServer`, and `nish/net/tls-tcp` puts that on a socket.
  * Written from RFC 8446 §5, not ported from another implementation.
  */
-import { AesKey, aesGcmOpen, aesGcmSeal, aesKeyInto } from "nish/crypto/aes"
+import { BufferPool } from "nish/net/buffer-pool"
+import { AesKey, aesGcmOpen, aesGcmSeal, aesKeyInto, aesKeyWipe } from "nish/crypto/aes"
 import { chacha20Poly1305Open, chacha20Poly1305Seal } from "nish/crypto/chacha20poly1305"
 import {
   TLS_ALERT_INTERNAL_ERROR,
   TLS_ALERT_UNEXPECTED_MESSAGE,
   TLS_LEGACY_VERSION,
 } from "nish/net/tls/codec"
-import { HkdfScratch, hkdfExpandLabelInto } from "nish/crypto/hkdf"
+import {
+  HkdfScratch,
+  hkdfExpandLabelInto,
+  hkdfExpandLabelSha256Held,
+  hkdfExpandLabelSha384Held,
+} from "nish/crypto/hkdf"
 import { SHA384_SIZE } from "nish/crypto/sha512"
 import {
   TLS_CHACHA20_POLY1305_SHA256,
@@ -69,8 +78,10 @@ import {
   tlsExpandLabel,
   tlsSuiteHashLength,
   tlsSuiteKeyLength,
+  tlsTrafficKeysFromHeld,
   tlsTrafficKeysInto,
 } from "nish/net/tls/schedule"
+import { Secret, expose } from "nish:secret"
 
 // ---- The wire's constants ------------------------------------------------------
 
@@ -134,11 +145,12 @@ const TLS_RECORD_FROM: i32 = 0
 /**
  * The traffic secret a KeyUpdate moves one direction to (RFC 8446 §7.2):
  * `HKDF-Expand-Label(secret, "traffic upd", "", Hash.length)` over the hash
- * `hashLength` names. The old secret is the caller's to wipe.
+ * `hashLength` names, held as a `Secret`. The old secret is the caller's to
+ * wipe.
  */
-export const tlsNextTrafficSecret = (hashLength: i32, secret: u8[]): u8[] => {
+export const tlsNextTrafficSecret = (hashLength: i32, trafficSecret: Secret<u8[]>): Secret<u8[]> => {
   const none: u8[] = []
-  return tlsExpandLabel(hashLength, secret, "traffic upd", none, hashLength)
+  return tlsExpandLabel(hashLength, trafficSecret, "traffic upd", none, hashLength)
 }
 
 /** Whether `[off, off + len)` is a window inside an array of `length` elements: every caller's range check. */
@@ -182,44 +194,65 @@ export const tlsRecordLength = (buf: u8[], off: i32, avail: i32): i32 => {
   return TLS_RECORD_HEADER_SIZE + length
 }
 
-/**
- * Zeroes an AES key schedule's round keys and H with ordinary stores, which
- * stand because the schedule stays reachable for the next key (TLS-2).
- */
-const tlsClearAesKey = (aes: AesKey): void => {
-  for (let k: i32 = 0; k < toI32(aes.roundKeys.length); k++) {
-    aes.roundKeys[k] = toU64(0)
-  }
-  aes.hHi = toU64(0)
-  aes.hLo = toU64(0)
-}
-
 /**
  * The bytes of a stream that are not yet a whole record. The buffer is
- * allocated once, `TLS_MAX_RECORD` bytes, so a reader never grows: `push`
- * takes what fits, and the bytes of a record stay until `consume` lets them
- * go. The caller reads `buffer[start .. start + next())` for the record.
+ * `TLS_MAX_RECORD` bytes, borrowed from `pool` by the first `push` that brings
+ * a byte, kept between records, and given back, zeroed with `giveSecret`, by
+ * `reset`, as its connection ends: a reader that has not been pushed to since
+ * holds no buffer at all. `push` takes what fits, and the
+ * bytes of a record stay until `consume` lets them go. The caller reads
+ * `buffer[start .. start + next())` for the record, while `next()` is above 0.
+ *
+ * A reader starts with a pool of its own, one buffer deep; `borrowFrom` points
+ * it at a pool a server shares between its slots.
  */
 export class TlsRecordReader {
+  // References, then 32-bit fields: the order the layout packs without padding.
+  /** The bytes held, or `empty` while the reader holds none. */
   buffer: u8[]
+  /** The zero-length array `buffer` is while no buffer is borrowed. */
+  empty: u8[]
+  /** Where `buffer` comes from and goes back to. */
+  pool: BufferPool
   /** The first byte not yet consumed. */
   start: i32 = 0
   /** One past the last byte pushed. */
   end: i32 = 0
 
   constructor() {
-    this.buffer = new Array<u8>(TLS_MAX_RECORD)
+    this.empty = []
+    this.buffer = this.empty
+    this.pool = new BufferPool("TlsRecordReader.buffer", TLS_MAX_RECORD, 1)
+  }
+
+  /**
+   * Borrows from `pool` from now on, giving back first, zeroed, any buffer
+   * held from the old one. Every byte held is forgotten, as `reset` does.
+   */
+  borrowFrom(pool: BufferPool): void {
+    this.reset()
+    this.pool = pool
   }
 
-  /** Forgets every byte, for a connection that starts again in the same slot. */
+  /** Forgets every byte, for a connection that starts again in the same slot, and gives the buffer back. */
   reset(): void {
     this.start = 0
     this.end = 0
+    this.giveBack()
+  }
+
+  /** Gives the buffer back, zeroed, if one is held. */
+  giveBack(): void {
+    if (this.buffer.length > 0) {
+      // Every byte of it may have held a record: zero all of it.
+      this.pool.giveSecret(this.buffer, TLS_MAX_RECORD)
+      this.buffer = this.empty
+    }
   }
 
   /** How many bytes `push` would take now. */
   space(): i32 {
-    return toI32(this.buffer.length) - (this.end - this.start)
+    return TLS_MAX_RECORD - (this.end - this.start)
   }
 
   /**
@@ -231,16 +264,22 @@ export class TlsRecordReader {
     if (!tlsRecordWindowFits(toI32(data.length), off, len)) {
       return -TLS_ALERT_INTERNAL_ERROR
     }
+    if (len === 0) {
+      return 0
+    }
+    if (this.buffer.length === 0) {
+      this.buffer = this.pool.take()
+    }
     const held: i32 = this.end - this.start
     // The held bytes move to the front only when the new ones would not fit after them.
-    if (this.start > 0 && toI32(this.buffer.length) - this.end < len) {
+    if (this.start > 0 && TLS_MAX_RECORD - this.end < len) {
       for (let k: i32 = 0; k < held; k++) {
         this.buffer[k] = this.buffer[this.start + k]
       }
       this.start = 0
       this.end = held
     }
-    const room: i32 = toI32(this.buffer.length) - this.end
+    const room: i32 = TLS_MAX_RECORD - this.end
     const take: i32 = len < room ? len : room
     for (let k: i32 = 0; k < take; k++) {
       this.buffer[this.end + k] = data[off + k]
@@ -260,7 +299,11 @@ export class TlsRecordReader {
     return length > avail ? 0 : length
   }
 
-  /** Lets the first `n` held bytes go: the record `next` answered, once it is handled. */
+  /**
+   * Lets the first `n` held bytes go: the record `next` answered, once it is
+   * handled. When none are left the next record starts at the front; the
+   * buffer stays until `reset`.
+   */
   consume(n: i32): void {
     const held: i32 = this.end - this.start
     let take: i32 = n < held ? n : held
@@ -334,16 +377,16 @@ export class TlsRecordProtection {
 
   /**
    * Back to cleartext, with the sequence number at 0 and both keys, the IV
-   * and both AES key schedules zeroed: the keys and IV with `secureZero`,
-   * and the schedules' `u64` words with ordinary stores, which stand because
-   * the schedules stay reachable for the next `install` to fill (TLS-2).
+   * and both AES key schedules wiped: the keys and IV with `secureZero`, and
+   * each schedule with `aesKeyWipe`, its whole `roundKeys` and its H, which
+   * the next `install` fills again (TLS-2).
    */
   clear(): void {
     secureZero(this.key16)
     secureZero(this.key32)
     secureZero(this.iv)
-    tlsClearAesKey(this.aes128)
-    tlsClearAesKey(this.aes256)
+    aesKeyWipe(this.aes128)
+    aesKeyWipe(this.aes256)
     this.suite = 0
     this.sequence = 0
     this.contentType = 0
@@ -443,6 +486,54 @@ export class TlsRecordProtection {
     return this.install(suite, secret)
   }
 
+  /**
+   * `install` from a traffic secret the caller holds as a `Secret`: the key
+   * and IV are derived from it straight into this direction's arrays, the
+   * plain output of each derivation wiped, and the AES key schedule expanded
+   * into place inside an arena block, as `derive`'s is. `false`, leaving the
+   * direction cleartext, where `install` answers it.
+   */
+  installHeld(suite: i32, secret: Secret<u8[]>): boolean {
+    this.clear()
+    const hashLength: i32 = tlsSuiteHashLength(suite)
+    if (hashLength === 0 || expose(secret, (bytes: u8[]): i32 => toI32(bytes.length)) !== hashLength) {
+      return false
+    }
+    this.reserve(suite)
+    tlsTrafficKeysFromHeld(suite, secret, this.key, this.iv)
+    const aes: AesKey | null = this.aes
+    if (aes !== null && suite !== TLS_CHACHA20_POLY1305_SHA256) {
+      using _scope = arena()
+      aesKeyInto(this.key, aes)
+    }
+    this.suite = suite
+    return true
+  }
+
+  /**
+   * `advance` on a traffic secret the caller holds as a `Secret`: the next
+   * traffic secret (§7.2) is written over `secret`'s bytes in place, a
+   * ratchet that leaves no copy of either, and the keys are installed from
+   * it with `installHeld`. False, as `advance` answers, when the keys do not
+   * install; a secret that is not its hash's length is left as it was.
+   */
+  advanceHeld(secret: Secret<u8[]>): boolean {
+    const suite: i32 = this.suite
+    const hashLength: i32 = tlsSuiteHashLength(suite)
+    if (hashLength === 0) {
+      return false
+    }
+    if (expose(secret, (bytes: u8[]): i32 => toI32(bytes.length)) === hashLength) {
+      const none: u8[] = []
+      if (hashLength === SHA384_SIZE) {
+        hkdfExpandLabelSha384Held(secret, secret, "traffic upd", none)
+      } else {
+        hkdfExpandLabelSha256Held(secret, secret, "traffic upd", none)
+      }
+    }
+    return this.installHeld(suite, secret)
+  }
+
   /** The per-record nonce (§5.3): the IV with the sequence number XORed into its last eight bytes, big-endian. */
   nonceInto(nonce: u8[]): void {
     for (let k: i32 = 0; k < TLS_IV_SIZE && k < toI32(nonce.length) && k < toI32(this.iv.length); k++) {