facil.io
Cryptography & TLS

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

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