ztls

Uma implementação TLS 1.3 para QUIC escrita em Zig, aderindo estritamente às RFC 8446 (TLS 1.3) e RFC 9001 (QUIC-TLS).

Estado

Aspecto	Info
Estabilidade da API	Produção
Versão do Zig	0.16.0
Plataformas	Linux, macOS, Windows

Nota sobre desempenho

O alvo de <2 ms por handshake é validado em configurações de certificados Ed25519 e RSA-2048. Cargas de trabalho secp256r1 (P-256) atualmente executam 2–3 ms por handshake devido a uma limitação upstream do stdlib do Zig (PERF-229). Consulte ADR-0002 para o registro de decisão completo.

Funcionalidades

✅ Conforme com RFC - Implementa TLS 1.3 (RFC 8446) e QUIC-TLS (RFC 9001) ✅ Zero Dependências - Utiliza apenas a biblioteca padrão do Zig ✅ Testado em Interoperabilidade - Testes de conformidade contra BoringSSL e OpenSSL ✅ Nativo para QUIC - Projetado para integração com QUIC, sem camada de registro tradicional ✅ Bem Testado - 551 testes unitários + vetores de teste RFC + 449 testes de conformidade

Início Rápido

# Construir e testar tudo
make

# Ou manualmente
zig build
zig build test

Requisitos

• Zig 0.16.0 ou compatível
• Bibliotecas de desenvolvimento do OpenSSL (opcional, para testes de conformidade)

Compilação

O projeto utiliza tanto um Makefile quanto build.zig para flexibilidade:

Usando Make (Recomendado)

# Construir e executar todos os testes (padrão)
make

# Apenas construir
make build

# Executar suítes de teste específicas
make test-unit           # Testes unitários
make test-vectors        # Vetores de teste RFC 8446/9001
make test-conformance    # Conformidade com BoringSSL/OpenSSL (requer libssl-dev)

# Fluxo de desenvolvimento
make dev                 # Formatação + verificação + testes unitários
make clean               # Limpar artefatos de compilação
make help                # Mostrar todos os alvos disponíveis

Usando zig build

# Construir a biblioteca
zig build

# Executar todos os testes
zig build test

# Executar suítes de teste específicas
zig build test-vectors
zig build test-conformance  # Requer bibliotecas de desenvolvimento do OpenSSL

# Com otimizações
zig build -Doptimize=ReleaseFast

Resultados dos Testes

Build Summary: All steps succeeded; 1000 tests passed ✅

Cobertura de Testes Abrangente:

• 551 testes unitários - Testes por módulo com referências a subseções RFC (553 total, 2 ignorados)
• 449 testes de conformidade - Testes de paridade com BoringSSL e OpenSSL
  • Operações criptográficas (HKDF, AEAD, assinaturas)
  • Validação de certificados X.509 e construção de cadeias
  • Extensões X.509 avançadas (OCSP, CRL, AIA, restrições de nome, políticas)
  • Conformidade com o protocolo TLS 1.3 (extensões, fluxos de handshake)
  • Benchmarks de desempenho (latência <2ms, memória <100KB)
  • Testes de segurança (fuzzing, validação de entrada)
  • Prontidão para algoritmos pós-quânticos (apenas análise sintática)

Total: 1000 testes garantindo conformidade com RFC, paridade criptográfica e prontidão para produção

Estrutura do Projeto

src/
├── lib.zig               # Ponto de entrada principal da biblioteca
├── tls13/                # Máquina de estados do handshake TLS 1.3 (modularizada)
├── tls13_full.zig        # Análise sintática completa de mensagens TLS 1.3
├── key_schedule.zig      # Derivação de chaves baseada em HKDF
├── record.zig            # Camada de registro e operações AEAD
├── x509.zig              # Análise sintática e validação de certificados
├── sig.zig               # Verificação de assinaturas
├── asn1.zig              # Decodificador ASN.1 DER
├── alert.zig             # Protocolo de alerta TLS
├── entropy.zig           # Auxiliar RNG com falha segura (SEC-074)
├── zero_rtt.zig          # Suporte a 0-RTT
└── quic_*.zig            # Interfaces de integração com QUIC

tests/
├── rfc8446_vectors.zig        # Vetores de teste RFC
├── boringssl_conformance.zig  # Testes de paridade com BoringSSL
└── openssl_conformance.zig    # Testes de conformidade com OpenSSL

Exemplo de Uso

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

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

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

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

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

    // Processar frames CRYPTO recebidos do QUIC
    try ctx.processCrypto(crypto_data);
}

Arquitetura

Princípios de Design

1. INTEROP PRIMEIRO - Detecta e suporta automaticamente formatos TLS 1.3 padrão para compatibilidade com implementações QUIC reais (quic-go, quinn, msquic)
2. Desenvolvimento Orientado por RFC - Cada bloco de implementação cita a seção RFC relevante
3. Zero Dependências Externas - Utiliza apenas primitivas do stdlib do Zig

Componentes Principais

• Key Schedule - Derivação de chaves baseada em HKDF usando std.crypto.kdf.hkdf
• Proteção AEAD - AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305
• Validação de Certificados - Análise sintática X.509 com correspondência SNI e verificações de validade
• Verificação de Assinaturas - ECDSA (P-256, P-384), RSA-PSS, Ed25519

Testes de Conformidade

O projeto inclui testes de conformidade abrangentes para garantir compatibilidade com implementações TLS padrão da indústria:

Conformidade com BoringSSL

• Paridade HKDF-Extract e HKDF-Expand
• Derivação do segredo inicial QUIC (RFC 9001)
• Compatibilidade de cifras AEAD
• Mapeamento de códigos de alerta

Conformidade com OpenSSL 3.x

• Compatibilidade com API EVP
• Disponibilidade de suítes de cifras
• Paridade de funções hash
• Procedimentos de atualização de chave

Para executar testes de conformidade:

# Instale primeiro as bibliotecas de desenvolvimento do OpenSSL
make install-deps  # Detecta automaticamente seu SO

# Execute testes de conformidade
make test-conformance

Observabilidade

O ztls possui uma interface opcional para OpenTelemetry. Quando a flag de compilação -Dwith_otel=true é definida, a biblioteca emite exatamente um span por handshake TLS (nome do span: "TLS handshake") com os seguintes atributos de convenção semântica anexados na conclusão:

• tls.role -- "client" ou "server"
• tls.protocol.version -- "1.3" (sempre para ztls)
• tls.cipher_suite -- a cifra negociada (ex. TLS_AES_128_GCM_SHA256)
• network.protocol.name -- "tls"

# Compilação padrão: sem símbolos otel, zero overhead.
zig build test

# Compilação habilitada: um span por handshake, exportado via padrões OTLP
# (http://localhost:4318) ou quaisquer variáveis de ambiente OTEL_* que
# especifiquem.
zig build test -Dwith_otel=true

A interface é controlada por uma dependência lazy, então o pacote otel é obtido apenas quando a flag está ativada. O código de entrada da aplicação que deseja instalar um TracerProvider deve chamar ztls.observability_init.Otel.init e em seguida installGlobals(); consulte a receita de integração do otel upstream (otel/docs/integration/RECIPE.md) para o bootstrap completo da aplicação hospedeira.

Documentação