ztls

A TLS 1.3 implementation for QUIC written in Zig, strictly adhering to RFC 8446 (TLS 1.3) and RFC 9001 (QUIC-TLS).

Status

Performance note

The <2 ms handshake target is validated on Ed25519 and RSA-2048 certificate configurations. secp256r1 (P-256) workloads currently run 2–3 ms per handshake due to an upstream Zig stdlib limitation (PERF-229). See ADR-0002 for the full decision record.

Features

✅ RFC Compliant - Implements TLS 1.3 (RFC 8446) and QUIC-TLS (RFC 9001) ✅ Zero Dependencies - Uses only Zig standard library ✅ Interop Tested - Conformance tests against BoringSSL and OpenSSL ✅ QUIC Native - Designed for QUIC integration, no traditional record layer ✅ Well Tested - 551 unit tests + RFC test vectors + 449 conformance tests

Quick Start

# Build and test everything
make

# Or manually
zig build
zig build test

Requirements

• Zig 0.16.0 or compatible
• OpenSSL development libraries (optional, for conformance tests)

Building

The project uses both a Makefile and build.zig for flexibility:

Using Make (Recommended)

# Build and run all tests (default)
make

# Build only
make build

# Run specific test suites
make test-unit           # Unit tests
make test-vectors        # RFC 8446/9001 test vectors
make test-conformance    # BoringSSL/OpenSSL conformance (requires libssl-dev)

# Development workflow
make dev                 # Format + check + unit tests
make clean               # Clean build artifacts
make help                # Show all available targets

Using zig build

# Build the library
zig build

# Run all tests
zig build test

# Run specific test suites
zig build test-vectors
zig build test-conformance  # Requires OpenSSL dev libraries

# With optimizations
zig build -Doptimize=ReleaseFast

Test Results

Build Summary: All steps succeeded; 1000 tests passed ✅

Comprehensive Test Coverage:

• 551 unit tests - Per-module tests with RFC subsection references (553 total, 2 skipped)
• 449 conformance tests - BoringSSL and OpenSSL parity testing
  • Cryptographic operations (HKDF, AEAD, signatures)
  • X.509 certificate validation and chain building
  • Advanced X.509 extensions (OCSP, CRL, AIA, name constraints, policies)
  • TLS 1.3 protocol compliance (extensions, handshake flows)
  • Performance benchmarks (latency <2ms, memory <100KB)
  • Security testing (fuzzing, input validation)
  • Post-quantum algorithm readiness (parsing-only)

Total: 1000 tests ensuring RFC compliance, cryptographic parity, and production readiness

Project Structure

src/
├── lib.zig               # Main library entry point
├── tls13/                # TLS 1.3 handshake state machine (modularized)
├── tls13_full.zig        # Full TLS 1.3 message parsing
├── key_schedule.zig      # HKDF-based key derivation
├── record.zig            # Record layer & AEAD operations
├── x509.zig              # Certificate parsing & validation
├── sig.zig               # Signature verification
├── asn1.zig              # ASN.1 DER decoder
├── alert.zig             # TLS alert protocol
├── entropy.zig           # Fail-closed RNG helper (SEC-074)
├── zero_rtt.zig          # 0-RTT support
└── quic_*.zig            # QUIC integration interfaces

tests/
├── rfc8446_vectors.zig        # RFC test vectors
├── boringssl_conformance.zig  # BoringSSL parity tests
└── openssl_conformance.zig    # OpenSSL conformance tests

Usage Example

const std = @import("std");
const tls = @import("ztls");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    // Configure TLS context
    const config = tls.Config{
        .allocator = gpa.allocator(),
        .role = .client,
        .supported_cipher_suites = &.{.TLS_AES_128_GCM_SHA256},
        .supported_groups = &.{.x25519},
        .alpn_protocols = &.{"h3"},
    };

    // Set up callbacks
    const callbacks = tls.Callbacks{
        .on_secret_available = mySecretCallback,
        .on_handshake_complete = myHandshakeCallback,
    };

    // Initialize TLS context
    var ctx = try tls.Context.init(config, callbacks);
    defer ctx.deinit();

    // Process incoming CRYPTO frames from QUIC
    try ctx.processCrypto(crypto_data);
}

Architecture

Design Principles

1. INTEROP FIRST - Auto-detects and supports standard TLS 1.3 formats for compatibility with real-world QUIC implementations (quic-go, quinn, msquic)
2. RFC-Driven Development - Every implementation block cites the relevant RFC section
3. Zero External Dependencies - Uses only Zig stdlib primitives

Key Components

• Key Schedule - HKDF-based key derivation using std.crypto.kdf.hkdf
• AEAD Protection - AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305
• Certificate Validation - X.509 parsing with SNI matching and validity checks
• Signature Verification - ECDSA (P-256, P-384), RSA-PSS, Ed25519

Conformance Testing

The project includes comprehensive conformance tests to ensure compatibility with industry-standard TLS implementations:

BoringSSL Conformance

• HKDF-Extract and HKDF-Expand parity
• QUIC initial secret derivation (RFC 9001)
• AEAD cipher compatibility
• Alert code mapping

OpenSSL 3.x Conformance

• EVP API compatibility
• Cipher suite availability
• Hash function parity
• Key update procedures

To run conformance tests:

# Install OpenSSL development libraries first
make install-deps  # Auto-detects your OS

# Run conformance tests
make test-conformance

Observability

ztls ships with an opt-in OpenTelemetry seam. When the -Dwith_otel=true build flag is set, the library emits exactly one span per TLS handshake (span name: "TLS handshake") with the following semantic-convention attributes attached on completion:

• tls.role -- "client" or "server"
• tls.protocol.version -- "1.3" (always for ztls)
• tls.cipher_suite -- the negotiated cipher (e.g. TLS_AES_128_GCM_SHA256)
• network.protocol.name -- "tls"

# Default build: no otel symbols, zero overhead.
zig build test

# Enabled build: one span per handshake, exported via the OTLP
# defaults (http://localhost:4318) or whatever OTEL_* env vars
# specify.
zig build test -Dwith_otel=true

The seam is gated behind a lazy dependency, so the otel package is only fetched when the flag is on. Application entry-point code that wants to install a TracerProvider should call ztls.observability_init.Otel.init then installGlobals(); consult the upstream otel integration recipe (otel/docs/integration/RECIPE.md) for the full host-application bootstrap.

Documentation

• BUILD_SYSTEM.md - Detailed build system documentation
• CONFORMANCE_TESTS.md - BoringSSL/OpenSSL compatibility test documentation
• CLAUDE.md - Project overview and AI assistance context
• RFC References - All code includes RFC section citations

Development

# Quick development iteration
make dev

# Format code
make fmt
# or
zig fmt src/ tests/

# Check syntax
make check

# Clean build
make clean build

Implementation Status

✅ Completed

• TLS 1.3 handshake state machine
• HKDF key schedule (RFC 8446 §7, RFC 9001 §5.1)
• AEAD record protection (AES-GCM, ChaCha20-Poly1305)
• X.509 certificate parsing and validation
• Signature verification (ECDSA, RSA-PSS, Ed25519)
• Alert protocol
• 0-RTT anti-replay
• QUIC integration interfaces

🚧 Future Work

• HKDF-Expand-Label wrapper (tracked in test vectors)
• OCSP stapling and SCT support
• Full certificate chain validation
• Additional cipher suites (AES-256-GCM-SHA384, AES-CCM)
• Post-handshake authentication
• Migration to stdlib X.509 when stable

Contributing

When adding features:

1. Include unit tests in source files
2. Add RFC section citations to all protocol logic
3. Update integration tests if RFC compliance is affected
4. Add conformance tests for cryptographic operations
5. Update documentation

License

Apache-2.0 License - see LICENSE for details.

References

• RFC 8446 - TLS 1.3
• RFC 9001 - QUIC Transport TLS
• RFC 9369 - QUIC Version 2
• RFC 5280 - X.509 Certificates
• RFC 7301 - ALPN

Built with Zig 0.16.0 | TLS 1.3 | QUIC-Native | RFC-Compliant