GizStack
View .mdOpen in ChatGPTOpen in Claude

gizlang/tlsengine

The portable TLS engine (gizlang/tlsengine): the handshake, record protection and key schedule of TLS 1.3 and 1.2 as Gizlang values, with no native call. Both the composition (the tls module) and the callbacks of the C runtime (gizlang/sys/tls) make their engines here, so it runs the same on giz and on Node. It imports only gizlang/core, gizlang/crypto and gizlang/text.

gizlang
import * as Tlsengine from "gizlang/tlsengine";

Types

Tls12

gizlang
type Tls12 = { randoms: bytes; peer: bytes; master: bytes; extended: bool; pendingKey: bytes; pendingIv: bytes; }

TLS 1.2: the client's random then the server's, the peer's key share, the master secret and whether it is the extended one, and the peer's write key and IV, in force from its ChangeCipherSpec.

  • randoms: bytes
  • peer: bytes
  • master: bytes
  • extended: bool
  • pendingKey: bytes
  • pendingIv: bytes

Engine

gizlang
type Engine

One TLS connection's state, client or server: its handshake, keys and record layer.

  • output: bytes — Bytes for the peer, in order.
  • plain: bytes — The peer's application data not taken yet.
  • failure: string — Why the engine stopped; "" while it runs or after a clean close_notify.
  • peerParameters: bytes
  • crypto: Vec<bytes> — QUIC: the handshake bytes for the peer at each encryption level (Initial, Handshake, 1-RTT), and the traffic secrets in the order the handshake makes them, the peer's and this side's: the handshake ones, then the application ones. The number of secrets is the level that the engine reads and writes.
  • readSecrets: Vec<bytes>
  • writeSecrets: Vec<bytes>

Identity

gizlang
type Identity = { chain: Vec<bytes>; key: Crypto.PrivateKey; }

A server's certificates (DER, its own first) and key.

  • chain: Vec<bytes>
  • key: gizlang_crypto.PrivateKey

Functions

expandLabel

gizlang
function expandLabel(secret: bytes, label: string, context: bytes, length: i64): bytes

HKDF-Expand-Label (RFC 8446 7.1): LENGTH bytes from SECRET for LABEL and CONTEXT.

Effects: fail, alloc.

handshakeTrafficSecrets

gizlang
function handshakeTrafficSecrets(shared: bytes, hash: bytes): Vec<bytes>

The handshake secret of the shared secret SHARED, then the client's and the server's handshake traffic secrets over the transcript hash HASH.

Effects: fail, alloc.

applicationTrafficSecrets

gizlang
function applicationTrafficSecrets(handshake: bytes, hash: bytes): Vec<bytes>

The client's and the server's application traffic secrets of the handshake secret HANDSHAKE over the transcript hash HASH, which ends with the server's Finished.

Effects: fail, alloc.

nextTrafficSecret

gizlang
function nextTrafficSecret(secret: bytes): bytes

The traffic secret after SECRET (RFC 8446 7.2).

Effects: fail, alloc.

aes128

gizlang
function aes128(suite: u64): bool

Whether the cipher SUITE uses AES-128-GCM.

aes256

gizlang
function aes256(suite: u64): bool

Whether the cipher SUITE uses AES-256-GCM.

ecdsaSuite

gizlang
function ecdsaSuite(suite: u64): bool

Whether the TLS 1.2 SUITE authenticates the server with an EC key, not RSA.

nonceOf

gizlang
function nonceOf(iv: bytes, sequence: u64): bytes

The record nonce: the IV with the sequence number XORed into its last 8 bytes (RFC 8446 5.3, RFC 9001 5.3).

Effects: fail, alloc.

engineOf

gizlang
function engineOf(server: bool, random: bytes, protocols: Vec<string>): Engine

A new engine for a server or a client, with its RANDOM bytes and its ALPN PROTOCOLS.

Effects: fail, alloc.

engineClient

gizlang
function engineClient(host: string, roots: Vec<Crypto.Certificate>, now: i64, random: bytes, protocols: Vec<string>): Engine

A client for HOST (the SNI name and the name the certificate must carry; no check when HOST is an empty string) trusting ROOTS at NOW (milliseconds since the epoch). RANDOM holds 64 fresh random bytes: the hello random and the key share's secret. PROTOCOLS are ALPN names; the ClientHello is in output at once. It sends an X25519 share and answers a HelloRetryRequest for P-256.

Effects: fail, alloc.

quicClient

gizlang
function quicClient(host: string, roots: Vec<Crypto.Certificate>, now: i64, random: bytes, protocols: Vec<string>, parameters: bytes): Engine

A QUIC client (RFC 9001), as engineClient with the transport PARAMETERS: TLS 1.3 only, no session id and no ChangeCipherSpec; the ClientHello is in crypto[0] at once.

Effects: fail, alloc.

engineServer

gizlang
function engineServer(chain: Vec<bytes>, key: Crypto.PrivateKey, random: bytes, protocols: Vec<string>, groups: Vec<i64>): Engine

A server presenting CHAIN (DER, its own certificate first) with KEY, the private key of the first. RANDOM holds 64 fresh random bytes: the hello random and the key share's secret. It chooses the first of PROTOCOLS (ALPN names) the client offers, and the first of GROUPS (X25519, P256) the client sent a share of; a client that sent none of them gets a HelloRetryRequest for the first it supports. A client without TLS 1.3 gets TLS 1.2 with ECDHE.

Effects: fail, alloc.

quicServer

gizlang
function quicServer(chain: Vec<bytes>, key: Crypto.PrivateKey, random: bytes, protocols: Vec<string>, parameters: bytes): Engine

A QUIC server (RFC 9001), as engineServer with the transport PARAMETERS: it takes only a TLS 1.3 ClientHello that carries the client's transport parameters, no session id and an ALPN name of PROTOCOLS.

Effects: fail, alloc.

verifyText

gizlang
function verifyText(code: i64): string

OpenSSL's text of the verify result CODE.

identityOf

gizlang
function identityOf(chain: bytes, key: bytes): Option<Identity>

The identity of the PEM CHAIN and KEY; none unless CHAIN holds only certificates, KEY is a P-256, Ed25519 or RSA key and the first certificate is of it.

Effects: fail, alloc.

canServe

gizlang
function canServe(chain: bytes, key: bytes): bool

Whether the PEM CHAIN and KEY can serve (identityOf): the answer the engine module takes, which keeps Identity private.

Effects: fail, alloc.

served

gizlang
function served(chain: bytes, key: bytes, random: bytes): Option<Engine>

A server of the PEM CHAIN and KEY (identityOf), offering HTTP/2 and HTTP/1.1, X25519 and P-256.

Effects: fail, alloc.

progress

gizlang
function progress(engine: Engine): i64

The state of ENGINE as a number: 0 in the handshake, 1 open, 2 closed, 3 waiting for a name, and a negative code when it failed (-47000 minus the verify code, or -46000 minus the alert).

Effects: fail.

Methods

Engine.send

gizlang
function Engine.send(self: mut Engine, data: bytes): bool

Encrypts DATA for the peer once the handshake is done; false before or after.

Effects: fail, alloc.

Engine.dispose

gizlang
function Engine.dispose(self: mut Engine): void

Sends close_notify; the engine takes no more data.

Effects: fail, alloc.

Engine.open

gizlang
function Engine.open(self: Engine): bool

Whether the handshake is done and the connection open.

Engine.closed

gizlang
function Engine.closed(self: Engine): bool

Whether the engine ended: the peer's close_notify, a failure or close.

Engine.eof

gizlang
function Engine.eof(self: mut Engine): void

The peer's stream ended. Between records it ends like a close (most servers send no close_notify); inside one, the stream was cut and the engine fails.

Effects: fail, alloc.

Engine.protocol

gizlang
function Engine.protocol(self: Engine): string

The ALPN protocol the server chose, or "".

Engine.serverName

gizlang
function Engine.serverName(self: Engine): string

A server's: the name the client asked for (SNI), or "".

Engine.group

gizlang
function Engine.group(self: Engine): i64

The key exchange group of the handshake (X25519 or P256), 0 before the hello.

Engine.suite

gizlang
function Engine.suite(self: Engine): u64

The TLS 1.3 cipher suite of the handshake (0x1301, 0x1303), 0 before the hello.

Engine.alertCode

gizlang
function Engine.alertCode(self: Engine): i64

The TLS alert that ended the engine, sent or received; 0 for none.

Engine.hearCrypto

gizlang
function Engine.hearCrypto(self: mut Engine, level: i64, data: bytes): void

QUIC: the peer's handshake bytes DATA at encryption LEVEL (0 Initial, 1 Handshake, 2 1-RTT), in order. Bytes at a level other than the one the engine reads fail it (RFC 9001 4.1.3).

Effects: fail, read, write, console, io, alloc.

Engine.receive

gizlang
function Engine.receive(self: mut Engine, data: bytes): void

Takes the peer's bytes DATA: whole records are decrypted and handled; a partial one waits for the rest.

Effects: fail, read, write, console, io, alloc.

Engine.judged

gizlang
function Engine.judged(self: mut Engine, verify: i64, checked: bool): void

The system's verdict VERIFY on the server's chain, where the system judges it (macOS): OpenSSL's verify code, or 0. The engine ran unchecked for the system; a refused chain of a CHECKED caller fails it with the alert its own check sends (Engine.checked), so the server learns it at once rather than waiting for a request.

Effects: fail, alloc.

Engine.choose

gizlang
function Engine.choose(self: mut Engine, chain: bytes, key: bytes, staple: bytes): void

A server stopped at its client's name goes on with the PEM CHAIN, the PEM KEY and the OCSP answer STAPLE when they serve (an empty CHAIN: with its own), then with what came after the ClientHello.

Effects: fail, read, write, console, io, alloc.

Constants

X25519

gizlang
const X25519: i64 = 0x1d

The key exchange groups.

P256

gizlang
const P256: i64 = 0x17

The key exchange group secp256r1 (NIST P-256).

CLOSED

gizlang
const CLOSED: i64 = 3

The engine state after either side closed the connection.

AWAIT_NAME

gizlang
const AWAIT_NAME: i64 = 4

The engine state of a naming server after a ClientHello: it waits for the credentials of the name.

TLS12

gizlang
const TLS12: i64 = 0x0303

The protocol version number of TLS 1.2.