zig-tls
All librariesGitHubDiscord

Third-Party Audit Preparation Checklist

Copy page
Copy page as Markdown for LLMs
View as Markdown
View this page as plain text
Open in ChatGPT
Copy content and open ChatGPT
Open in Claude
Copy content and open Claude
Open in Perplexity
Search with Perplexity AI
On this page 7

Use this checklist before engaging a security auditor or enabling zig-tls as the default TLS stack in Bun.

Scope

  • TLS 1.2 and TLS 1.3 client/server handshake
  • Record layer encryption/decryption (AEAD and CBC)
  • Certificate chain verification
  • Session ticket encryption (RFC 5077 / TLS 1.3 NewSessionTicket)
  • RSA, ECDSA signing and verification
  • Post-quantum hybrid key exchange (ML-KEM-768 + X25519)

Out of scope: node:crypto EVP layer, QUIC, DTLS, legacy SSLv3.

Code Areas for Review

AreaPathNotes
Handshake state machinessrc/handshake_client.zig, src/handshake_server.zigNon-blocking + blocking
Record parsersrc/record.zigFuzz target available
Cipher suitessrc/cipher.zigAEAD + CBC
Key schedulesrc/transcript.zigHKDF labels
RSAsrc/rsa/rsa.zigConstant-time decrypt
Session ticketssrc/session_ticket.zigAES-256-GCM encryption
ALPNsrc/alpn.zigProtocol negotiation
Embedding APIsrc/embed.zigBun adapter surface

Test Evidence to Provide

zig build test
zig build bench -Doptimize=ReleaseFast
./bench/compare.sh            # zig-tls vs BoringSSL (see docs/BENCHMARKS.md)
zig build -Dfuzz=true fuzz   # fuzz binaries in zig-out/bin/

Interop Evidence

zig build tls-server              # listens on 127.0.0.1:8443
zig build tls-server -- 9443      # custom port
./scripts/testssl.sh localhost 8443

Production Features (in scope)

  • OCSP stapling: server Server.ocsp_response; client request_ocsp with full validation when verification is enabled (DER shape, status, CertID, validity window, responder signature, issuer chain, id-kp-OCSPSigning or issuing-CA responder)
  • TLS 1.3 echo server: zig build tls-server for testssl.sh / openssl interop

Known Limitations (document for auditor)

  • TLS 1.2 static RSA key exchange: server decrypt path implemented; legacy export ciphers unsupported by design
  • HelloRetryRequest: implemented for preferred-group mismatch; stateless cookie is connection-scoped (16-byte random)
  • 0-RTT early data: client send and server decrypt with PSK binder verification; disabled by default (Server.max_early_data_size = 0); set > 0 to accept early data on PSK resume
  • FFDHE2048: implemented (RFC 7919); x448 and secp521r1 are rejected if listed in named_groups (awaiting std.crypto support)
  • Record crypto: optional BoringSSL-derived AES-GCM and P-256 Montgomery assembly on AArch64/x86_64 (src/crypto/*/NOTICE)

Bun Integration Surface

The embedding API in src/embed.zig exposes:

  • zigt_ctx_* — secure context (cipher list, ALPN, ticket keys, PQ flag)
  • zigt_conn_* — per-connection non-blocking handshake
  • Error codes mapped to OpenSSL SSL_ERROR_WANT_READ/WRITE

Bun-specific half-open TCP semantics remain in the Bun adapter, not zig-tls core.