devnw/zig/tlsQUIC용 TLS 1.3의 Zig 구현으로, 외부 의존성 없이 RFC 8446/9001을 준수하며 AEAD 보호, X.509 검증, 1000개 이상의 테스트를 갖추고 있습니다.
Zig로 작성된 QUIC용 TLS 1.3 구현체로, RFC 8446(TLS 1.3) 및 RFC 9001(QUIC-TLS)을 엄격히 준수합니다.
| 항목 | 정보 |
|---|---|
| API 안정성 | 프로덕션 |
| Zig 버전 | 0.16.0 |
| 플랫폼 | Linux, macOS, Windows |
2ms 미만의 핸드셰이크 목표는 Ed25519 및 RSA-2048 인증서 구성에서 검증되었습니다. secp256r1(P-256) 워크로드는 현재 핸드셰이크당 2~3ms로 실행되며, 이는 업스트림 Zig stdlib 제한(PERF-229) 때문입니다. 전체 결정 기록은 ADR-0002를 참조하세요.
✅ RFC 준수 - TLS 1.3(RFC 8446) 및 QUIC-TLS(RFC 9001) 구현 ✅ 제로 종속성 - Zig 표준 라이브러리만 사용 ✅ 상호 운용성 테스트 완료 - BoringSSL 및 OpenSSL에 대한 적합성 테스트 ✅ QUIC 네이티브 - QUIC 통합용으로 설계, 기존 레코드 계층 없음 ✅ 충분히 테스트됨 - 551개 단위 테스트 + RFC 테스트 벡터 + 449개 적합성 테스트
# 모든 항목 빌드 및 테스트
make
# 또는 수동으로
zig build
zig build test
이 프로젝트는 유연성을 위해 Makefile과 build.zig를 모두 사용합니다:
# 모든 테스트 빌드 및 실행 (기본값)
make
# 빌드만
make build
# 특정 테스트 스위트 실행
make test-unit # 단위 테스트
make test-vectors # RFC 8446/9001 테스트 벡터
make test-conformance # BoringSSL/OpenSSL 적합성 테스트 (libssl-dev 필요)
# 개발 워크플로우
make dev # 포맷 + 검사 + 단위 테스트
make clean # 빌드 아티팩트 정리
make help # 사용 가능한 모든 타겟 표시
# 라이브러리 빌드
zig build
# 모든 테스트 실행
zig build test
# 특정 테스트 스위트 실행
zig build test-vectors
zig build test-conformance # OpenSSL 개발 라이브러리 필요
# 최적화 포함
zig build -Doptimize=ReleaseFast
Build Summary: All steps succeeded; 1000 tests passed ✅
포괄적인 테스트 커버리지:
총: 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();
// QUIC에서 들어오는 CRYPTO 프레임 처리
try ctx.processCrypto(crypto_data);
}
std.crypto.kdf.hkdf를 사용한 HKDF 기반 키 유도이 프로젝트에는 업계 표준 TLS 구현과의 호환성을 보장하기 위한 포괄적인 적합성 테스트가 포함되어 있습니다:
적합성 테스트 실행:
# 먼저 OpenSSL 개발 라이브러리 설치
make install-deps # OS 자동 감지
# 적합성 테스트 실행
make test-conformance
ztls는 옵트인 OpenTelemetry 시임을 제공합니다. -Dwith_otel=true 빌드 플래그가 설정되면 라이브러리는 TLS 핸드셰이크당 정확히 하나의 스팬(스팬 이름: "TLS handshake")을 내보내며, 완료 시 다음 의미론적 규칙 속성이 첨부됩니다:
tls.role -- "client" 또는 "server"tls.protocol.version -- "1.3" (ztls의 경우 항상)tls.cipher_suite -- 협상된 암호 (예: TLS_AES_128_GCM_SHA256)network.protocol.name -- "tls"# 기본 빌드: otel 심볼 없음, 오버헤드 제로.
zig build test
# 활성화 빌드: 핸드셰이크당 하나의 스팬, OTLP 기본값(http://localhost:4318) 또는
# OTEL_* 환경 변수로 지정된 주소를 통해 내보내짐.
zig build test -Dwith_otel=true
시임은 지연 종속성 뒤에 게이트되어 있으므로 otel 패키지는 플래그가 켜져 있을 때만 가져옵니다. TracerProvider를 설치하려는 애플리케이션 진입점 코드는 ztls.observability_init.Otel.init을 호출한 다음 installGlobals()를 호출해야 합니다. 전체 호스트 애플리케이션 부트스트랩에 대해서는 업스트림 otel 통합 레시피(otel/docs/integration/RECIPE.md)를 참조하세요.
# 빠른 개발 반복
make dev
# 코드 포맷
make fmt
# 또는
zig fmt src/ tests/
# 구문 검사
make check
# 클린 빌드
make clean build
기능 추가 시:
Apache-2.0 라이선스 - 자세한 내용은 LICENSE를 참조하세요.
Zig 0.16.0으로 빌드 | TLS 1.3 | QUIC 네이티브 | RFC 준수