ztls

Реализация TLS 1.3 для QUIC на языке Zig, строго соответствующая RFC 8446 (TLS 1.3) и RFC 9001 (QUIC-TLS).

Статус

Аспект	Информация
Стабильность API	Production
Версия Zig	0.16.0
Платформы	Linux, macOS, Windows

Замечание по производительности

Цель рукопожатия <2 мс подтверждена для конфигураций сертификатов Ed25519 и RSA-2048. Нагрузки secp256r1 (P-256) в настоящее время выполняются за 2–3 мс на рукопожатие из-за ограничения вышестоящей stdlib Zig (PERF-229). Полная документация по решению в ADR-0002.

Возможности

✅ Соответствие RFC - Реализует TLS 1.3 (RFC 8446) и QUIC-TLS (RFC 9001) ✅ Ноль зависимостей - Использует только стандартную библиотеку Zig ✅ Проверено на совместимость - Тесты на соответствие с BoringSSL и OpenSSL ✅ Родной для QUIC - Разработан для интеграции с QUIC, без традиционного рекордного уровня ✅ Хорошо протестировано - 551 модульный тест + тестовые векторы RFC + 449 тестов на соответствие

Быстрый старт

# Build and test everything
make

# Or manually
zig build
zig build test

Требования

Zig 0.16.0 или совместимая
Библиотеки разработки OpenSSL (опционально, для тестов на соответствие)

Сборка

Проект использует как Makefile, так и build.zig для гибкости:

Использование Make (рекомендуется)

# Build and run all tests (default)
make

# Build only
make build

# Run specific test suites
make test-unit           # Модульные тесты
make test-vectors        # Тестовые векторы RFC 8446/9001
make test-conformance    # Тесты на соответствие BoringSSL/OpenSSL (требуется libssl-dev)

# Workflow разработки
make dev                 # Форматирование + проверка + модульные тесты
make clean               # Очистка артефактов сборки
make help                # Показать все доступные цели

Использование zig build

# Сборка библиотеки
zig build

# Запуск всех тестов
zig build test

# Запуск определённых наборов тестов
zig build test-vectors
zig build test-conformance  # Требуется dev-библиотеки OpenSSL

# С оптимизациями
zig build -Doptimize=ReleaseFast

Результаты тестирования

Build Summary: All steps succeeded; 1000 tests passed ✅

Всеобъемлющее тестовое покрытие:

551 модульный тест - Помодульные тесты с привязкой к разделам RFC (всего 553, 2 пропущено)
449 тестов на соответствие - Проверка на паритет с BoringSSL и OpenSSL
- Криптографические операции (HKDF, AEAD, подписи)
- Проверка X.509-сертификатов и построение цепочек
- Расширенные X.509-расширения (OCSP, CRL, AIA, ограничения имён, политики)
- Соответствие протоколу TLS 1.3 (расширения, потоки рукопожатия)
- Бенчмарки производительности (задержка <2ms, память <100KB)
- Тестирование безопасности (фаззинг, проверка входных данных)
- Готовность к постквантовым алгоритмам (только парсинг)

Всего: 1000 тестов, обеспечивающих соответствие RFC, криптографический паритет и готовность к промышленной эксплуатации

Структура проекта

src/
├── lib.zig               # Главная точка входа библиотеки
├── tls13/                # Конечный автомат рукопожатия TLS 1.3 (модульный)
├── tls13_full.zig        # Полный парсинг сообщений TLS 1.3
├── key_schedule.zig      # Вывод ключей на основе HKDF
├── record.zig            # Рекордный уровень и операции AEAD
├── x509.zig              # Парсинг и проверка сертификатов
├── sig.zig               # Проверка подписей
├── asn1.zig              # Декодер ASN.1 DER
├── alert.zig             # Протокол тревог TLS
├── entropy.zig           # Хелпер RNG с защитой от сбоев (SEC-074)
├── zero_rtt.zig          # Поддержка 0-RTT
└── quic_*.zig            # Интерфейсы интеграции с QUIC

tests/
├── rfc8446_vectors.zig        # Тестовые векторы RFC
├── boringssl_conformance.zig  # Тесты на паритет с BoringSSL
└── openssl_conformance.zig    # Тесты на соответствие OpenSSL

Пример использования

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

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

    // Настройка контекста TLS
    const config = tls.Config{
        .allocator = gpa.allocator(),
        .role = .client,
        .supported_cipher_suites = &.{.TLS_AES_128_GCM_SHA256},
        .supported_groups = &.{.x25519},
        .alpn_protocols = &.{"h3"},
    };

    // Настройка обратных вызовов
    const callbacks = tls.Callbacks{
        .on_secret_available = mySecretCallback,
        .on_handshake_complete = myHandshakeCallback,
    };

    // Инициализация контекста TLS
    var ctx = try tls.Context.init(config, callbacks);
    defer ctx.deinit();

    // Обработка входящих CRYPTO-фреймов от QUIC
    try ctx.processCrypto(crypto_data);
}

Архитектура

Принципы проектирования

СОВМЕСТИМОСТЬ В ПЕРВУЮ ОЧЕРЕДЬ - Автоматически обнаруживает и поддерживает стандартные форматы TLS 1.3 для совместимости с реальными реализациями QUIC (quic-go, quinn, msquic)
Разработка на основе RFC - Каждый блок реализации содержит ссылку на соответствующий раздел RFC
Ноль внешних зависимостей - Использует только примитивы стандартной библиотеки Zig

Ключевые компоненты

Ключевое расписание - Вывод ключей на основе HKDF с использованием std.crypto.kdf.hkdf
Защита AEAD - AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305
Проверка сертификатов - Парсинг X.509 с сопоставлением SNI и проверками действительности
Проверка подписей - ECDSA (P-256, P-384), RSA-PSS, Ed25519

Тестирование на соответствие

Проект включает всеобъемлющие тесты на соответствие для обеспечения совместимости с промышленными реализациями TLS:

Соответствие BoringSSL

Паритет HKDF-Extract и HKDF-Expand
Вывод начального секрета QUIC (RFC 9001)
Совместимость шифров AEAD
Сопоставление кодов тревог

Соответствие OpenSSL 3.x

Совместимость с API EVP
Доступность наборов шифров
Паритет хеш-функций
Процедуры обновления ключей

Для запуска тестов на соответствие:

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

# Run conformance tests
make test-conformance

Наблюдаемость

ztls поставляется с опциональной интеграцией OpenTelemetry. При установке флага сборки -Dwith_otel=true библиотека генерирует ровно один span на каждое TLS-рукопожатие (имя span: "TLS handshake") со следующими атрибутами семантических соглашений, прикреплёнными по завершении:

tls.role -- "client" или "server"
tls.protocol.version -- "1.3" (всегда для ztls)
tls.cipher_suite -- согласованный шифр (например, 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

Интеграция защищена ленивой зависимостью, поэтому пакет otel загружается только при включённом флаге. Код точки входа приложения, который хочет установить TracerProvider, должен вызвать ztls.observability_init.Otel.init, а затем installGlobals(); полную инструкцию по начальной загрузке приложения-хоста см. в upstream-рецепте интеграции otel (otel/docs/integration/RECIPE.md).

Документация

BUILD_SYSTEM.md - Подробная документация по системе сборки
CONFORMANCE_TESTS.md - Документация тестов на совместимость с BoringSSL/OpenSSL
CLAUDE.md - Обзор проекта и контекст для AI-ассистента
Ссылки на RFC - Весь код содержит цитаты разделов RFC

Разработка

# Quick development iteration
make dev

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

# Check syntax
make check

# Clean build
make clean build

Статус реализации

✅ Завершено

ztls

Реализация TLS 1.3 для QUIC на языке Zig, строго соответствующая RFC 8446 (TLS 1.3) и RFC 9001 (QUIC-TLS).

Статус

Аспект	Информация
Стабильность API	Production
Версия Zig	0.16.0
Платформы	Linux, macOS, Windows

Замечание по производительности

Возможности

Быстрый старт

# Build and test everything
make

# Or manually
zig build
zig build test

Требования

Zig 0.16.0 или совместимая
Библиотеки разработки OpenSSL (опционально, для тестов на соответствие)

Сборка

Проект использует как Makefile, так и build.zig для гибкости:

Использование Make (рекомендуется)

# Build and run all tests (default)
make

# Build only
make build

# Run specific test suites
make test-unit           # Модульные тесты
make test-vectors        # Тестовые векторы RFC 8446/9001
make test-conformance    # Тесты на соответствие BoringSSL/OpenSSL (требуется libssl-dev)

# Workflow разработки
make dev                 # Форматирование + проверка + модульные тесты
make clean               # Очистка артефактов сборки
make help                # Показать все доступные цели

Использование zig build

# Сборка библиотеки
zig build

# Запуск всех тестов
zig build test

# Запуск определённых наборов тестов
zig build test-vectors
zig build test-conformance  # Требуется dev-библиотеки OpenSSL

# С оптимизациями
zig build -Doptimize=ReleaseFast

Результаты тестирования

Build Summary: All steps succeeded; 1000 tests passed ✅

Всеобъемлющее тестовое покрытие:

551 модульный тест - Помодульные тесты с привязкой к разделам RFC (всего 553, 2 пропущено)
449 тестов на соответствие - Проверка на паритет с BoringSSL и OpenSSL
- Криптографические операции (HKDF, AEAD, подписи)
- Проверка X.509-сертификатов и построение цепочек
- Расширенные X.509-расширения (OCSP, CRL, AIA, ограничения имён, политики)
- Соответствие протоколу TLS 1.3 (расширения, потоки рукопожатия)
- Бенчмарки производительности (задержка <2ms, память <100KB)
- Тестирование безопасности (фаззинг, проверка входных данных)
- Готовность к постквантовым алгоритмам (только парсинг)

Структура проекта

src/
├── lib.zig               # Главная точка входа библиотеки
├── tls13/                # Конечный автомат рукопожатия TLS 1.3 (модульный)
├── tls13_full.zig        # Полный парсинг сообщений TLS 1.3
├── key_schedule.zig      # Вывод ключей на основе HKDF
├── record.zig            # Рекордный уровень и операции AEAD
├── x509.zig              # Парсинг и проверка сертификатов
├── sig.zig               # Проверка подписей
├── asn1.zig              # Декодер ASN.1 DER
├── alert.zig             # Протокол тревог TLS
├── entropy.zig           # Хелпер RNG с защитой от сбоев (SEC-074)
├── zero_rtt.zig          # Поддержка 0-RTT
└── quic_*.zig            # Интерфейсы интеграции с QUIC

tests/
├── rfc8446_vectors.zig        # Тестовые векторы RFC
├── boringssl_conformance.zig  # Тесты на паритет с BoringSSL
└── openssl_conformance.zig    # Тесты на соответствие OpenSSL

Пример использования

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

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

    // Настройка контекста TLS
    const config = tls.Config{
        .allocator = gpa.allocator(),
        .role = .client,
        .supported_cipher_suites = &.{.TLS_AES_128_GCM_SHA256},
        .supported_groups = &.{.x25519},
        .alpn_protocols = &.{"h3"},
    };

    // Настройка обратных вызовов
    const callbacks = tls.Callbacks{
        .on_secret_available = mySecretCallback,
        .on_handshake_complete = myHandshakeCallback,
    };

    // Инициализация контекста TLS
    var ctx = try tls.Context.init(config, callbacks);
    defer ctx.deinit();

    // Обработка входящих CRYPTO-фреймов от QUIC
    try ctx.processCrypto(crypto_data);
}

Архитектура

Принципы проектирования

СОВМЕСТИМОСТЬ В ПЕРВУЮ ОЧЕРЕДЬ - Автоматически обнаруживает и поддерживает стандартные форматы TLS 1.3 для совместимости с реальными реализациями QUIC (quic-go, quinn, msquic)
Разработка на основе RFC - Каждый блок реализации содержит ссылку на соответствующий раздел RFC
Ноль внешних зависимостей - Использует только примитивы стандартной библиотеки Zig

Ключевые компоненты

Ключевое расписание - Вывод ключей на основе HKDF с использованием std.crypto.kdf.hkdf
Защита AEAD - AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305
Проверка сертификатов - Парсинг X.509 с сопоставлением SNI и проверками действительности
Проверка подписей - ECDSA (P-256, P-384), RSA-PSS, Ed25519

Тестирование на соответствие

Соответствие BoringSSL

Паритет HKDF-Extract и HKDF-Expand
Вывод начального секрета QUIC (RFC 9001)
Совместимость шифров AEAD
Сопоставление кодов тревог

Соответствие OpenSSL 3.x

Совместимость с API EVP
Доступность наборов шифров
Паритет хеш-функций
Процедуры обновления ключей

Для запуска тестов на соответствие:

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

# Run conformance tests
make test-conformance

Наблюдаемость

tls.role -- "client" или "server"
tls.protocol.version -- "1.3" (всегда для ztls)
tls.cipher_suite -- согласованный шифр (например, 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

Документация

BUILD_SYSTEM.md - Подробная документация по системе сборки
CONFORMANCE_TESTS.md - Документация тестов на совместимость с BoringSSL/OpenSSL
CLAUDE.md - Обзор проекта и контекст для AI-ассистента
Ссылки на RFC - Весь код содержит цитаты разделов RFC

Разработка

# Quick development iteration
make dev

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

# Check syntax
make check

# Clean build
make clean build

tls

Популярное

ztls

Статус

Замечание по производительности

Возможности

Быстрый старт

Требования

Сборка

Использование Make (рекомендуется)

Использование zig build

Результаты тестирования

Структура проекта

Пример использования

Архитектура

Принципы проектирования

Ключевые компоненты

Тестирование на соответствие

Соответствие BoringSSL

Соответствие OpenSSL 3.x

Наблюдаемость

Документация

Разработка

Статус реализации

✅ Завершено

tls

Популярное

ztls

Статус

Замечание по производительности

Возможности

Быстрый старт

Требования

Сборка

Использование Make (рекомендуется)

Использование zig build

Результаты тестирования

Структура проекта

Пример использования

Архитектура

Принципы проектирования

Ключевые компоненты

Тестирование на соответствие

Соответствие BoringSSL

Соответствие OpenSSL 3.x

Наблюдаемость

Документация

Разработка

Статус реализации

✅ Завершено