# 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.

