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.
import * as Tlsengine from "gizlang/tlsengine";Types
Tls12
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:bytespeer:bytesmaster:bytesextended:boolpendingKey:bytespendingIv:bytes
Engine
type EngineOne 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:bytescrypto: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
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
function expandLabel(secret: bytes, label: string, context: bytes, length: i64): bytesHKDF-Expand-Label (RFC 8446 7.1): LENGTH bytes from SECRET for LABEL and CONTEXT.
Effects: fail, alloc.
handshakeTrafficSecrets
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
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
function nextTrafficSecret(secret: bytes): bytesThe traffic secret after SECRET (RFC 8446 7.2).
Effects: fail, alloc.
aes128
function aes128(suite: u64): boolWhether the cipher SUITE uses AES-128-GCM.
aes256
function aes256(suite: u64): boolWhether the cipher SUITE uses AES-256-GCM.
ecdsaSuite
function ecdsaSuite(suite: u64): boolWhether the TLS 1.2 SUITE authenticates the server with an EC key, not RSA.
nonceOf
function nonceOf(iv: bytes, sequence: u64): bytesThe 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
function engineOf(server: bool, random: bytes, protocols: Vec<string>): EngineA new engine for a server or a client, with its RANDOM bytes and its ALPN PROTOCOLS.
Effects: fail, alloc.
engineClient
function engineClient(host: string, roots: Vec<Crypto.Certificate>, now: i64, random: bytes, protocols: Vec<string>): EngineA 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
function quicClient(host: string, roots: Vec<Crypto.Certificate>, now: i64, random: bytes, protocols: Vec<string>, parameters: bytes): EngineA 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
function engineServer(chain: Vec<bytes>, key: Crypto.PrivateKey, random: bytes, protocols: Vec<string>, groups: Vec<i64>): EngineA 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
function quicServer(chain: Vec<bytes>, key: Crypto.PrivateKey, random: bytes, protocols: Vec<string>, parameters: bytes): EngineA 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
function verifyText(code: i64): stringOpenSSL's text of the verify result CODE.
identityOf
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
function canServe(chain: bytes, key: bytes): boolWhether the PEM CHAIN and KEY can serve (identityOf): the answer the engine module takes, which keeps Identity private.
Effects: fail, alloc.
served
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
function progress(engine: Engine): i64The 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
function Engine.send(self: mut Engine, data: bytes): boolEncrypts DATA for the peer once the handshake is done; false before or after.
Effects: fail, alloc.
Engine.dispose
function Engine.dispose(self: mut Engine): voidSends close_notify; the engine takes no more data.
Effects: fail, alloc.
Engine.open
function Engine.open(self: Engine): boolWhether the handshake is done and the connection open.
Engine.closed
function Engine.closed(self: Engine): boolWhether the engine ended: the peer's close_notify, a failure or close.
Engine.eof
function Engine.eof(self: mut Engine): voidThe 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
function Engine.protocol(self: Engine): stringThe ALPN protocol the server chose, or "".
Engine.serverName
function Engine.serverName(self: Engine): stringA server's: the name the client asked for (SNI), or "".
Engine.group
function Engine.group(self: Engine): i64The key exchange group of the handshake (X25519 or P256), 0 before the hello.
Engine.suite
function Engine.suite(self: Engine): u64The TLS 1.3 cipher suite of the handshake (0x1301, 0x1303), 0 before the hello.
Engine.alertCode
function Engine.alertCode(self: Engine): i64The TLS alert that ended the engine, sent or received; 0 for none.
Engine.hearCrypto
function Engine.hearCrypto(self: mut Engine, level: i64, data: bytes): voidQUIC: 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
function Engine.receive(self: mut Engine, data: bytes): voidTakes 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
function Engine.judged(self: mut Engine, verify: i64, checked: bool): voidThe 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
function Engine.choose(self: mut Engine, chain: bytes, key: bytes, staple: bytes): voidA 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
const X25519: i64 = 0x1dThe key exchange groups.
P256
const P256: i64 = 0x17The key exchange group secp256r1 (NIST P-256).
CLOSED
const CLOSED: i64 = 3The engine state after either side closed the connection.
AWAIT_NAME
const AWAIT_NAME: i64 = 4The engine state of a naming server after a ClientHello: it waits for the credentials of the name.
TLS12
const TLS12: i64 = 0x0303The protocol version number of TLS 1.2.