# TLS 1.3 Standalone Library

```c
#define FIO_TLS13
#include "fio-stl.h"
```

Standalone TLS 1.3 crypto library — for IO-layer TLS see [`405 tls13.md`](https://facil.io/0.8.x/native-tls-1-3-io-backend/).

This header implements TLS 1.3 building blocks and standalone client/server state machines: key schedule, record protection, handshake message helpers, alerts, KeyUpdate, certificate-request helpers, and client/server encrypt/decrypt flows.

It is not the facil.io IO integration layer. If you want TLS plugged into the evented IO stack, use the `405` layer. If you want the raw TLS 1.3 machinery, this is the sharp box.

**Security note:** this implementation has not been independently audited. Prefer audited platform TLS for production trust decisions when practical.

## Requirements

The key schedule needs HKDF, which needs SHA-2. The full TLS paths also depend on the selected AEAD, key exchange, certificate, and signature modules. `FIO_CRYPTO` is the easy button when you want the whole crypto set.

Common dependencies:

- `FIO_HKDF` / `FIO_SHA2` for key derivation.
- `FIO_AES` for AES-GCM suites.
- `FIO_CHACHA` for ChaCha20-Poly1305.
- `FIO_ED25519` for X25519 and Ed25519.
- `FIO_P256`, `FIO_P384`, `FIO_RSA`, `FIO_X509`, `FIO_PEM` as certificate/key support requires.

## Constants

```c
#define FIO_TLS13_SHA256_HASH_LEN 32
#define FIO_TLS13_SHA384_HASH_LEN 48
#define FIO_TLS13_MAX_HASH_LEN    48
#define FIO_TLS13_AES128_KEY_LEN  16
#define FIO_TLS13_AES256_KEY_LEN  32
#define FIO_TLS13_CHACHA_KEY_LEN  32
#define FIO_TLS13_IV_LEN          12
```

The record layer uses 12-byte IVs and 16-byte AEAD tags. Maximum TLS plaintext is 16 KiB.

## Main Types

The public types include:

- `fio_tls13_content_type_e` — alert, handshake, application data, and legacy change-cipher-spec content types.
- `fio_tls13_handshake_type_e` — ClientHello, ServerHello, Certificate, Finished, KeyUpdate, and related handshake message IDs.
- `fio_tls13_cipher_suite_e` — `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, and `TLS_CHACHA20_POLY1305_SHA256`.
- `fio_tls13_cipher_type_e` — the AEAD implementation selector for record keys.
- `fio_tls13_record_keys_s` — per-direction write key, IV, sequence number, key length, and cipher type.
- Parsed handshake structs such as `fio_tls13_server_hello_s`, `fio_tls13_encrypted_extensions_s`, `fio_tls13_certificate_s`, `fio_tls13_certificate_verify_s`, and `fio_tls13_certificate_request_s`.
- `fio_tls13_client_s` and `fio_tls13_server_s` — standalone client/server TLS state.

## Key Schedule

These functions implement RFC 8446 section 7 derivation rules:

| Function | Purpose |
| --- | --- |
| `fio_tls13_hkdf_expand_label` | TLS-specific `HKDF-Expand-Label`. |
| `fio_tls13_derive_secret` | `Derive-Secret(secret, label, transcript_hash)`. |
| `fio_tls13_derive_early_secret` | Derive Early Secret from PSK or empty PSK. |
| `fio_tls13_derive_handshake_secret` | Derive Handshake Secret from Early Secret and ECDHE. |
| `fio_tls13_derive_master_secret` | Derive Master Secret. |
| `fio_tls13_derive_traffic_keys` | Derive write key and IV from a traffic secret. |
| `fio_tls13_derive_finished_key` | Derive the Finished MAC key. |
| `fio_tls13_compute_finished` | Compute Finished verify data. |
| `fio_tls13_update_traffic_secret` | Advance application traffic secret for KeyUpdate. |

`use_sha384 != 0` selects SHA-384; otherwise SHA-256 is used.

## Record Layer

| Function | Purpose |
| --- | --- |
| `fio_tls13_build_nonce` | XOR sequence number into IV to build the AEAD nonce. |
| `fio_tls13_record_keys_init` | Initialize `fio_tls13_record_keys_s`. |
| `fio_tls13_record_keys_clear` | Securely clear record keys. |
| `fio_tls13_record_encrypt` | Encrypt one TLS record and advance sequence number. |
| `fio_tls13_record_decrypt` | Decrypt one TLS record, recover inner content type, and advance sequence number. |

Record encryption appends the inner content type before AEAD protection. Decryption strips padding and reports the recovered `fio_tls13_content_type_e`.

## Handshake Helpers

| Function | Purpose |
| --- | --- |
| `fio_tls13_write_handshake_header` | Write a TLS handshake header. |
| `fio_tls13_build_client_hello` | Build a ClientHello with X25519 key share, SNI, and cipher suites. |
| `fio_tls13_parse_server_hello` | Parse ServerHello. |
| `fio_tls13_parse_encrypted_extensions` | Parse EncryptedExtensions. |
| `fio_tls13_parse_certificate` | Parse TLS Certificate handshake body. |
| `fio_tls13_parse_certificate_verify` | Parse CertificateVerify. |
| `fio_tls13_build_finished` | Build Finished handshake message from verify data. |
| `fio_tls13_parse_finished` | Verify a Finished message against expected verify data. |
| `fio_tls13_parse_certificate_request` | Parse CertificateRequest. |
| `fio_tls13_build_certificate_request` | Build CertificateRequest. |

## Alerts and KeyUpdate

| Function | Purpose |
| --- | --- |
| `fio_tls13_build_alert` | Build a plaintext alert payload. |
| `fio_tls13_send_alert` | Build and encrypt an alert record. |
| `fio_tls13_send_alert_plaintext` | Build a plaintext alert record. |
| `fio_tls13_build_key_update` | Build a KeyUpdate handshake message. |
| `fio_tls13_parse_key_update` | Parse KeyUpdate and extract request flag. |
| `fio_tls13_process_key_update` | Process peer KeyUpdate and rotate read/write state as needed. |
| `fio_tls13_send_key_update_response` | Send the required response update when requested. |

## Standalone Client API

| Function | Purpose |
| --- | --- |
| `fio_tls13_client_init` | Initialize client state for a server name. |
| `fio_tls13_client_destroy` | Clear client state. |
| `fio_tls13_client_set_trust_store` | Attach an X.509 trust store pointer. |
| `fio_tls13_client_skip_verification` | Enable/disable certificate verification skipping. Handle with tongs. |
| `fio_tls13_client_get_cert_error` | Return the last certificate validation error. |
| `fio_tls13_client_is_cert_verified` | Report certificate and chain verification status. |
| `fio_tls13_client_start` | Build the initial ClientHello. |
| `fio_tls13_client_process` | Process incoming handshake/record bytes and optionally emit output. |
| `fio_tls13_client_encrypt` | Encrypt application data. |
| `fio_tls13_client_decrypt` | Decrypt application data. |
| `fio_tls13_client_is_connected` | Test for connected state. |
| `fio_tls13_client_is_error` | Test for error state. |
| `fio_tls13_client_alpn_set` | Configure ALPN protocols. |
| `fio_tls13_client_set_cert` | Configure client certificate/private key. |
| `fio_tls13_client_set_public_key` | Configure client public key. |
| `fio_tls13_client_cert_requested` | Report whether the server requested a client certificate. |

## Standalone Server API

| Function | Purpose |
| --- | --- |
| `fio_tls13_server_init` | Initialize server state. |
| `fio_tls13_server_destroy` | Clear server state. |
| `fio_tls13_server_set_cert_chain` | Configure the server certificate chain. |
| `fio_tls13_server_set_private_key` | Configure the private key. |
| `fio_tls13_server_process` | Process incoming handshake/record bytes and optionally emit output. |
| `fio_tls13_server_encrypt` | Encrypt application data. |
| `fio_tls13_server_decrypt` | Decrypt application data. |
| `fio_tls13_server_is_connected` | Test for connected state. |
| `fio_tls13_server_is_error` | Test for error state. |
| `fio_tls13_server_alpn_set` | Configure ALPN protocols. |
| `fio_tls13_server_require_client_cert` | Configure client-certificate request/require mode. |
| `fio_tls13_server_client_cert_received` | Report whether a client certificate arrived. |
| `fio_tls13_server_client_cert_verified` | Report whether the client certificate verified. |

## Example Shape

```c
#define FIO_TLS13
#define FIO_CRYPTO
#include "fio-stl.h"

void client_start(uint8_t *out, size_t cap) {
  fio_tls13_client_s client;
  fio_tls13_client_init(&client, "example.com");

  int len = fio_tls13_client_start(&client, out, cap);
  if (len < 0) {
    /* handle error */
  }

  fio_tls13_client_destroy(&client);
}
```

## Practical Notes

- `190 tls13.md` documents the standalone TLS 1.3 implementation.
- [`405 tls13.md`](https://facil.io/0.8.x/native-tls-1-3-io-backend/) is the IO-layer integration point.
- Skipping certificate verification is for tests and controlled environments, not normal trust.
- Keep traffic secrets and record keys out of logs. They are not collectibles.

------------------------------------------------------------