nish/net/tls/ticket

TLS 1.3 session tickets a server seals for itself (RFC 8446 §4.6.1), and the strike register that makes each one single-use (§8.1). docs/security/tls.md, "Resumption", is the design this follows.

import {
  TLS_TICKET_CHAIN_LIMIT,
  TLS_TICKET_KEY_ID_SIZE,
  TLS_TICKET_KEY_SIZE,
  TLS_TICKET_LIFETIME_SECONDS,
  TLS_TICKET_NONCE_SIZE,
  TLS_TICKET_OPEN_WINDOW,
  TLS_TICKET_PSK_MAX,
  TLS_TICKET_SEAL_CAP,
  TLS_TICKET_SEAL_WINDOW,
  TLS_TICKET_SERVER_NAME_MAX,
  TLS_TICKET_STRIKES_DEFAULT,
  TlsTicketKeyInfo,
  TlsTicketState,
  TlsTicketStrikes,
  tlsTicketKeyDraw,
  tlsTicketKeyDue,
  tlsTicketOpen,
  tlsTicketSeal,
  tlsTicketSize,
} from "nish/net/tls/ticket";
import {
  TLS_TICKET_STRIKES_DEFAULT, TlsTicketKeyInfo, TlsTicketState, TlsTicketStrikes,
  tlsTicketKeyDraw, tlsTicketKeyDue, tlsTicketOpen, tlsTicketSeal, tlsTicketSize,
} from "nish/net/tls/ticket";
import { monotonicNanos } from "nish:process";
import { wipe } from "nish:secret";
// secureZero is a builtin and needs no import

const info = new TlsTicketKeyInfo()
const key = tlsTicketKeyDraw(info, monotonicNanos())
const strikes = new TlsTicketStrikes(TLS_TICKET_STRIKES_DEFAULT)

// Issuing: `state` is a TlsTicketState the server filled from a finished handshake.
const ticket: u8[] = new Array<u8>(tlsTicketSize(state))
const written = tlsTicketSeal(key, info, state, monotonicNanos(), ticket)  // 0: send no ticket

// Resuming (`TlsServer.resume` does this for a server): `offered` is a ticket the client sent.
const now = monotonicNanos()
const opened = new TlsTicketState()
const fresh = tlsTicketOpen(key, info, offered, now, opened)
if (fresh && strikes.take(opened.id, opened.expiresAt(), now)) {
  // resume with opened.psk[0 .. opened.pskLength), then secureZero(opened.psk)
}
// when tlsTicketKeyDue(info, now), rotate as "Keys" below says; wipe(key) before it goes
The ticket

A ticket is the key id (16 bytes, public, the additional data) ‖ a fresh random nonce (12) ‖ the ChaCha20-Poly1305 ciphertext of the state ‖ its tag (16). The state is what a resumed handshake reads: the suite, the time the ticket was issued, its lifetime, the time of the full handshake its chain started from, the server name, and the resumption PSK. Its plaintext is the suite (2 bytes), the issue time (8), the lifetime in seconds (4), the chain start (8), the server name with a one-byte length, and the PSK with a one-byte length, every integer big-endian.

Time

Every time is monotonicNanos(), read by the caller outside expose and handed in as now: keys never leave the process, so neither does a ticket, and a clock that cannot step keeps the strike register honest.

Keys

A ticket key is a Secret<u8[]> of 32 random bytes, which no class may hold (NL2430): the program keeps its current and previous keys in locals and lends them to tlsTicketSeal and tlsTicketOpen, which read them only inside exposeWith. Beside each key it keeps a TlsTicketKeyInfo — the id, the time it was drawn, how many tickets it has sealed, and its seal cap. tlsTicketKeyDraw draws a key into a record and tlsTicketKeyDue says when to replace it. The rotation turn is the program's, because a function hands back one Secret and may not reassign a borrowed one: wipe(previous), previous = current, previousInfo.copyFrom(currentInfo), current = tlsTicketKeyDraw(currentInfo, now).

What the module enforces from the record

A key seals for 12 hours of awake time after its draw and until its seal cap (2^30 tickets), and opens for 14 hours, inclusive; a ticket opens while now is no earlier than its issue time, no later than issue time plus lifetime, and no later than 24 hours after its chain started, and only when its sealed lifetime is at most 7200 s and its chain start is no later than its issue time.

Wiping

The plaintext of a seal or an open is a plain u8[] made in a using a = arena() block, wiped with secureZero once, at the point every path reaches; a failed open also wipes the state's PSK array. The seal's exposed function wipes the copy of the plaintext it hands the AEAD, and what the AEAD makes from the key is wiped by the AEAD (nish/crypto/chacha20poly1305).

`TlsTicketStrikes`

TlsTicketStrikes records each ticket's id (its nonce) until the ticket expires or 7200 s after the recording, whichever is sooner, in a table made once at its capacity. It never grows and fails closed when full.

Written from the RFC and the design record, not ported from another implementation. Private names carry the tlsTicket prefix because a std/ module's private functions share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

tlsTicketKeyDraw

Draws a fresh key: 32 random bytes moved into the Secret it answers, a fresh random id in info, now as its creation time and a count of 0. The seal cap is left as the program set it.

const tlsTicketKeyDraw: (
  info: TlsTicketKeyInfo,
  now: i64,
) => Secret<u8[]>
infoTlsTicketKeyInforequired

The record to fill for the new key; its old id, time and count are overwritten.

nowi64required

The draw time, in monotonicNanos().

returnsSecret<u8[]>

The new key, owned by the caller, who keeps it in a local and wipes it when it is replaced.

tlsTicketKeyDue

True when the key info describes should be replaced: at the end of its issue window, or at its seal cap.

const tlsTicketKeyDue: (
  info: TlsTicketKeyInfo,
  now: i64,
) => boolean
infoTlsTicketKeyInforequired

The current key's record.

nowi64required

The time to judge at, in monotonicNanos().

returnsboolean

True when the program should rotate now; the key still opens tickets for a while after.

tlsTicketOpen

Opens ticket under key, the key info describes, into out, and answers whether it opened at now. False — with nothing of the key read — when the ticket names another key id or the key is past 14 hours of awake time; false when the tag does not verify, the plaintext is malformed, or the ticket is outside its bounds (tlsTicketParse). On true, out holds the state and the ticket's nonce in id, its strike-register id. On false after the AEAD ran, the state's PSK array is wiped. The plaintext is wiped once, after the branch on the tag and on the parse, so the one wipe covers every path.

const tlsTicketOpen: (
  key: Secret<u8[]>,
  info: TlsTicketKeyInfo,
  ticket: u8[],
  now: i64,
  out: TlsTicketState,
) => boolean
keySecret<u8[]>required

The ticket key, lent: it is read only inside exposeWith, and stays the caller's to wipe.

infoTlsTicketKeyInforequired

The key's record, whose id the ticket must name.

ticketu8[]required

The ticket as the client sent it: key id, nonce, ciphertext and tag.

nowi64required

The time to judge the key and the ticket at, in monotonicNanos().

outTlsTicketStaterequired

The state to fill; its PSK array holds secret bytes on true, which the caller wipes once used.

returnsboolean

True when the ticket opened and is within its bounds; it is not yet checked against the strike register, which TlsTicketStrikes.take does.

tlsTicketSeal

Seals state under key, the key info describes, into out from index 0, and answers the ticket's length; 0 when it seals nothing: a key past its issue window or at its seal cap, a state tlsTicketSize refuses, or an out too short. The issue time sealed is now, which is also written to state.issuedAt; the nonce is drawn fresh, and info counts the ticket. The plaintext is built after the key id and nonce in one array, the one exposeWith hands its function, and wiped once, after the seal and its refusals.

const tlsTicketSeal: (
  key: Secret<u8[]>,
  info: TlsTicketKeyInfo,
  state: TlsTicketState,
  now: i64,
  out: u8[],
) => i32
keySecret<u8[]>required

The ticket key, lent: it is read only inside exposeWith, and stays the caller's to wipe.

infoTlsTicketKeyInforequired

The key's record: its id heads the ticket and its count goes up by one on a seal.

stateTlsTicketStaterequired

What the ticket carries; its issuedAt is overwritten with now, unless the key cannot seal at now, the state does not fit a ticket or out is too short.

nowi64required

The issue time, in monotonicNanos().

outu8[]required

Where the ticket is written, from index 0; at least tlsTicketSize(state) bytes.

returnsi32

How many bytes of out hold the ticket, or 0 when nothing was sealed.

tlsTicketSize

The bytes tlsTicketSeal makes of state, 0 when it cannot seal it: a suite this server does not know, a PSK of another length than its hash, or a server name longer than 255 bytes, which is issued no ticket.

const tlsTicketSize: (state: TlsTicketState) => i32
stateTlsTicketStaterequired

The state to be sealed, with its suite, server name and PSK lengths set.

returnsi32

The ticket's length in bytes, the least out that tlsTicketSeal accepts, or 0.

Classes

TlsTicketKeyInfo

A ticket key's public record. A class, so the program may keep it in a field or anywhere else; the key it describes is a Secret the program keeps in a local.

class TlsTicketKeyInfo
Member
new TlsTicketKeyInfo() Makes a blank record, nothing sealed yet and the cap at TLS_TICKET_SEAL_CAP, for tlsTicketKeyDraw to fill.
createdAt: i64 When the key was drawn, in monotonicNanos().
id: u8[] The key id, the ticket's additional data.
sealCap: i64 How many it may seal: TLS_TICKET_SEAL_CAP unless the program lowers it.
sealed: i64 How many tickets the key has sealed.
copyFrom(other: TlsTicketKeyInfo): void Copies other into this record, as the rotation turn does from the current key's to the previous one's. The id is copied byte by byte into this record's own array, so the two records share nothing.

TlsTicketState

What a ticket carries: filled by the server before tlsTicketSeal, and by tlsTicketOpen from a ticket that opens. Made once and reused; the server name and PSK are windows of fixed arrays, serverNameLength and pskLength bytes long.

class TlsTicketState
Member
new TlsTicketState() Makes an empty state, its server name and PSK arrays at their fixed sizes and both lengths 0.
chainStart: i64 When the full handshake this ticket's chain started from ran.
id: u8[] The ticket's nonce, written by tlsTicketOpen: its id in the strike register.
issuedAt: i64 When the ticket was issued, in monotonicNanos(): tlsTicketSeal writes its now here.
lifetime: i32 The ticket's lifetime in seconds, at most TLS_TICKET_LIFETIME_SECONDS.
psk: u8[] The resumption PSK, pskLength bytes of it: the suite's hash length.
pskLength: i32 How many bytes of psk the PSK fills: 32 or 48, the suite's hash length.
serverName: u8[] The server name the session agreed, serverNameLength bytes of it; none when the client sent none.
serverNameLength: i32 How many bytes of serverName the name fills, 0 to TLS_TICKET_SERVER_NAME_MAX; 0 when the client sent no name.
suite: i32 The cipher suite the session agreed.
expiresAt(): i64 When the ticket stops opening: its issue time plus its lifetime. It opens at that instant, and not after.

TlsTicketStrikes

The strike register (§8.1): the ids of the tickets this process has accepted, each held until its ticket expires or one server lifetime after it was recorded, whichever is sooner, so that a ticket resumes at most once. An open-addressed table with linear probing, made once at the capacity the program gives (TLS_TICKET_STRIKES_DEFAULT unless it has a better figure) and never grown: an expired entry is reused, and when no entry is free take refuses and counts the refusal, failing closed. A slot never used ends a probe chain; a slot once used never is unused again, so every live entry of an id sits on its chain before the first unused slot.

class TlsTicketStrikes
Member
new TlsTicketStrikes(capacity: i32) Makes the whole table now, so that no take ever allocates; it panics on a capacity below 1.
filled: i32 How many ids are held or were held and expired: slots ever used.
longest: i32 The farthest from its home slot any id has been recorded: no entry of an id lies further along its chain. net/tls.ts reads it to stop a probe.
refusedFull: i64 How many takes were refused because no entry was free.
count(id: u8[]): i32 How many entries hold id, live or expired: what the tests read to see one id recorded once. It walks the whole table, so it is for tests and diagnostics, not for the handshake.
home(id: u8[]): i32 The slot an id's probe chain starts at: FNV-1a over its bytes.
live(now: i64): i32 How many entries are held at now.
take(id: u8[], expiresAt: i64, now: i64): boolean Records id until min(expiresAt, now + 7200 s) and answers true; false when id is still held, or when no entry is free, which is counted in refusedFull. The probe chain is scanned for a live entry of id as far as longest, the farthest any id has been recorded from its home, before an expired slot on it is reused, so an expired entry ahead of the id's live one cannot let it be recorded twice. Past that bound the scan only looks for a free slot and stops at the first, so a take costs the longest probe so far, not the capacity. An id of another length than a nonce is refused, uncounted.

Limits

TLS_​TICKET_​CHAIN_​LIMIT

TLS_TICKET_CHAIN_LIMIT: i64

The longest a chain of resumptions runs after the full handshake it started from: 24 hours.

48

TLS_TICKET_PSK_MAX: i32

The longest resumption PSK: SHA-384's length.

1,073,741,824

TLS_TICKET_SEAL_CAP: i64

How many tickets a key seals before tlsTicketSeal refuses it: 2^30.

255

TLS_TICKET_SERVER_NAME_MAX: i32

The longest server name a ticket carries: a session with a longer one is issued none.

Constants

16

TLS_TICKET_KEY_ID_SIZE: i32

A ticket key's id, sent in the clear at the head of each ticket it seals.

CHACHA20_​KEY_​SIZE

TLS_TICKET_KEY_SIZE: i32

A ticket key: 32 bytes, ChaCha20-Poly1305's key size.

7,200

TLS_TICKET_LIFETIME_SECONDS: i32

The ticket_lifetime this server sends, and the longest a ticket it opens may claim, in seconds.

CHACHA20​POLY1305_​NONCE_​SIZE

TLS_TICKET_NONCE_SIZE: i32

A ticket's nonce, which is also its id in the strike register.

TLS_​TICKET_​OPEN_​WINDOW

TLS_TICKET_OPEN_WINDOW: i64

How long after its draw a key opens tickets: its issue window and one lifetime more, 14 hours.

TLS_​TICKET_​SEAL_​WINDOW

TLS_TICKET_SEAL_WINDOW: i64

A key's issue window: 12 hours of awake time after its draw, in nanoseconds.

65,536

TLS_TICKET_STRIKES_DEFAULT: i32

The strike register's capacity when the program has no other figure: 65,536 ids, about 1.3 MB.