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
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.
tlsTicketKeyDue
True when the key info describes should be replaced: at the end of its issue window, or at its seal cap.
tlsTicketOpen
Opens ticket under key, the key info describes, into out, and answers whether it opened at now.
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.
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.
TlsTicketKeyInfo
A ticket key's public record.
TlsTicketState
What a ticket carries: filled by the server before tlsTicketSeal, and by tlsTicketOpen from a ticket that opens.
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.
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[]>
infoTlsTicketKeyInforequiredThe record to fill for the new key; its old id, time and count are overwritten.
nowi64requiredThe 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
infoTlsTicketKeyInforequiredThe current key's record.
nowi64requiredThe time to judge at, in monotonicNanos().
returnsbooleanTrue 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[]>requiredThe ticket key, lent: it is read only inside exposeWith, and stays the caller's to wipe.
infoTlsTicketKeyInforequiredThe key's record, whose id the ticket must name.
ticketu8[]requiredThe ticket as the client sent it: key id, nonce, ciphertext and tag.
nowi64requiredThe time to judge the key and the ticket at, in monotonicNanos().
outTlsTicketStaterequiredThe 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[]>requiredThe ticket key, lent: it is read only inside exposeWith, and stays the caller's to wipe.
infoTlsTicketKeyInforequiredThe 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.
nowi64requiredThe issue time, in monotonicNanos().
outu8[]requiredWhere the ticket is written, from index 0; at least tlsTicketSize(state) bytes.
returnsi32How 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
stateTlsTicketStaterequiredThe state to be sealed, with its suite, server name and PSK lengths set.
returnsi32The 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.
CHACHA20POLY1305_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.

