ztls

QUIC向けにZigで書かれたTLS 1.3実装で、RFC 8446（TLS 1.3）およびRFC 9001（QUIC-TLS）に厳密に準拠しています。

ステータス

側面	情報
API安定性	本番
Zigバージョン	0.16.0
プラットフォーム	Linux, macOS, Windows

パフォーマンスに関する注意

2ミリ秒未満のハンドシェイク目標は、Ed25519およびRSA-2048証明書構成で検証されています。secp256r1（P-256）のワークロードは現在、上流のZig stdlibの制限（PERF-229）により、ハンドシェイクあたり2～3ミリ秒かかります。詳細な決定記録については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           # 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

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

テスト結果

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

使用例

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);
}

アーキテクチャ

設計原則

相互運用性優先 - 標準のTLS 1.3形式を自動検出してサポートし、実際のQUIC実装（quic-go、quinn、msquic）との互換性を確保
RFC駆動開発 - すべての実装ブロックに関連するRFCセクションを引用
外部依存なし - Zig stdlibのプリミティブのみを使用

主要コンポーネント

鍵スケジュール - std.crypto.kdf.hkdfを使用したHKDFベースの鍵導出
AEAD保護 - AES-128-GCM、AES-256-GCM、ChaCha20-Poly1305
証明書検証 - SNIマッチングと有効性チェックを含むX.509解析
署名検証 - ECDSA（P-256、P-384）、RSA-PSS、Ed25519

適合テスト

このプロジェクトには、業界標準のTLS実装との互換性を確保するための包括的な適合テストが含まれています。

BoringSSL適合テスト

HKDF-ExtractおよびHKDF-Expandのパリティ
QUIC初期秘密導出（RFC 9001）
AEAD暗号互換性
アラートコードマッピング

OpenSSL 3.x適合テスト

EVP API互換性
暗号スイートの可用性
ハッシュ関数パリティ
鍵更新手順

適合テストを実行するには:

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

# Run conformance tests
make test-conformance

可観測性

ztlsにはオプトインのOpenTelemetryシームが付属しています。-Dwith_otel=trueビルドフラグが設定されている場合、ライブラリはTLSハンドシェイクごとに1つのスパン（スパン名: "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()を呼び出す必要があります。完全なホストアプリケーションのブートストラップについては、上流のotel統合レシピ（otel/docs/integration/RECIPE.md）を参照してください。

ドキュメント

BUILD_SYSTEM.md - 詳細なビルドシステムドキュメント
CONFORMANCE_TESTS.md - BoringSSL/OpenSSL互換性テストドキュメント
CLAUDE.md - プロジェクト概要とAI支援コンテキスト
RFC References - すべてのコードに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 1.3ハンドシェイクステートマシン
HKDF鍵スケジュール（RFC 8446 §7、RFC 9001 §5.1）
AEADレコード保護（AES-GCM、ChaCha20-Poly1305）
X.509証明書解析と検証
署名検証（ECDSA、RSA-PSS、Ed25519）
アラートプロトコル
0-RTTリプレイ防止
QUIC統合インターフェース

🚧 今後の作業

HKDF-Expand-Labelラッパー（テストベクターで追跡）
OCSPステープリングとSCTサポート
完全な証明書チェーン検証
追加の暗号スイート（AES-256-GCM-SHA384、AES-CCM）
ハンドシェイク後認証
stdlib X.509が安定したら移行

貢献

機能を追加する際は:

ソースファイルに単体テストを含める
すべてのプロトコルロジックにRFCセクション引用を追加
RFC準拠に影響がある場合は統合テストを更新
暗号操作の適合テストを追加
ドキュメントを更新

ライセンス

Apache-2.0ライセンス - 詳細はLICENSEを参照してください。

参考文献

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

Zig 0.16.0で構築 | TLS 1.3 | QUICネイティブ | RFC準拠

tls

人気