nish/net/tls/record

The TLS 1.3 record layer (RFC 8446 §5): the framing of a byte stream into records, the protection of one direction of it under a traffic secret, and the next secret a KeyUpdate moves to.

import {
  TLS_ALERT_BAD_RECORD_MAC,
  TLS_ALERT_CLOSE_NOTIFY,
  TLS_ALERT_LEVEL_FATAL,
  TLS_ALERT_LEVEL_WARNING,
  TLS_ALERT_RECORD_OVERFLOW,
  TLS_ALERT_USER_CANCELED,
  TLS_CONTENT_ALERT,
  TLS_CONTENT_APPLICATION_DATA,
  TLS_CONTENT_CHANGE_CIPHER_SPEC,
  TLS_CONTENT_HANDSHAKE,
  TLS_HANDSHAKE_KEY_UPDATE,
  TLS_KEY_UPDATE_RECORDS,
  TLS_LAST_SEQUENCE,
  TLS_MAX_CIPHERTEXT,
  TLS_MAX_PLAINTEXT,
  TLS_MAX_RECORD,
  TLS_RECORD_HEADER_SIZE,
  TLS_RECORD_TAG_SIZE,
  TlsRecordProtection,
  TlsRecordReader,
  tlsNextTrafficSecret,
  tlsRecordLength,
  tlsRecordWindowFits,
} from "nish/net/tls/record";
import { TlsRecordProtection, TlsRecordReader } from "nish/net/tls/record";

const write = new TlsRecordProtection();
write.install(TLS_AES_128_GCM_SHA256, serverApplicationSecret);
const n: i32 = write.seal(TLS_CONTENT_APPLICATION_DATA, data, 0, len, 0, out, at);
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 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 TLSCiphertext (§5.2) under the AEAD the suite names. Each record's nonce is the traffic IV XORed with the 64-bit record sequence number (§5.3), and its additional data is the record's own header.

Inside, the content is followed by its real type and by zero padding (§5.4); open finds the type by reading every byte of the decrypted record whatever the padding is, so how much padding there was is not in its timing, and refuses a record that is padding and nothing else. Both seal and open write into a buffer the caller owns and answer a count, and what they allocate on the way dies with the call (docs/LANGUAGE.md, "Memory model"), so a connection that has finished its handshake moves records without moving the arena.

Refusals are alerts. Every function that can refuse answers the alert to send, negated, as a negative count: -TLS_ALERT_BAD_RECORD_MAC for a record that does not authenticate, -TLS_ALERT_RECORD_OVERFLOW for one past the limits, -TLS_ALERT_UNEXPECTED_MESSAGE for a type that cannot be here, and -TLS_ALERT_INTERNAL_ERROR for a mistake of the caller's — a window outside its array, an output too small, content over 2^14 bytes. Nothing the peer sends can make it panic.

Secrets

A traffic secret arrives as plain bytes, since that is how nish/net/tls hands it over.

The key, the IV and the AES key schedule 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 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.

Functions

tlsNextTrafficSecret

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, held as a Secret. The old secret is the caller's to wipe.

const tlsNextTrafficSecret: (
  hashLength: i32,
  trafficSecret: Secret<u8[]>,
) => Secret<u8[]>
hashLengthi32required

The hash length of the connection's suite, 32 or 48, and so how many bytes are derived.

trafficSecretSecret<u8[]>required

The direction's current traffic secret. This function does not wipe it.

returnsSecret<u8[]>

A fresh Secret holding the next traffic secret, which the caller owns and wipes.

tlsRecordLength

The length of the record whose header starts at buf[off], header included, read from the avail bytes there: 0 while fewer than five are in, or the alert negated when the header announces a type this layer does not know (unexpected_message) or a body past 2^14 + 256 bytes (record_overflow, §5.2). The legacy version is not read (§5.1).

const tlsRecordLength: (
  buf: u8[],
  off: i32,
  avail: i32,
) => i32
bufu8[]required

The array that holds the bytes received so far.

offi32required

Where in buf the record's header starts.

availi32required

How many bytes, from off, have arrived.

returnsi32

The whole record's length in bytes, header included; 0 while the header is not all in; -TLS_ALERT_UNEXPECTED_MESSAGE or -TLS_ALERT_RECORD_OVERFLOW for a header this layer refuses; -TLS_ALERT_INTERNAL_ERROR when buf[off .. off + avail) is not inside buf.

tlsRecordWindowFits

Whether [off, off + len) is a window inside an array of length elements: every caller's range check. It is written as off <= length - len, not off + len <= length, so a large off cannot overflow.

const tlsRecordWindowFits: (
  length: i32,
  off: i32,
  len: i32,
) => boolean
lengthi32required

How many elements the array has.

offi32required

Where the window starts.

leni32required

How many elements the window spans.

returnsboolean

true when off and len are not negative and the window ends at or before length.

Classes

TlsRecordProtection

One direction of a connection's record protection. Cleartext (suite 0) until install; then every record is sealed or opened under the suite's AEAD with the key and IV of the traffic secret it was given, and its sequence number counts from 0. contentType is the type the last open found inside a protected record, or the header's type for a cleartext one.

Every array it fills is made by the constructor: a key of each length, an AES key schedule of each size, the IV, the next traffic secret of each hash, and the HKDF scratch the keys are derived in. key and aes point at the ones the installed suite uses, so changing suites allocates nothing.

class TlsRecordProtection
Member
new TlsRecordProtection() Makes a cleartext direction and every array it will fill, so that no install allocates. The record limit starts at TLS_KEY_UPDATE_RECORDS.
aes: AesKey | null The AES key schedule for the two AES-GCM suites, the one of the installed key's size.
aes128: AesKey The expanded AES-128 key schedule aes points to under AES-128-GCM, 10 rounds; clear wipes it.
aes256: AesKey The expanded AES-256 key schedule aes points to under AES-256-GCM, 14 rounds; clear wipes it.
contentType: i32 The real content type of the last record open answered.
iv: u8[] The 12-byte traffic IV (§7.3), zeroed while the direction is cleartext.
key: u8[] The AEAD key (§7.3): the suite's key length, zeroed while the direction is cleartext.
key16: u8[] The arrays key and aes point into: AES-128's and ChaCha20's or AES-256's.
key32: u8[] The 32-byte key array key points into for ChaCha20-Poly1305 and AES-256-GCM; clear zeroes it.
next: u8[] Where advance derives the next traffic secret: HashLen bytes of it.
recordLimit: i64 The sequence number at which a writer moves to the next key. Readable and writable, so a test can bring the key update forward; a reader ignores it.
sequence: i64 The next record's sequence number (§5.3).
advance(secret: u8[]): boolean Moves this direction to the next traffic secret (§7.2), the KeyUpdate step: secret, the current one, is overwritten in place by the next, and the keys are installed from it; the next secret's own copy is wiped. The next secret is derived in place inside an arena block, as derive's keys are. False, as install answers, when the keys do not install.
advanceHeld(secret: Secret<u8[]>): boolean 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.
install(suite: i32, secret: u8[]): boolean Protects this direction under secret from the next record on: the suite's key and IV (§7.3), the sequence number back to 0, and what this replaces zeroed by clear. false, leaving the direction cleartext, for a suite nish/net/tls/schedule does not know or a secret that is not its hash's length.

The key, the IV and the AES key schedule are written into the arrays this direction made when it was constructed, so an install allocates nothing that outlives it (TLS-3).
installHeld(suite: i32, secret: Secret<u8[]>): boolean 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.
isProtected(): boolean Whether records in this direction are protected.
nonceInto(nonce: u8[]): void The per-record nonce (§5.3): the IV with the sequence number XORed into its last eight bytes, big-endian.
open(record: u8[], off: i32, len: i32, out: u8[], at: i32): i32 Reads the whole record record[off .. off + len), header included, and writes its content at out[at]: answers the content's length and sets contentType. Cleartext, the content is the body and the type the header's: application_data is unexpected_message, since it is never sent in the clear, and a body over 2^14 bytes is record_overflow.

Protected, the header's type must be application_data (unexpected_message otherwise), the body must authenticate under this record's nonce with the header as additional data (bad_record_mac), the decrypted record may be no longer than 2^14 + 1 bytes (record_overflow), and its last non-zero byte is the real type — one that is all zeros is unexpected_message (§5.4). Every refusal is the alert negated; a window outside record, a len that is not the header's, or too little room at out[at] is -TLS_ALERT_INTERNAL_ERROR.

A protected record that fails to authenticate leaves the sequence number where it was; one that authenticates spends its number even when its content is then refused.
seal(type: i32, data: u8[], off: i32, len: i32, padding: i32, out: u8[], at: i32): i32 Writes one record of content type type holding data[off .. off + len) at out[at] and answers its length, header included. Cleartext, it is a TLSPlaintext, padding must be 0 and type may not be application_data; protected, it is a TLSCiphertext whose inner plaintext carries type and then padding zero bytes (§5.4), and the sequence number moves on. -TLS_ALERT_INTERNAL_ERROR, with nothing written, for content over 2^14 bytes, a padding that would take the inner plaintext past 2^14 + 1, a window outside data, too little room at out[at], or a sequence number that would wrap.

TlsRecordReader

The bytes of a stream that are not yet a whole record. The buffer is 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.

class TlsRecordReader
Member
new TlsRecordReader() Makes an empty reader with a pool of its own, one buffer deep. No buffer is taken until the first push brings a byte.
buffer: u8[] The bytes held, or empty while the reader holds none.
end: i32 One past the last byte pushed.
start: i32 The first byte not yet consumed.
consume(n: i32): void 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.
next(): i32 The length of the whole record at start, header included, once every byte of it is in; 0 before; or the alert negated for a header this layer refuses, as tlsRecordLength says.
push(data: u8[], off: i32, len: i32): i32 Copies as many of data[off .. off + len) as fit and answers how many, after moving what is held to the front. A window outside data is -TLS_ALERT_INTERNAL_ERROR, and nothing is copied.
reset(): void Forgets every byte, for a connection that starts again in the same slot, and gives the buffer back.
space(): i32 How many bytes push would take now.

Limits

16,640

TLS_MAX_CIPHERTEXT: i32

The longest body a protected record may have: 2^14 + 256 bytes (§5.2).

16,384

TLS_MAX_PLAINTEXT: i32

The most content one record carries: 2^14 bytes (§5.1).

16,645

TLS_MAX_RECORD: i32

The longest whole record, header included.

Constants

20

TLS_ALERT_BAD_RECORD_MAC: i32

bad_record_mac: a protected record did not authenticate.

0

TLS_ALERT_CLOSE_NOTIFY: i32

close_notify (§6.1): the sender writes nothing more.

2

TLS_ALERT_LEVEL_FATAL: i32

An alert's level byte for every error alert.

1

TLS_ALERT_LEVEL_WARNING: i32

An alert's level byte for close_notify and user_canceled. TLS 1.3 reads nothing into it (§6).

22

TLS_ALERT_RECORD_OVERFLOW: i32

record_overflow: a record longer than the limits allow.

90

TLS_ALERT_USER_CANCELED: i32

user_canceled (§6.1): a warning that the peer is abandoning the handshake; a close follows.

21

TLS_CONTENT_ALERT: i32

alert (§6): a level and a description.

23

TLS_CONTENT_APPLICATION_DATA: i32

application_data, and the outer type of every protected record.

20

TLS_CONTENT_CHANGE_CIPHER_SPEC: i32

change_cipher_spec: the compatibility record of RFC 8446 §D.4, one byte of 1.

22

TLS_CONTENT_HANDSHAKE: i32

handshake (§4).

24

TLS_HANDSHAKE_KEY_UPDATE: i32

The KeyUpdate handshake message (§4.6.3).

16,777,216

TLS_KEY_UPDATE_RECORDS: i64

How many records one key protects before a writer moves to the next with a KeyUpdate: 2^24. AES-GCM's limit is 2^24.5 full-size records per key (RFC 8446 §5.5), and this is under it with room; ChaCha20-Poly1305's is far past it, and one rule for all three suites keeps the writer simple.

9,007,199,254,740,991

TLS_LAST_SEQUENCE: i64

The sequence number no record is sealed or opened at: 2^53 − 1. The counter must never wrap (§5.3), and stopping here, at a number no connection reaches, keeps the i64 it is held in far from its own overflow.

5

TLS_RECORD_HEADER_SIZE: i32

The bytes before a record's body: its type, a legacy version and a 16-bit length.

16

TLS_RECORD_TAG_SIZE: i32

The AEAD tag every protected record ends with; all three suites' is 16 bytes.