跳转到内容

std.crypto.tls.Client

标准库Zig 0.17.0官方原文
源码std/crypto/tls/Client.zig

第 1 行

字段

input: *Reader

从服务器发送到客户端的加密流。通过 reader 从此处读取字节。

断言缓冲区容量至少为 min_buffer_len。

reader: Reader

从服务器到客户端的已解密流。

output: *Writer

从客户端到服务器的加密流。通过 writer 将字节推入此处。

断言缓冲区容量至少为 min_buffer_len。

writer: Writer

从客户端到服务器的明文流。

alert: ?tls.Alert = null

返回 error.TlsAlert 时填充。

read_err: ?ReadError = null
tls_version: tls.ProtocolVersion
read_seq: u64
write_seq: u64
received_close_notify: bool

此值为 true 时,流仍可能未结束,因为 输入缓冲区中可能还有数据。

allow_truncation_attacks: bool
application_cipher: tls.ApplicationCipher
ssl_key_log: ?*SslKeyLog

非 null 时,将 SSL 密钥记录到流中。创建此日志文件后, 任何能访问该文件的其他程序都可以解密此连接上的全部流量。

std.crypto.tls.Client.array

别名

第 18 行

别名目标 std.crypto.tls.array

std.crypto.tls.Client.assert

别名

第 9 行

别名目标 std.debug.assert

std.crypto.tls.Client.big

函数

第 1346 行

fn big(x: anytype) @TypeOf(x)

std.crypto.tls.Client.builtin

常量

第 1 行

std.crypto.tls.Client.Certificate

别名

第 10 行

别名目标 std.crypto.Certificate

std.crypto.tls.Client.CertificatePublicKey

容器

第 1490 行

字段

algo: Certificate.AlgorithmCategory
buf: [600]u8
len: u16

std.crypto.tls.Client.CertificatePublicKey.init

函数

第 1495 行

fn init( cert_pub_key: *CertificatePublicKey, algo: Certificate.AlgorithmCategory, pub_key: []const u8, ) error{CertificatePublicKeyInvalid}!void

参数

cert_pub_key: *CertificatePublicKey
algo: Certificate.AlgorithmCategory
pub_key: []const u8

错误

CertificatePublicKeyInvalid

std.crypto.tls.Client.CertificatePublicKey.VerifyError

错误集合

第 1506 行

错误

CertificateFieldHasInvalidLength ParseError
CertificateFieldHasWrongDataType ParseDerError
CertificatePublicKeyInvalid FromBytesError
InvalidEncoding
InvalidSignature VerifyError
MessageTooLong EncryptError
NonCanonical NonCanonicalError
NotSquare NotSquareError
TlsBadRsaSignatureBitCount
TlsBadSignatureScheme
TlsDecodeError

std.crypto.tls.Client.CertificatePublicKey.verifySignature

函数

第 1522 行

fn verifySignature( cert_pub_key: *const CertificatePublicKey, sigd: *tls.Decoder, msg: []const []const u8, ) VerifyError!void

参数

cert_pub_key: *const CertificatePublicKey
sigd: *tls.Decoder
msg: []const []const u8

错误

CertificateFieldHasInvalidLength ParseError
CertificateFieldHasWrongDataType ParseDerError
CertificatePublicKeyInvalid FromBytesError
InvalidEncoding
InvalidSignature VerifyError
MessageTooLong EncryptError
NonCanonical NonCanonicalError
NotSquare NotSquareError
TlsBadRsaSignatureBitCount
TlsBadSignatureScheme
TlsDecodeError

std.crypto.tls.Client.cipher_suites

常量

第 1651 行

此处优先级顺序的选择依据是 Zig 标准库提供的 密码算法以及各算法的速度。下方给出 这些算法相对性能的若干测量数据。

使用 0.11.0-dev.810+c2f5848fe 测量, 平台为 x86_64-linux,Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz: zig run .lib/std/crypto/benchmark.zig -OReleaseFast aegis-128l: 15382 MiB/s aegis-256: 9553 MiB/s aes128-gcm: 3721 MiB/s aes256-gcm: 3010 MiB/s chacha20Poly1305: 597 MiB/s

使用 0.11.0-dev.810+c2f5848fe 测量, 平台为 x86_64-linux,Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz: zig run .lib/std/crypto/benchmark.zig -OReleaseFast -mcpu=baseline aegis-128l: 629 MiB/s chacha20Poly1305: 529 MiB/s aegis-256: 461 MiB/s aes128-gcm: 138 MiB/s aes256-gcm: 120 MiB/s

std.crypto.tls.Client.Client

别名

第 6 行

别名目标 std.crypto.tls.Client

std.crypto.tls.Client.crypto

别名

第 8 行

别名目标 std.crypto

std.crypto.tls.Client.drain

函数

第 965 行

fn drain(w: *Writer, data: []const []const u8, splat: usize) Writer.Error!usize

参数

w: *Writer
data: []const []const u8
splat: usize

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.crypto.tls.Client.end

函数

第 1009 行

发送 close_notify 警报,使服务器能够区分 正常完成的 TLS 会话与截断攻击。

pub fn end(c: *Client) Writer.Error!void

参数

c: *Client

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.crypto.tls.Client.eof

函数

第 1120 行

pub fn eof(c: Client) bool

参数

c: Client

std.crypto.tls.Client.failRead

类型函数

第 1332 行

fn failRead(c: *Client, err: ReadError) error{ReadFailed}

参数

c: *Client
err: ReadError

错误

ReadFailed

std.crypto.tls.Client.flush

函数

第 997 行

fn flush(w: *Writer) Writer.Error!void

参数

w: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.crypto.tls.Client.hkdfExpandLabel

别名

第 16 行

别名目标 std.crypto.tls.hkdfExpandLabel

std.crypto.tls.Client.hmacExpandLabel

别名

第 15 行

别名目标 std.crypto.tls.hmacExpandLabel

std.crypto.tls.Client.init

函数

第 195 行

发起 TLS 握手,并建立 TLSv1.2 或 TLSv1.3 会话。

host 仅在此函数调用期间被借用。

断言 input 的缓冲区容量至少为 min_buffer_len。

pub fn init(input: *Reader, output: *Writer, options: Options) InitError!Client

参数

input: *Reader
output: *Writer
options: Options

错误

BufferTooSmall
Canceled Cancelable

调用方请求停止异步操作。

CertificateExpired
CertificateFieldHasInvalidLength
CertificateFieldHasWrongDataType
CertificateHasInvalidBitString
CertificateHasUnrecognizedObjectId
CertificateHostMismatch
CertificateIssuerMismatch
CertificateNotYetValid
CertificatePublicKeyInvalid
CertificateSignatureAlgorithmMismatch
CertificateSignatureAlgorithmUnsupported
CertificateSignatureInvalid
CertificateSignatureInvalidLength
CertificateSignatureNamedCurveUnsupported
CertificateSignatureUnsupportedBitCount
CertificateTimeInvalid
DiskQuota
IdentityElement
InsufficientEntropy
InvalidEncoding
InvalidSignature
LockViolation
MessageTooLong
NegativeIntoUnsigned
NonCanonical
NotOpenForWriting
NotSquare
ReadFailed ShortError

详细诊断参见 Reader 的实现。

SignatureVerificationFailed
TargetTooSmall
TlsAlert

警报说明将存储在 alert 中。

TlsBadRecordMac
TlsBadRsaSignatureBitCount
TlsBadSignatureScheme
TlsCertificateNotVerified
TlsConnectionTruncated
TlsDecodeError
TlsDecryptError
TlsDecryptFailure
TlsIllegalParameter
TlsRecordOverflow
TlsUnexpectedMessage
UnsupportedCertificateVersion
WeakPublicKey
WriteFailed Error

详细诊断信息见 Writer 实现。

std.crypto.tls.Client.InitError

错误集合

第 142 行

错误

BufferTooSmall
Canceled Cancelable

调用方请求停止异步操作。

CertificateExpired
CertificateFieldHasInvalidLength
CertificateFieldHasWrongDataType
CertificateHasInvalidBitString
CertificateHasUnrecognizedObjectId
CertificateHostMismatch
CertificateIssuerMismatch
CertificateNotYetValid
CertificatePublicKeyInvalid
CertificateSignatureAlgorithmMismatch
CertificateSignatureAlgorithmUnsupported
CertificateSignatureInvalid
CertificateSignatureInvalidLength
CertificateSignatureNamedCurveUnsupported
CertificateSignatureUnsupportedBitCount
CertificateTimeInvalid
DiskQuota
IdentityElement
InsufficientEntropy
InvalidEncoding
InvalidSignature
LockViolation
MessageTooLong
NegativeIntoUnsigned
NonCanonical
NotOpenForWriting
NotSquare
ReadFailed ShortError

详细诊断参见 Reader 的实现。

SignatureVerificationFailed
TargetTooSmall
TlsAlert

警报说明将存储在 alert 中。

TlsBadRecordMac
TlsBadRsaSignatureBitCount
TlsBadSignatureScheme
TlsCertificateNotVerified
TlsConnectionTruncated
TlsDecodeError
TlsDecryptError
TlsDecryptFailure
TlsIllegalParameter
TlsRecordOverflow
TlsUnexpectedMessage
UnsupportedCertificateVersion
WeakPublicKey
WriteFailed Error

详细诊断信息见 Writer 实现。

std.crypto.tls.Client.int

别名

第 17 行

别名目标 std.crypto.tls.int

std.crypto.tls.Client.KeyShare

容器

第 1353 行

字段

std.crypto.tls.Client.KeyShare.exchange

函数

第 1379 行

fn exchange( ks: *KeyShare, named_group: tls.NamedGroup, server_pub_key: []const u8, ) error{ TlsIllegalParameter, TlsDecryptFailure }!void

参数

ks: *KeyShare
named_group: tls.NamedGroup
server_pub_key: []const u8

错误

TlsDecryptFailure
TlsIllegalParameter

std.crypto.tls.Client.KeyShare.getSharedSecret

函数

第 1428 行

fn getSharedSecret(ks: *const KeyShare) ?[]const u8

参数

ks: *const KeyShare

std.crypto.tls.Client.KeyShare.init

函数

第 1368 行

fn init(seed: *const [176]u8) error{IdentityElement}!KeyShare

参数

seed: *const [176]u8

错误

IdentityElement

std.crypto.tls.Client.KeyShare.sk_max_len

常量

第 1361 行

std.crypto.tls.Client.logSecrets

函数

第 1337 行

fn logSecrets(w: *Writer, context: anytype, secrets: anytype) void

参数

w: *Writer

std.crypto.tls.Client.max_ciphertext_len

别名

第 14 行

别名目标 std.crypto.tls.max_ciphertext_len

std.crypto.tls.Client.mem

别名

第 7 行

别名目标 std.mem

std.crypto.tls.Client.min_buffer_len

别名

第 85 行

提供给 init 的 Reader 要求缓冲区容量至少为此值。

别名目标 std.crypto.tls.max_ciphertext_record_len

std.crypto.tls.Client.native_endian

常量

第 2 行

std.crypto.tls.Client.Options

容器

第 87 行

字段

host: union(enum) {
    /// 不执行主机验证,因此无法建立
    /// 受信任的连接。
    no_verification,
    /// 验证服务器证书是否为给定主机签发。
    explicit: []const u8,
}

如何对服务器证书执行主机名验证。

ca: union(enum) {
    /// 未进行 CA 验证,
    /// 因此无法建立受信任的连接。
    no_verification,
    /// 验证服务器证书是否为有效的自签名证书。
    /// 这不提供授权保证,因为任何人都可以创建自签名证书。
    ///
    self_signed,
    /// 验证服务器证书是否由给定 CA 包授权。
    bundle: struct {
        gpa: std.mem.Allocator,
        io: std.Io,
        lock: *std.Io.RwLock,
        bundle: *Certificate.Bundle,
    },
}

如何验证服务器证书的真实性。

write_buffer: []u8
read_buffer: []u8
entropy: *const [entropy_len]u8

密码学安全的随机字节。不会捕获指针;仅在 init 期间读取数据。

realtime_now: std.Io.Timestamp

墙上时钟/日历所示的当前时间。

ssl_key_log: ?*SslKeyLog = null

若非 null,则将 SSL 秘密信息记录到此流。有权访问该日志文件的 其他程序可解密此连接上的全部流量。

握手,即 init 期间,仅观察 writer 字段。 之后会填充其他字段。

allow_truncation_attacks: bool = false

默认情况下,从服务器读取时遇到流结束,除非此前已收到 close_notify 消息,否则返回 error.TlsConnectionTruncated。将此标志设为 true 后,会改为将流结束转发给 TLS 之上的应用层。

除非应用层自行验证接收数据量与预期数据量相等,例如使用 Content-Length 报头的 HTTP,否则这会使应用程序容易受到截断攻击。

alert: ?*tls.Alert = null

init 返回 error.TlsAlert 时填充。

std.crypto.tls.Client.Options.entropy_len

常量

第 139 行

std.crypto.tls.Client.prepareCiphertextRecord

类型函数

第 1017 行

fn prepareCiphertextRecord( c: *Client, ciphertext_buf: []u8, bytes: []const u8, inner_content_type: tls.ContentType, ) struct { ciphertext_end: usize, cleartext_len: usize, }

参数

c: *Client
ciphertext_buf: []u8
bytes: []const u8
inner_content_type: tls.ContentType

std.crypto.tls.Client.Reader

别名

第 11 行

别名目标 std.Io.Reader

std.crypto.tls.Client.ReadError

错误集合

第 53 行

错误

TlsAlert

警报说明将存储在 alert 中。

TlsBadLength
TlsBadRecordMac
TlsConnectionTruncated
TlsDecodeError
TlsIllegalParameter
TlsRecordOverflow
TlsSequenceOverflow
TlsUnexpectedMessage

std.crypto.tls.Client.readIndirect

函数

第 1139 行

fn readIndirect(c: *Client) Reader.Error!usize

参数

c: *Client

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.crypto.tls.Client.readVec

函数

第 1132 行

fn readVec(r: *Reader, data: [][]u8) Reader.Error!usize

参数

r: *Reader
data: [][]u8

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.crypto.tls.Client.rebase

函数

第 1323 行

fn rebase(r: *Reader, capacity: usize) void

参数

r: *Reader
capacity: usize

std.crypto.tls.Client.SchemeEcdsa

类型函数

第 1433 行

fn SchemeEcdsa(comptime scheme: tls.SignatureScheme) type

参数

std.crypto.tls.Client.SchemeEddsa

类型函数

第 1459 行

fn SchemeEddsa(comptime scheme: tls.SignatureScheme) type

参数

std.crypto.tls.Client.SchemeHash

类型函数

第 1466 行

fn SchemeHash(comptime scheme: tls.SignatureScheme) type

参数

std.crypto.tls.Client.SchemeRsa

类型函数

第 1441 行

fn SchemeRsa(comptime scheme: tls.SignatureScheme) type

参数

std.crypto.tls.Client.SslKeyLog

容器

第 66 行

字段

client_key_seq: u64
server_key_seq: u64
client_random: [32]u8
writer: *Writer

std.crypto.tls.Client.SslKeyLog.clientCounter

函数

第 72 行

fn clientCounter(key_log: *@This()) u64

参数

key_log: *@This()

std.crypto.tls.Client.SslKeyLog.serverCounter

函数

第 77 行

fn serverCounter(key_log: *@This()) u64

参数

key_log: *@This()

std.crypto.tls.Client.std

别名

第 4 行

别名目标 std

std.crypto.tls.Client.stream

函数

第 1124 行

fn stream(r: *Reader, w: *Writer, limit: std.Io.Limit) Reader.StreamError!usize

参数

r: *Reader
w: *Writer
limit: std.Io.Limit

错误

EndOfStream

Reader 指示流结束。此错误不会从 Writer 产生。

ReadFailed

详细诊断参见 Reader 的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.crypto.tls.Client.testReadError

函数

第 1674 行

fn testReadError(input_buf: []const u8, tls_version: tls.ProtocolVersion, cipher: tls.ApplicationCipher) ReadError

参数

input_buf: []const u8
tls_version: tls.ProtocolVersion
cipher: tls.ApplicationCipher

std.crypto.tls.Client.tls

别名

第 5 行

别名目标 std.crypto.tls

std.crypto.tls.Client.tryDownloadRootCert

函数

第 1606 行

fn tryDownloadRootCert(chain: *Certificate.Chain, options: *const Options) !void

参数

chain: *Certificate.Chain
options: *const Options

std.crypto.tls.Client.Writer

别名

第 12 行

别名目标 std.Io.Writer

源码

std/crypto/tls/Client.zig

const builtin = @import("builtin");
const native_endian = builtin.cpu.arch.endian();

const std = @import("../../std.zig");
const tls = std.crypto.tls;
const Client = @This();
const mem = std.mem;
const crypto = std.crypto;
const assert = std.debug.assert;
const Certificate = std.crypto.Certificate;
const Reader = std.Io.Reader;
const Writer = std.Io.Writer;

const max_ciphertext_len = tls.max_ciphertext_len;
const hmacExpandLabel = tls.hmacExpandLabel;
const hkdfExpandLabel = tls.hkdfExpandLabel;
const int = tls.int;
const array = tls.array;

/// 从服务器发送到客户端的加密流。通过 `reader` 从此处读取字节。
///
/// 断言缓冲区容量至少为 `min_buffer_len`。
///
input: *Reader,
/// 从服务器到客户端的已解密流。
reader: Reader,

/// 从客户端到服务器的加密流。通过 `writer` 将字节推入此处。
///
/// 断言缓冲区容量至少为 `min_buffer_len`。
///
output: *Writer,
/// 从客户端到服务器的明文流。
writer: Writer,

/// 返回 `error.TlsAlert` 时填充。
alert: ?tls.Alert = null,
read_err: ?ReadError = null,
tls_version: tls.ProtocolVersion,
read_seq: u64,
write_seq: u64,
/// 此值为 true 时,流仍可能未结束,因为
/// 输入缓冲区中可能还有数据。
received_close_notify: bool,
allow_truncation_attacks: bool,
application_cipher: tls.ApplicationCipher,

/// 非 null 时,将 SSL 密钥记录到流中。创建此日志文件后,
/// 任何能访问该文件的其他程序都可以解密此连接上的全部流量。
///
ssl_key_log: ?*SslKeyLog,

pub const ReadError = error{
    /// 警报说明将存储在 `alert` 中。
    TlsAlert,
    TlsBadLength,
    TlsBadRecordMac,
    TlsConnectionTruncated,
    TlsDecodeError,
    TlsRecordOverflow,
    TlsUnexpectedMessage,
    TlsIllegalParameter,
    TlsSequenceOverflow,
};

pub const SslKeyLog = struct {
    client_key_seq: u64,
    server_key_seq: u64,
    client_random: [32]u8,
    writer: *Writer,

    fn clientCounter(key_log: *@This()) u64 {
        defer key_log.client_key_seq += 1;
        return key_log.client_key_seq;
    }

    fn serverCounter(key_log: *@This()) u64 {
        defer key_log.server_key_seq += 1;
        return key_log.server_key_seq;
    }
};

/// 提供给 `init` 的 `Reader`
/// 要求缓冲区容量至少为此值。
pub const min_buffer_len = tls.max_ciphertext_record_len;

pub const Options = struct {
    /// 如何对服务器证书执行主机名验证。
    host: union(enum) {
        /// 不执行主机验证,因此无法建立
        /// 受信任的连接。
        no_verification,
        /// 验证服务器证书是否为给定主机签发。
        explicit: []const u8,
    },
    /// 如何验证服务器证书的真实性。
    ca: union(enum) {
        /// 未进行 CA 验证,
        /// 因此无法建立受信任的连接。
        no_verification,
        /// 验证服务器证书是否为有效的自签名证书。
        /// 这不提供授权保证,因为任何人都可以创建自签名证书。
        ///
        self_signed,
        /// 验证服务器证书是否由给定 CA 包授权。
        bundle: struct {
            gpa: std.mem.Allocator,
            io: std.Io,
            lock: *std.Io.RwLock,
            bundle: *Certificate.Bundle,
        },
    },
    write_buffer: []u8,
    read_buffer: []u8,
    /// 密码学安全的随机字节。不会捕获指针;仅在
    /// `init` 期间读取数据。
    entropy: *const [entropy_len]u8,
    /// 墙上时钟/日历所示的当前时间。
    realtime_now: std.Io.Timestamp,

    /// 若非 null,则将 SSL 秘密信息记录到此流。有权访问该日志文件的
    /// 其他程序可解密此连接上的全部流量。
    ///
    /// 握手,即 `init` 期间,仅观察 `writer` 字段。
    /// 之后会填充其他字段。
    ssl_key_log: ?*SslKeyLog = null,
    /// 默认情况下,从服务器读取时遇到流结束,除非此前已收到 close_notify 消息,否则返回 `error.TlsConnectionTruncated`。将此标志设为 `true` 后,会改为将流结束转发给 TLS 之上的应用层。
    ///
    /// 除非应用层自行验证接收数据量与预期数据量相等,例如使用 Content-Length 报头的 HTTP,否则这会使应用程序容易受到截断攻击。
    ///
    ///
    ///
    ///
    ///
    allow_truncation_attacks: bool = false,
    /// `init` 返回 `error.TlsAlert` 时填充。
    alert: ?*tls.Alert = null,

    pub const entropy_len = 240;
};

pub const InitError = error{
    InsufficientEntropy,
    DiskQuota,
    LockViolation,
    NotOpenForWriting,
    /// 警报说明将存储在 `alert` 中。
    TlsAlert,
    TlsUnexpectedMessage,
    TlsIllegalParameter,
    TlsDecryptFailure,
    TlsRecordOverflow,
    TlsBadRecordMac,
    CertificateFieldHasInvalidLength,
    CertificateHostMismatch,
    CertificatePublicKeyInvalid,
    CertificateExpired,
    CertificateFieldHasWrongDataType,
    CertificateIssuerMismatch,
    CertificateNotYetValid,
    CertificateSignatureAlgorithmMismatch,
    CertificateSignatureAlgorithmUnsupported,
    CertificateSignatureInvalid,
    CertificateSignatureInvalidLength,
    CertificateSignatureNamedCurveUnsupported,
    CertificateSignatureUnsupportedBitCount,
    TlsCertificateNotVerified,
    TlsBadSignatureScheme,
    TlsBadRsaSignatureBitCount,
    InvalidEncoding,
    IdentityElement,
    SignatureVerificationFailed,
    TlsDecryptError,
    TlsConnectionTruncated,
    TlsDecodeError,
    UnsupportedCertificateVersion,
    CertificateTimeInvalid,
    CertificateHasUnrecognizedObjectId,
    CertificateHasInvalidBitString,
    MessageTooLong,
    NegativeIntoUnsigned,
    TargetTooSmall,
    BufferTooSmall,
    InvalidSignature,
    NotSquare,
    NonCanonical,
    WeakPublicKey,
} || std.Io.Writer.Error || std.Io.Reader.ShortError || std.Io.Cancelable;

/// 发起 TLS 握手,并建立 TLSv1.2 或 TLSv1.3 会话。
///
/// `host` 仅在此函数调用期间被借用。
///
/// 断言 `input` 的缓冲区容量至少为 `min_buffer_len`。
pub fn init(input: *Reader, output: *Writer, options: Options) InitError!Client {
    assert(input.buffer.len >= min_buffer_len);
    const host = switch (options.host) {
        .no_verification => "",
        .explicit => |host| host,
    };
    const host_len: u16 = @intCast(host.len);

    const client_hello_rand = options.entropy[0..32].*;
    var key_seq: u64 = 0;
    var server_hello_rand: [32]u8 = undefined;
    const legacy_session_id = options.entropy[32..64].*;

    var key_share = KeyShare.init(options.entropy[64..240]) catch |err| switch (err) {
        // 仅当种子全为零时才可能发生。
        error.IdentityElement => return error.InsufficientEntropy,
    };

    const extensions_payload = tls.extension(.supported_versions, array(u8, tls.ProtocolVersion, .{
        .tls_1_3,
        .tls_1_2,
    })) ++ tls.extension(.signature_algorithms, array(u16, tls.SignatureScheme, .{
        .ecdsa_secp256r1_sha256,
        .ecdsa_secp384r1_sha384,
        .rsa_pkcs1_sha256,
        .rsa_pkcs1_sha384,
        .rsa_pkcs1_sha512,
        .rsa_pss_rsae_sha256,
        .rsa_pss_rsae_sha384,
        .rsa_pss_rsae_sha512,
        .rsa_pss_pss_sha256,
        .rsa_pss_pss_sha384,
        .rsa_pss_pss_sha512,
        .rsa_pkcs1_sha1,
        .ed25519,
    })) ++ tls.extension(.supported_groups, array(u16, tls.NamedGroup, .{
        .x25519_ml_kem768,
        .secp256r1,
        .secp384r1,
        .x25519,
    })) ++ tls.extension(.psk_key_exchange_modes, array(u8, tls.PskKeyExchangeMode, .{
        .psk_dhe_ke,
    })) ++ tls.extension(.key_share, array(
        u16,
        u8,
        int(u16, @backingInt(tls.NamedGroup.x25519_ml_kem768)) ++
            array(u16, u8, key_share.ml_kem768_kp.public_key.toBytes() ++ key_share.x25519_kp.public_key) ++
            int(u16, @backingInt(tls.NamedGroup.secp256r1)) ++
            array(u16, u8, key_share.secp256r1_kp.public_key.toUncompressedSec1()) ++
            int(u16, @backingInt(tls.NamedGroup.secp384r1)) ++
            array(u16, u8, key_share.secp384r1_kp.public_key.toUncompressedSec1()) ++
            int(u16, @backingInt(tls.NamedGroup.x25519)) ++
            array(u16, u8, key_share.x25519_kp.public_key),
    ));
    const server_name_extension = int(u16, @backingInt(tls.ExtensionType.server_name)) ++
        int(u16, 2 + 1 + 2 + host_len) ++ // 此扩展有效负载的字节长度
        int(u16, 1 + 2 + host_len) ++ // server_name_list 的字节数
        .{0x00} ++ // name_type
        int(u16, host_len);
    const server_name_extension_len = switch (options.host) {
        .no_verification => 0,
        .explicit => server_name_extension.len + host_len,
    };

    const extensions_header =
        int(u16, @intCast(extensions_payload.len + server_name_extension_len)) ++
        extensions_payload ++
        server_name_extension;

    const client_hello =
        int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
        client_hello_rand ++
        [1]u8{32} ++ legacy_session_id ++
        cipher_suites ++
        array(u8, tls.CompressionMethod, .{.null}) ++
        extensions_header;

    const out_handshake = .{@backingInt(tls.HandshakeType.client_hello)} ++
        int(u24, @intCast(client_hello.len - server_name_extension.len + server_name_extension_len)) ++
        client_hello;

    const cleartext_header_buf = .{@backingInt(tls.ContentType.handshake)} ++
        int(u16, @backingInt(tls.ProtocolVersion.tls_1_0)) ++
        int(u16, @intCast(out_handshake.len - server_name_extension.len + server_name_extension_len)) ++
        out_handshake;
    const cleartext_header = switch (options.host) {
        .no_verification => cleartext_header_buf[0 .. cleartext_header_buf.len - server_name_extension.len],
        .explicit => &cleartext_header_buf,
    };

    {
        var iovecs: [2][]const u8 = .{ cleartext_header, host };
        try output.writeVecAll(iovecs[0..if (host.len == 0) 1 else 2]);
        try output.flush();
    }

    var tls_version: tls.ProtocolVersion = undefined;
    var chain: Certificate.Chain = if (Certificate.Chain != void) .empty;
    defer if (Certificate.Chain != void) chain.deinit();
    // 这些用于两个目的:
    // * 检测某证书是否为首次呈现的证书;若是,则需要验证主机名。
    //
    var cert_index: usize = 0;
    // * 在两个明文缓冲区之间交替切换,
    //   将前一张证书保留在内存中,以便
    //   使用下一张证书验证它。
    var cert_buf_index: usize = 0;
    var write_seq: u64 = 0;
    var read_seq: u64 = 0;
    var prev_cert: Certificate.Parsed = undefined;
    const CipherState = enum {
        /// 当前未使用密码算法
        cleartext,
        /// 握手密码算法正在使用中
        handshake,
        /// 应用程序密码算法正在使用中
        application,
    };
    var pending_cipher_state: CipherState = .cleartext;
    var cipher_state = pending_cipher_state;
    const HandshakeState = enum {
        /// 在此状态下,只应收到 server hello 消息。
        hello,
        /// 在此状态下,只应收到 encrypted_extensions 消息。
        encrypted_extensions,
        /// 此状态下,预期接收证书握手消息。
        certificate,
        /// 在此状态下,应收到 certificate 或 certificate_verify 消息。
        /// 由于信任链已经建立,将忽略 certificate 消息。
        ///
        trust_chain_established,
        /// 在此状态下,只应收到 server_hello_done 握手消息。
        server_hello_done,
        /// 此状态下,仅预期接收 finished 握手消息。
        finished,
    };
    var handshake_state: HandshakeState = .hello;
    var handshake_cipher: tls.HandshakeCipher = undefined;
    var main_cert_pub_key: CertificatePublicKey = undefined;
    var tls12_negotiated_group: ?tls.NamedGroup = null;
    const now_sec = options.realtime_now.toSeconds();

    var cleartext_fragment_start: usize = 0;
    var cleartext_fragment_end: usize = 0;
    var cleartext_bufs: [2][tls.max_ciphertext_inner_record_len]u8 = undefined;
    fragment: while (true) {
        const record_header = (input.takeArray(tls.record_header_len) catch |err| switch (err) {
            error.EndOfStream => return error.TlsConnectionTruncated,
            error.ReadFailed => |e| return e,
        }).*;
        const record_ct: tls.ContentType = @fromBackingInt(record_header[0]);
        // record_header[1..3] 为 legacy_version
        const record_len = mem.readInt(u16, record_header[3..5], .big);
        if (record_len > tls.max_ciphertext_len) return error.TlsRecordOverflow;
        const record_buffer = input.take(record_len) catch |err| switch (err) {
            error.EndOfStream => return error.TlsConnectionTruncated,
            error.ReadFailed => |e| return e,
        };
        var record_decoder: tls.Decoder = .fromTheirSlice(record_buffer);
        var ctd, const ct = content: switch (cipher_state) {
            .cleartext => .{ record_decoder, record_ct },
            .handshake => {
                assert(tls_version == .tls_1_3);
                if (record_ct != .application_data) return error.TlsUnexpectedMessage;
                try record_decoder.ensure(record_len);
                const cleartext_buf = &cleartext_bufs[cert_buf_index % 2];
                switch (handshake_cipher) {
                    inline else => |*p| {
                        const pv = &p.version.tls_1_3;
                        const P = @TypeOf(p.*).A;
                        if (record_len < P.AEAD.tag_length) return error.TlsRecordOverflow;
                        const ciphertext = record_decoder.slice(record_len - P.AEAD.tag_length);
                        const cleartext_fragment_buf = cleartext_buf[cleartext_fragment_end..];
                        if (ciphertext.len > cleartext_fragment_buf.len) return error.TlsRecordOverflow;
                        const cleartext = cleartext_fragment_buf[0..ciphertext.len];
                        const auth_tag = record_decoder.array(P.AEAD.tag_length).*;
                        const nonce = nonce: {
                            const V = @Vector(P.AEAD.nonce_length, u8);
                            const pad: [P.AEAD.nonce_length - 8]u8 = @splat(0);
                            const operand: V = pad ++ @as([8]u8, @bitCast(@byteSwap(read_seq)));
                            break :nonce @as(V, pv.server_handshake_iv) ^ operand;
                        };
                        P.AEAD.decrypt(cleartext, ciphertext, auth_tag, &record_header, nonce, pv.server_handshake_key) catch
                            return error.TlsBadRecordMac;
                        // TODO 使用标量而非切片版本
                        const trimmed_len = mem.trimEnd(u8, cleartext, "\x00").len;
                        if (trimmed_len == 0) return error.TlsDecodeError;
                        cleartext_fragment_end += trimmed_len;
                    },
                }
                read_seq += 1;
                cleartext_fragment_end -= 1;
                const ct: tls.ContentType = @fromBackingInt(@intCast(cleartext_buf[cleartext_fragment_end]));
                if (ct != .handshake) return error.TlsUnexpectedMessage;
                break :content .{ tls.Decoder.fromTheirSlice(@constCast(cleartext_buf[cleartext_fragment_start..cleartext_fragment_end])), ct };
            },
            .application => {
                assert(tls_version == .tls_1_2);
                if (record_ct != .handshake) return error.TlsUnexpectedMessage;
                try record_decoder.ensure(record_len);
                const cleartext_buf = &cleartext_bufs[cert_buf_index % 2];
                switch (handshake_cipher) {
                    inline else => |*p| {
                        const pv = &p.version.tls_1_2;
                        const P = @TypeOf(p.*).A;
                        if (record_len < P.record_iv_length + P.mac_length) return error.TlsRecordOverflow;
                        const message_len: u16 = record_len - P.record_iv_length - P.mac_length;
                        const cleartext_fragment_buf = cleartext_buf[cleartext_fragment_end..];
                        if (message_len > cleartext_fragment_buf.len) return error.TlsRecordOverflow;
                        const cleartext = cleartext_fragment_buf[0..message_len];
                        const ad = mem.toBytes(big(read_seq)) ++
                            record_header[0 .. 1 + 2] ++
                            mem.toBytes(big(message_len));
                        const record_iv = record_decoder.array(P.record_iv_length).*;
                        const masked_read_seq = read_seq &
                            comptime std.math.shl(u64, std.math.maxInt(u64), 8 * P.record_iv_length);
                        const nonce: [P.AEAD.nonce_length]u8 = nonce: {
                            const V = @Vector(P.AEAD.nonce_length, u8);
                            const pad: [P.AEAD.nonce_length - 8]u8 = @splat(0);
                            const operand: V = pad ++ @as([8]u8, @bitCast(@byteSwap(masked_read_seq)));
                            break :nonce @as(V, pv.app_cipher.server_write_IV ++ record_iv) ^ operand;
                        };
                        const ciphertext = record_decoder.slice(message_len);
                        const auth_tag = record_decoder.array(P.mac_length);
                        P.AEAD.decrypt(cleartext, ciphertext, auth_tag.*, ad, nonce, pv.app_cipher.server_write_key) catch return error.TlsBadRecordMac;
                        cleartext_fragment_end += message_len;
                    },
                }
                read_seq += 1;
                break :content .{ tls.Decoder.fromTheirSlice(cleartext_buf[cleartext_fragment_start..cleartext_fragment_end]), record_ct };
            },
        };
        switch (ct) {
            .alert => {
                ctd.ensure(2) catch continue :fragment;
                if (options.alert) |a| a.* = .{
                    .level = ctd.decode(tls.Alert.Level),
                    .description = ctd.decode(tls.Alert.Description),
                };
                return error.TlsAlert;
            },
            .change_cipher_spec => {
                ctd.ensure(1) catch continue :fragment;
                if (ctd.decode(tls.ChangeCipherSpecType) != .change_cipher_spec) return error.TlsIllegalParameter;
                cipher_state = pending_cipher_state;
            },
            .handshake => while (true) {
                ctd.ensure(4) catch continue :fragment;
                const handshake_type = ctd.decode(tls.HandshakeType);
                const handshake_len = ctd.decode(u24);
                var hsd = ctd.sub(handshake_len) catch continue :fragment;
                const wrapped_handshake = ctd.buf[ctd.idx - handshake_len - 4 .. ctd.idx];
                switch (handshake_type) {
                    .server_hello => {
                        if (cipher_state != .cleartext) return error.TlsUnexpectedMessage;
                        if (handshake_state != .hello) return error.TlsUnexpectedMessage;
                        try hsd.ensure(2 + 32 + 1);
                        const legacy_version = hsd.decode(u16);
                        @memcpy(&server_hello_rand, hsd.array(32));
                        if (mem.eql(u8, &server_hello_rand, &tls.hello_retry_request_sequence)) {
                            // 这是 HelloRetryRequest 消息。此客户端实现
                            // 不预期收到该消息。
                            return error.TlsUnexpectedMessage;
                        }
                        const legacy_session_id_echo_len = hsd.decode(u8);
                        try hsd.ensure(legacy_session_id_echo_len + 2 + 1);
                        const legacy_session_id_echo = hsd.slice(legacy_session_id_echo_len);
                        const cipher_suite_tag = hsd.decode(tls.CipherSuite);
                        hsd.skip(1); // legacy_compression_method
                        var supported_version: ?u16 = null;
                        if (!hsd.eof()) {
                            try hsd.ensure(2);
                            const extensions_size = hsd.decode(u16);
                            var all_extd = try hsd.sub(extensions_size);
                            while (!all_extd.eof()) {
                                try all_extd.ensure(2 + 2);
                                const et = all_extd.decode(tls.ExtensionType);
                                const ext_size = all_extd.decode(u16);
                                var extd = try all_extd.sub(ext_size);
                                switch (et) {
                                    .supported_versions => {
                                        if (supported_version) |_| return error.TlsIllegalParameter;
                                        try extd.ensure(2);
                                        supported_version = extd.decode(u16);
                                    },
                                    .key_share => {
                                        if (key_share.getSharedSecret()) |_| return error.TlsIllegalParameter;
                                        try extd.ensure(4);
                                        const named_group = extd.decode(tls.NamedGroup);
                                        const key_size = extd.decode(u16);
                                        try extd.ensure(key_size);
                                        try key_share.exchange(named_group, extd.slice(key_size));
                                    },
                                    else => {},
                                }
                            }
                        }

                        tls_version = @fromBackingInt(@intCast(supported_version orelse legacy_version));
                        switch (tls_version) {
                            .tls_1_3 => if (!mem.eql(u8, legacy_session_id_echo, &legacy_session_id)) return error.TlsIllegalParameter,
                            .tls_1_2 => if (mem.eql(u8, server_hello_rand[24..31], "DOWNGRD") and
                                server_hello_rand[31] >> 1 == 0x00) return error.TlsIllegalParameter,
                            else => return error.TlsIllegalParameter,
                        }

                        switch (cipher_suite_tag) {
                            inline .AES_128_GCM_SHA256,
                            .AES_256_GCM_SHA384,
                            .CHACHA20_POLY1305_SHA256,
                            .AEGIS_256_SHA512,
                            .AEGIS_128L_SHA256,

                            .ECDHE_RSA_WITH_AES_128_GCM_SHA256,
                            .ECDHE_RSA_WITH_AES_256_GCM_SHA384,
                            .ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
                            => |tag| {
                                handshake_cipher = @unionInit(tls.HandshakeCipher, @tagName(tag.with()), .{
                                    .transcript_hash = .init(.{}),
                                    .version = undefined,
                                });
                                const p = &@field(handshake_cipher, @tagName(tag.with()));
                                p.transcript_hash.update(cleartext_header[tls.record_header_len..]); // Client Hello 第 1 部分
                                p.transcript_hash.update(host); // Client Hello 第 2 部分
                                p.transcript_hash.update(wrapped_handshake);
                            },

                            else => return error.TlsIllegalParameter,
                        }
                        switch (tls_version) {
                            .tls_1_3 => {
                                switch (cipher_suite_tag) {
                                    inline .AES_128_GCM_SHA256,
                                    .AES_256_GCM_SHA384,
                                    .CHACHA20_POLY1305_SHA256,
                                    .AEGIS_256_SHA512,
                                    .AEGIS_128L_SHA256,
                                    => |tag| {
                                        const sk = key_share.getSharedSecret() orelse return error.TlsIllegalParameter;
                                        const p = &@field(handshake_cipher, @tagName(tag.with()));
                                        const P = @TypeOf(p.*).A;
                                        const hello_hash = p.transcript_hash.peek();
                                        const zeroes: [P.Hash.digest_length]u8 = @splat(0);
                                        const early_secret = P.Hkdf.extract(&[1]u8{0}, &zeroes);
                                        const empty_hash = tls.emptyHash(P.Hash);
                                        p.version = .{ .tls_1_3 = undefined };
                                        const pv = &p.version.tls_1_3;
                                        const hs_derived_secret = hkdfExpandLabel(P.Hkdf, early_secret, "derived", &empty_hash, P.Hash.digest_length);
                                        pv.handshake_secret = P.Hkdf.extract(&hs_derived_secret, sk);
                                        const ap_derived_secret = hkdfExpandLabel(P.Hkdf, pv.handshake_secret, "derived", &empty_hash, P.Hash.digest_length);
                                        pv.master_secret = P.Hkdf.extract(&ap_derived_secret, &zeroes);
                                        const client_secret = hkdfExpandLabel(P.Hkdf, pv.handshake_secret, "c hs traffic", &hello_hash, P.Hash.digest_length);
                                        const server_secret = hkdfExpandLabel(P.Hkdf, pv.handshake_secret, "s hs traffic", &hello_hash, P.Hash.digest_length);
                                        if (options.ssl_key_log) |key_log| logSecrets(key_log.writer, .{
                                            .client_random = &client_hello_rand,
                                        }, .{
                                            .SERVER_HANDSHAKE_TRAFFIC_SECRET = &server_secret,
                                            .CLIENT_HANDSHAKE_TRAFFIC_SECRET = &client_secret,
                                        });
                                        pv.client_finished_key = hkdfExpandLabel(P.Hkdf, client_secret, "finished", "", P.Hmac.key_length);
                                        pv.server_finished_key = hkdfExpandLabel(P.Hkdf, server_secret, "finished", "", P.Hmac.key_length);
                                        pv.client_handshake_key = hkdfExpandLabel(P.Hkdf, client_secret, "key", "", P.AEAD.key_length);
                                        pv.server_handshake_key = hkdfExpandLabel(P.Hkdf, server_secret, "key", "", P.AEAD.key_length);
                                        pv.client_handshake_iv = hkdfExpandLabel(P.Hkdf, client_secret, "iv", "", P.AEAD.nonce_length);
                                        pv.server_handshake_iv = hkdfExpandLabel(P.Hkdf, server_secret, "iv", "", P.AEAD.nonce_length);
                                    },
                                    else => return error.TlsIllegalParameter,
                                }
                                pending_cipher_state = .handshake;
                                handshake_state = .encrypted_extensions;
                            },
                            .tls_1_2 => switch (cipher_suite_tag) {
                                .ECDHE_RSA_WITH_AES_128_GCM_SHA256,
                                .ECDHE_RSA_WITH_AES_256_GCM_SHA384,
                                .ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
                                => handshake_state = .certificate,
                                else => return error.TlsIllegalParameter,
                            },
                            else => return error.TlsIllegalParameter,
                        }
                    },
                    .encrypted_extensions => {
                        if (tls_version != .tls_1_3) return error.TlsUnexpectedMessage;
                        if (cipher_state != .handshake) return error.TlsUnexpectedMessage;
                        if (handshake_state != .encrypted_extensions) return error.TlsUnexpectedMessage;
                        switch (handshake_cipher) {
                            inline else => |*p| p.transcript_hash.update(wrapped_handshake),
                        }
                        try hsd.ensure(2);
                        const total_ext_size = hsd.decode(u16);
                        var all_extd = try hsd.sub(total_ext_size);
                        while (!all_extd.eof()) {
                            try all_extd.ensure(4);
                            const et = all_extd.decode(tls.ExtensionType);
                            const ext_size = all_extd.decode(u16);
                            const extd = try all_extd.sub(ext_size);
                            _ = extd;
                            switch (et) {
                                .server_name => {},
                                else => {},
                            }
                        }
                        handshake_state = .certificate;
                    },
                    .certificate => cert: {
                        if (cipher_state == .application) return error.TlsUnexpectedMessage;
                        switch (handshake_state) {
                            .certificate => {},
                            .trust_chain_established => break :cert,
                            else => return error.TlsUnexpectedMessage,
                        }
                        switch (handshake_cipher) {
                            inline else => |*p| p.transcript_hash.update(wrapped_handshake),
                        }

                        switch (tls_version) {
                            .tls_1_3 => {
                                try hsd.ensure(1 + 3);
                                const cert_req_ctx_len = hsd.decode(u8);
                                if (cert_req_ctx_len != 0) return error.TlsIllegalParameter;
                            },
                            .tls_1_2 => try hsd.ensure(3),
                            else => unreachable,
                        }
                        const certs_size = hsd.decode(u24);
                        const certs = try hsd.sub(certs_size);

                        var certs_decoder = certs;
                        while (!certs_decoder.eof()) {
                            try certs_decoder.ensure(3);
                            const cert_size = certs_decoder.decode(u24);
                            const certd = try certs_decoder.sub(cert_size);

                            if (tls_version == .tls_1_3) {
                                try certs_decoder.ensure(2);
                                const total_ext_size = certs_decoder.decode(u16);
                                const all_extd = try certs_decoder.sub(total_ext_size);
                                _ = all_extd;
                            }

                            const subject_cert: Certificate = .{
                                .buffer = certd.buf,
                                .index = @intCast(certd.idx),
                            };
                            const subject = try subject_cert.parse();
                            if (cert_index == 0) {
                                // 在第一张证书中验证主机。
                                switch (options.host) {
                                    .no_verification => {},
                                    .explicit => try subject.verifyHostName(host),
                                }

                                // 保存公钥,
                                // 供后续 certificate_verify 消息使用。
                                try main_cert_pub_key.init(subject.pub_key_algo, subject.pubKey());
                            } else {
                                try prev_cert.verify(subject, now_sec);
                            }

                            switch (options.ca) {
                                .no_verification => {
                                    handshake_state = .trust_chain_established;
                                    break :cert;
                                },
                                .self_signed => {
                                    try subject.verify(subject, now_sec);
                                    handshake_state = .trust_chain_established;
                                    break :cert;
                                },
                                .bundle => |ca| if (verify: {
                                    try ca.lock.lockShared(ca.io);
                                    defer ca.lock.unlockShared(ca.io);
                                    break :verify ca.bundle.verify(subject, now_sec);
                                }) {
                                    handshake_state = .trust_chain_established;
                                    break :cert;
                                } else |err| switch (err) {
                                    error.CertificateIssuerNotFound => {},
                                    else => |e| return e,
                                },
                            }

                            prev_cert = subject;
                            cert_index += 1;
                        }

                        if (Certificate.Chain != void) {
                            certs_decoder = certs;
                            while (!certs_decoder.eof()) {
                                try certs_decoder.ensure(3);
                                const cert_size = certs_decoder.decode(u24);
                                const certd = try certs_decoder.sub(cert_size);
                                chain.addCert(certd.rest()) catch |err| switch (err) {
                                    error.Unexpected => return error.TlsCertificateNotVerified,
                                };
                                if (tls_version == .tls_1_3) {
                                    try certs_decoder.ensure(2);
                                    const total_ext_size = certs_decoder.decode(u16);
                                    const all_extd = try certs_decoder.sub(total_ext_size);
                                    _ = all_extd;
                                }
                            }
                        }

                        cert_buf_index += 1;
                    },
                    .server_key_exchange => {
                        if (tls_version != .tls_1_2) return error.TlsUnexpectedMessage;
                        if (cipher_state != .cleartext) return error.TlsUnexpectedMessage;
                        switch (handshake_state) {
                            .trust_chain_established => {},
                            .certificate => try tryDownloadRootCert(&chain, &options),
                            else => return error.TlsUnexpectedMessage,
                        }

                        switch (handshake_cipher) {
                            inline else => |*p| p.transcript_hash.update(wrapped_handshake),
                        }
                        try hsd.ensure(1 + 2 + 1);
                        const curve_type = hsd.decode(u8);
                        if (curve_type != 0x03) return error.TlsIllegalParameter; // named_curve
                        const named_group = hsd.decode(tls.NamedGroup);
                        tls12_negotiated_group = named_group;
                        const key_size = hsd.decode(u8);
                        try hsd.ensure(key_size);
                        const server_pub_key = hsd.slice(key_size);
                        try main_cert_pub_key.verifySignature(&hsd, &.{ &client_hello_rand, &server_hello_rand, hsd.buf[0..hsd.idx] });
                        try key_share.exchange(named_group, server_pub_key);
                        handshake_state = .server_hello_done;
                    },
                    .server_hello_done => {
                        if (tls_version != .tls_1_2) return error.TlsUnexpectedMessage;
                        if (cipher_state != .cleartext) return error.TlsUnexpectedMessage;
                        if (handshake_state != .server_hello_done) return error.TlsUnexpectedMessage;

                        const public_key_bytes: []const u8 = switch (tls12_negotiated_group orelse .secp256r1) {
                            .secp256r1 => &key_share.secp256r1_kp.public_key.toUncompressedSec1(),
                            .secp384r1 => &key_share.secp384r1_kp.public_key.toUncompressedSec1(),
                            .x25519 => &key_share.x25519_kp.public_key,
                            else => return error.TlsIllegalParameter,
                        };

                        const client_key_exchange_prefix = .{@backingInt(tls.ContentType.handshake)} ++
                            int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
                            int(u16, @intCast(public_key_bytes.len + 5)) ++ // 记录长度
                            .{@backingInt(tls.HandshakeType.client_key_exchange)} ++
                            int(u24, @intCast(public_key_bytes.len + 1)) ++ // 握手消息长度
                            .{@as(u8, @intCast(public_key_bytes.len))}; // 公钥长度
                        const client_change_cipher_spec_msg = .{@backingInt(tls.ContentType.change_cipher_spec)} ++
                            int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
                            array(u16, tls.ChangeCipherSpecType, .{.change_cipher_spec});
                        const pre_master_secret = key_share.getSharedSecret().?;
                        switch (handshake_cipher) {
                            inline else => |*p| {
                                const P = @TypeOf(p.*).A;
                                p.transcript_hash.update(wrapped_handshake);
                                p.transcript_hash.update(client_key_exchange_prefix[tls.record_header_len..]);
                                p.transcript_hash.update(public_key_bytes);
                                const master_secret = hmacExpandLabel(P.Hmac, pre_master_secret, &.{
                                    "master secret",
                                    &client_hello_rand,
                                    &server_hello_rand,
                                }, 48);
                                if (options.ssl_key_log) |key_log| logSecrets(key_log.writer, .{
                                    .client_random = &client_hello_rand,
                                }, .{
                                    .CLIENT_RANDOM = &master_secret,
                                });
                                const key_block = hmacExpandLabel(
                                    P.Hmac,
                                    &master_secret,
                                    &.{ "key expansion", &server_hello_rand, &client_hello_rand },
                                    @sizeOf(P.Tls_1_2),
                                );
                                const client_verify_cleartext = .{@backingInt(tls.HandshakeType.finished)} ++
                                    array(u24, u8, hmacExpandLabel(
                                        P.Hmac,
                                        &master_secret,
                                        &.{ "client finished", &p.transcript_hash.peek() },
                                        P.verify_data_length,
                                    ));
                                p.transcript_hash.update(&client_verify_cleartext);
                                p.version = .{ .tls_1_2 = .{
                                    .expected_server_verify_data = hmacExpandLabel(
                                        P.Hmac,
                                        &master_secret,
                                        &.{ "server finished", &p.transcript_hash.finalResult() },
                                        P.verify_data_length,
                                    ),
                                    .app_cipher = mem.bytesToValue(P.Tls_1_2, &key_block),
                                } };
                                const pv = &p.version.tls_1_2;
                                const nonce: [P.AEAD.nonce_length]u8 = nonce: {
                                    const V = @Vector(P.AEAD.nonce_length, u8);
                                    const pad: [P.AEAD.nonce_length - 8]u8 = @splat(0);
                                    const operand: V = pad ++ @as([8]u8, @bitCast(@byteSwap(write_seq)));
                                    break :nonce @as(V, pv.app_cipher.client_write_IV ++ pv.app_cipher.client_salt) ^ operand;
                                };
                                var client_verify_msg = .{@backingInt(tls.ContentType.handshake)} ++
                                    int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
                                    array(u16, u8, nonce[P.fixed_iv_length..].* ++
                                        @as([client_verify_cleartext.len + P.mac_length]u8, undefined));
                                P.AEAD.encrypt(
                                    client_verify_msg[client_verify_msg.len - P.mac_length -
                                        client_verify_cleartext.len ..][0..client_verify_cleartext.len],
                                    client_verify_msg[client_verify_msg.len - P.mac_length ..][0..P.mac_length],
                                    &client_verify_cleartext,
                                    mem.toBytes(big(write_seq)) ++ client_verify_msg[0 .. 1 + 2] ++ int(u16, client_verify_cleartext.len),
                                    nonce,
                                    pv.app_cipher.client_write_key,
                                );
                                var all_msgs_vec: [4][]const u8 = .{
                                    &client_key_exchange_prefix,
                                    public_key_bytes,
                                    &client_change_cipher_spec_msg,
                                    &client_verify_msg,
                                };
                                try output.writeVecAll(&all_msgs_vec);
                                try output.flush();
                            },
                        }
                        write_seq += 1;
                        pending_cipher_state = .application;
                        handshake_state = .finished;
                    },
                    .certificate_verify => {
                        if (tls_version != .tls_1_3) return error.TlsUnexpectedMessage;
                        if (cipher_state != .handshake) return error.TlsUnexpectedMessage;
                        switch (handshake_state) {
                            .trust_chain_established => {},
                            .certificate => try tryDownloadRootCert(&chain, &options),
                            else => return error.TlsUnexpectedMessage,
                        }
                        switch (handshake_cipher) {
                            inline else => |*p| {
                                const pad: [64]u8 = @splat(' ');
                                try main_cert_pub_key.verifySignature(&hsd, &.{
                                    pad ++ "TLS 1.3, server CertificateVerify\x00",
                                    &p.transcript_hash.peek(),
                                });
                                p.transcript_hash.update(wrapped_handshake);
                            },
                        }
                        handshake_state = .finished;
                    },
                    .finished => {
                        if (cipher_state == .cleartext) return error.TlsUnexpectedMessage;
                        if (handshake_state != .finished) return error.TlsUnexpectedMessage;
                        // 此消息用于使有缺陷的代理表现正确。
                        const client_change_cipher_spec_msg = .{@backingInt(tls.ContentType.change_cipher_spec)} ++
                            int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
                            array(u16, tls.ChangeCipherSpecType, .{.change_cipher_spec});
                        const app_cipher = app_cipher: switch (handshake_cipher) {
                            inline else => |*p, tag| switch (tls_version) {
                                .tls_1_3 => {
                                    const pv = &p.version.tls_1_3;
                                    const P = @TypeOf(p.*).A;
                                    try hsd.ensure(P.Hmac.mac_length);
                                    const finished_digest = p.transcript_hash.peek();
                                    p.transcript_hash.update(wrapped_handshake);
                                    const expected_server_verify_data = tls.hmac(P.Hmac, &finished_digest, pv.server_finished_key);
                                    if (!std.crypto.timing_safe.eql([P.Hmac.mac_length]u8, expected_server_verify_data, hsd.array(P.Hmac.mac_length).*)) return error.TlsDecryptError;
                                    const handshake_hash = p.transcript_hash.finalResult();
                                    const verify_data = tls.hmac(P.Hmac, &handshake_hash, pv.client_finished_key);
                                    const out_cleartext = .{@backingInt(tls.HandshakeType.finished)} ++
                                        array(u24, u8, verify_data) ++
                                        .{@backingInt(tls.ContentType.handshake)};

                                    const wrapped_len = out_cleartext.len + P.AEAD.tag_length;

                                    var finished_msg = .{@backingInt(tls.ContentType.application_data)} ++
                                        int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
                                        array(u16, u8, @as([wrapped_len]u8, undefined));

                                    const ad = finished_msg[0..tls.record_header_len];
                                    const ciphertext = finished_msg[tls.record_header_len..][0..out_cleartext.len];
                                    const auth_tag = finished_msg[finished_msg.len - P.AEAD.tag_length ..];
                                    const nonce = pv.client_handshake_iv;
                                    P.AEAD.encrypt(ciphertext, auth_tag, &out_cleartext, ad, nonce, pv.client_handshake_key);

                                    var all_msgs_vec: [2][]const u8 = .{
                                        &client_change_cipher_spec_msg,
                                        &finished_msg,
                                    };
                                    try output.writeVecAll(&all_msgs_vec);
                                    try output.flush();

                                    const client_secret = hkdfExpandLabel(P.Hkdf, pv.master_secret, "c ap traffic", &handshake_hash, P.Hash.digest_length);
                                    const server_secret = hkdfExpandLabel(P.Hkdf, pv.master_secret, "s ap traffic", &handshake_hash, P.Hash.digest_length);
                                    if (options.ssl_key_log) |key_log| logSecrets(key_log.writer, .{
                                        .counter = key_seq,
                                        .client_random = &client_hello_rand,
                                    }, .{
                                        .SERVER_TRAFFIC_SECRET = &server_secret,
                                        .CLIENT_TRAFFIC_SECRET = &client_secret,
                                    });
                                    key_seq += 1;
                                    break :app_cipher @unionInit(tls.ApplicationCipher, @tagName(tag), .{ .tls_1_3 = .{
                                        .client_secret = client_secret,
                                        .server_secret = server_secret,
                                        .client_key = hkdfExpandLabel(P.Hkdf, client_secret, "key", "", P.AEAD.key_length),
                                        .server_key = hkdfExpandLabel(P.Hkdf, server_secret, "key", "", P.AEAD.key_length),
                                        .client_iv = hkdfExpandLabel(P.Hkdf, client_secret, "iv", "", P.AEAD.nonce_length),
                                        .server_iv = hkdfExpandLabel(P.Hkdf, server_secret, "iv", "", P.AEAD.nonce_length),
                                    } });
                                },
                                .tls_1_2 => {
                                    const pv = &p.version.tls_1_2;
                                    const P = @TypeOf(p.*).A;
                                    try hsd.ensure(P.verify_data_length);
                                    if (!std.crypto.timing_safe.eql([P.verify_data_length]u8, pv.expected_server_verify_data, hsd.array(P.verify_data_length).*)) return error.TlsDecryptError;
                                    break :app_cipher @unionInit(tls.ApplicationCipher, @tagName(tag), .{ .tls_1_2 = pv.app_cipher });
                                },
                                else => unreachable,
                            },
                        };
                        if (options.ssl_key_log) |ssl_key_log| ssl_key_log.* = .{
                            .client_key_seq = key_seq,
                            .server_key_seq = key_seq,
                            .client_random = client_hello_rand,
                            .writer = ssl_key_log.writer,
                        };
                        return .{
                            .input = input,
                            .reader = .{
                                .buffer = options.read_buffer,
                                .vtable = &.{
                                    .stream = stream,
                                    .readVec = readVec,
                                },
                                .seek = 0,
                                .end = 0,
                            },
                            .output = output,
                            .writer = .{
                                .buffer = options.write_buffer,
                                .vtable = &.{
                                    .drain = drain,
                                    .flush = flush,
                                },
                            },
                            .tls_version = tls_version,
                            .read_seq = switch (tls_version) {
                                .tls_1_3 => 0,
                                .tls_1_2 => read_seq,
                                else => unreachable,
                            },
                            .write_seq = switch (tls_version) {
                                .tls_1_3 => 0,
                                .tls_1_2 => write_seq,
                                else => unreachable,
                            },
                            .received_close_notify = false,
                            .allow_truncation_attacks = options.allow_truncation_attacks,
                            .application_cipher = app_cipher,
                            .ssl_key_log = options.ssl_key_log,
                        };
                    },
                    else => return error.TlsUnexpectedMessage,
                }
                if (ctd.eof()) break;
                cleartext_fragment_start = ctd.idx;
            },
            else => return error.TlsUnexpectedMessage,
        }
        cleartext_fragment_start = 0;
        cleartext_fragment_end = 0;
    }
}

fn drain(w: *Writer, data: []const []const u8, splat: usize) Writer.Error!usize {
    const c: *Client = @alignCast(@fieldParentPtr("writer", w));
    const output = c.output;
    const ciphertext_buf = try output.writableSliceGreedy(min_buffer_len);
    var ciphertext_end: usize = 0;
    var total_clear: usize = 0;
    done: {
        {
            const buf = w.buffered();
            const prepared = prepareCiphertextRecord(c, ciphertext_buf[ciphertext_end..], buf, .application_data);
            total_clear += prepared.cleartext_len;
            ciphertext_end += prepared.ciphertext_end;
            if (prepared.cleartext_len < buf.len) break :done;
        }
        for (data[0 .. data.len - 1]) |buf| {
            const prepared = prepareCiphertextRecord(c, ciphertext_buf[ciphertext_end..], buf, .application_data);
            total_clear += prepared.cleartext_len;
            ciphertext_end += prepared.ciphertext_end;
            if (prepared.cleartext_len < buf.len) break :done;
        }
        const buf = data[data.len - 1];
        for (0..splat) |_| {
            const prepared = prepareCiphertextRecord(c, ciphertext_buf[ciphertext_end..], buf, .application_data);
            total_clear += prepared.cleartext_len;
            ciphertext_end += prepared.ciphertext_end;
            if (prepared.cleartext_len < buf.len) break :done;
        }
    }
    output.advance(ciphertext_end);
    return w.consume(total_clear);
}

fn flush(w: *Writer) Writer.Error!void {
    const c: *Client = @alignCast(@fieldParentPtr("writer", w));
    const output = c.output;
    const ciphertext_buf = try output.writableSliceGreedy(min_buffer_len);
    const prepared = prepareCiphertextRecord(c, ciphertext_buf, w.buffered(), .application_data);
    output.advance(prepared.ciphertext_end);
    w.end = 0;
}

/// 发送 `close_notify` 警报,使服务器能够区分
/// 正常完成的 TLS 会话与截断攻击。
///
pub fn end(c: *Client) Writer.Error!void {
    try flush(&c.writer);
    const output = c.output;
    const ciphertext_buf = try output.writableSliceGreedy(min_buffer_len);
    const prepared = prepareCiphertextRecord(c, ciphertext_buf, &tls.close_notify_alert, .alert);
    output.advance(prepared.ciphertext_end);
}

fn prepareCiphertextRecord(
    c: *Client,
    ciphertext_buf: []u8,
    bytes: []const u8,
    inner_content_type: tls.ContentType,
) struct {
    ciphertext_end: usize,
    cleartext_len: usize,
} {
    // 由于密文末尾包含内部内容类型字节,需要额外缓冲区,
    // 在加密前存储明文。
    var cleartext_buf: [max_ciphertext_len]u8 = undefined;
    var ciphertext_end: usize = 0;
    var bytes_i: usize = 0;
    switch (c.application_cipher) {
        inline else => |*p| switch (c.tls_version) {
            .tls_1_3 => {
                const pv = &p.tls_1_3;
                const P = @TypeOf(p.*);
                const overhead_len = tls.record_header_len + P.AEAD.tag_length + 1;
                while (true) {
                    const encrypted_content_len: u16 = @min(
                        bytes.len - bytes_i,
                        tls.max_ciphertext_inner_record_len,
                        ciphertext_buf.len -| (overhead_len + ciphertext_end),
                    );
                    if (encrypted_content_len == 0) return .{
                        .ciphertext_end = ciphertext_end,
                        .cleartext_len = bytes_i,
                    };

                    @memcpy(cleartext_buf[0..encrypted_content_len], bytes[bytes_i..][0..encrypted_content_len]);
                    cleartext_buf[encrypted_content_len] = @backingInt(inner_content_type);
                    bytes_i += encrypted_content_len;
                    const ciphertext_len = encrypted_content_len + 1;
                    const cleartext = cleartext_buf[0..ciphertext_len];

                    const ad = ciphertext_buf[ciphertext_end..][0..tls.record_header_len];
                    ad.* = .{@backingInt(tls.ContentType.application_data)} ++
                        int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
                        int(u16, ciphertext_len + P.AEAD.tag_length);
                    ciphertext_end += ad.len;
                    const ciphertext = ciphertext_buf[ciphertext_end..][0..ciphertext_len];
                    ciphertext_end += ciphertext_len;
                    const auth_tag = ciphertext_buf[ciphertext_end..][0..P.AEAD.tag_length];
                    ciphertext_end += auth_tag.len;
                    const nonce = nonce: {
                        const V = @Vector(P.AEAD.nonce_length, u8);
                        const pad: [P.AEAD.nonce_length - 8]u8 = @splat(0);
                        const operand: V = pad ++ mem.toBytes(big(c.write_seq));
                        break :nonce @as(V, pv.client_iv) ^ operand;
                    };
                    P.AEAD.encrypt(ciphertext, auth_tag, cleartext, ad, nonce, pv.client_key);
                    c.write_seq += 1; // TODO 溢出时发送 key_update
                }
            },
            .tls_1_2 => {
                const pv = &p.tls_1_2;
                const P = @TypeOf(p.*);
                const overhead_len = tls.record_header_len + P.record_iv_length + P.mac_length;
                while (true) {
                    const message_len: u16 = @min(
                        bytes.len - bytes_i,
                        tls.max_ciphertext_inner_record_len,
                        ciphertext_buf.len -| (overhead_len + ciphertext_end),
                    );
                    if (message_len == 0) return .{
                        .ciphertext_end = ciphertext_end,
                        .cleartext_len = bytes_i,
                    };

                    @memcpy(cleartext_buf[0..message_len], bytes[bytes_i..][0..message_len]);
                    bytes_i += message_len;
                    const cleartext = cleartext_buf[0..message_len];

                    const record_header = ciphertext_buf[ciphertext_end..][0..tls.record_header_len];
                    ciphertext_end += tls.record_header_len;
                    record_header.* = .{@backingInt(inner_content_type)} ++
                        int(u16, @backingInt(tls.ProtocolVersion.tls_1_2)) ++
                        int(u16, P.record_iv_length + message_len + P.mac_length);
                    const ad = mem.toBytes(big(c.write_seq)) ++ record_header[0 .. 1 + 2] ++ int(u16, message_len);
                    const record_iv = ciphertext_buf[ciphertext_end..][0..P.record_iv_length];
                    ciphertext_end += P.record_iv_length;
                    const nonce: [P.AEAD.nonce_length]u8 = nonce: {
                        const V = @Vector(P.AEAD.nonce_length, u8);
                        const pad: [P.AEAD.nonce_length - 8]u8 = @splat(0);
                        const operand: V = pad ++ @as([8]u8, @bitCast(@byteSwap(c.write_seq)));
                        break :nonce @as(V, pv.client_write_IV ++ pv.client_salt) ^ operand;
                    };
                    record_iv.* = nonce[P.fixed_iv_length..].*;
                    const ciphertext = ciphertext_buf[ciphertext_end..][0..message_len];
                    ciphertext_end += message_len;
                    const auth_tag = ciphertext_buf[ciphertext_end..][0..P.mac_length];
                    ciphertext_end += P.mac_length;
                    P.AEAD.encrypt(ciphertext, auth_tag, cleartext, ad, nonce, pv.client_write_key);
                    c.write_seq += 1; // TODO 溢出时发送 key_update
                }
            },
            else => unreachable,
        },
    }
}

pub fn eof(c: Client) bool {
    return c.received_close_notify;
}

fn stream(r: *Reader, w: *Writer, limit: std.Io.Limit) Reader.StreamError!usize {
    // 此函数仅写入缓冲区。
    _ = w;
    _ = limit;
    const c: *Client = @alignCast(@fieldParentPtr("reader", r));
    return readIndirect(c);
}

fn readVec(r: *Reader, data: [][]u8) Reader.Error!usize {
    // 此函数仅写入缓冲区。
    _ = data;
    const c: *Client = @alignCast(@fieldParentPtr("reader", r));
    return readIndirect(c);
}

fn readIndirect(c: *Client) Reader.Error!usize {
    const r = &c.reader;
    if (c.eof()) return error.EndOfStream;
    const input = c.input;
    // 若缓冲区中不足一个完整加密记录,则读取一次。
    const record_header = input.peek(tls.record_header_len) catch |err| switch (err) {
        error.EndOfStream => {
            // 这可能是截断攻击、服务器缺陷,或因
            // TLS 上层负责截断检测,
            // 而有意省略了 close_notify 消息。
            if (c.allow_truncation_attacks) {
                c.received_close_notify = true;
                return error.EndOfStream;
            } else {
                return failRead(c, error.TlsConnectionTruncated);
            }
        },
        error.ReadFailed => |e| return e,
    };
    const ct: tls.ContentType = @fromBackingInt(@intCast(record_header[0]));
    const legacy_version = mem.readInt(u16, record_header[1..][0..2], .big);
    _ = legacy_version;
    const record_len = mem.readInt(u16, record_header[3..][0..2], .big);
    if (record_len > max_ciphertext_len) return failRead(c, error.TlsRecordOverflow);
    const record_end = 5 + record_len;
    if (record_end > input.buffered().len) {
        input.fillMore() catch |err| switch (err) {
            error.EndOfStream => return failRead(c, error.TlsConnectionTruncated),
            error.ReadFailed => |e| return e,
        };
        if (record_end > input.buffered().len) return 0;
    }

    const cleartext_len, const inner_ct: tls.ContentType = cleartext: switch (c.application_cipher) {
        inline else => |*p| switch (c.tls_version) {
            .tls_1_3 => {
                const pv = &p.tls_1_3;
                const P = @TypeOf(p.*);
                if (record_len < P.AEAD.tag_length) return failRead(c, error.TlsRecordOverflow);
                const ad = input.take(tls.record_header_len) catch unreachable; // 已窥视
                const ciphertext_len = record_len - P.AEAD.tag_length;
                const ciphertext = input.take(ciphertext_len) catch unreachable; // 已窥视
                const auth_tag = (input.takeArray(P.AEAD.tag_length) catch unreachable).*; // 已窥视
                const nonce = nonce: {
                    const V = @Vector(P.AEAD.nonce_length, u8);
                    const pad: [P.AEAD.nonce_length - 8]u8 = @splat(0);
                    const operand: V = pad ++ mem.toBytes(big(c.read_seq));
                    break :nonce @as(V, pv.server_iv) ^ operand;
                };
                rebase(r, ciphertext.len);
                const cleartext = r.buffer[r.end..][0..ciphertext.len];
                P.AEAD.decrypt(cleartext, ciphertext, auth_tag, ad, nonce, pv.server_key) catch
                    return failRead(c, error.TlsBadRecordMac);
                // TODO 使用标量而非切片版本
                const msg = mem.trimEnd(u8, cleartext, "\x00");
                if (msg.len == 0) return failRead(c, error.TlsDecodeError);
                break :cleartext .{ msg.len - 1, @fromBackingInt(@intCast(msg[msg.len - 1])) };
            },
            .tls_1_2 => {
                const pv = &p.tls_1_2;
                const P = @TypeOf(p.*);
                if (record_len < P.record_iv_length + P.mac_length) return failRead(c, error.TlsRecordOverflow);
                const message_len: u16 = record_len - P.record_iv_length - P.mac_length;
                const ad_header = input.take(tls.record_header_len) catch unreachable; // 已窥视
                const ad = mem.toBytes(big(c.read_seq)) ++
                    ad_header[0 .. 1 + 2] ++
                    mem.toBytes(big(message_len));
                const record_iv = (input.takeArray(P.record_iv_length) catch unreachable).*; // 已窥视
                const masked_read_seq = c.read_seq &
                    comptime std.math.shl(u64, std.math.maxInt(u64), 8 * P.record_iv_length);
                const nonce: [P.AEAD.nonce_length]u8 = nonce: {
                    const V = @Vector(P.AEAD.nonce_length, u8);
                    const pad: [P.AEAD.nonce_length - 8]u8 = @splat(0);
                    const operand: V = pad ++ @as([8]u8, @bitCast(@byteSwap(masked_read_seq)));
                    break :nonce @as(V, pv.server_write_IV ++ record_iv) ^ operand;
                };
                const ciphertext = input.take(message_len) catch unreachable; // 已窥视
                const auth_tag = (input.takeArray(P.mac_length) catch unreachable).*; // 已窥视
                rebase(r, ciphertext.len);
                const cleartext = r.buffer[r.end..][0..ciphertext.len];
                P.AEAD.decrypt(cleartext, ciphertext, auth_tag, ad, nonce, pv.server_write_key) catch
                    return failRead(c, error.TlsBadRecordMac);
                break :cleartext .{ cleartext.len, ct };
            },
            else => unreachable,
        },
    };
    const cleartext = r.buffer[r.end..][0..cleartext_len];
    c.read_seq = std.math.add(u64, c.read_seq, 1) catch return failRead(c, error.TlsSequenceOverflow);
    switch (inner_ct) {
        .alert => {
            if (cleartext.len != 2) return failRead(c, error.TlsDecodeError);
            const alert: tls.Alert = .{
                .level = @fromBackingInt(@intCast(cleartext[0])),
                .description = @fromBackingInt(@intCast(cleartext[1])),
            };
            switch (alert.description) {
                .close_notify => {
                    c.received_close_notify = true;
                    return 0;
                },
                .user_canceled => {
                    // TODO 处理服务端闭包
                    return failRead(c, error.TlsUnexpectedMessage);
                },
                else => {
                    c.alert = alert;
                    return failRead(c, error.TlsAlert);
                },
            }
        },
        .handshake => {
            var ct_i: usize = 0;
            while (true) {
                const handshake_type: tls.HandshakeType = @fromBackingInt(@intCast(cleartext[ct_i]));
                ct_i += 1;
                const handshake_len = mem.readInt(u24, cleartext[ct_i..][0..3], .big);
                ct_i += 3;
                const next_handshake_i = ct_i + handshake_len;
                if (next_handshake_i > cleartext.len) return failRead(c, error.TlsBadLength);
                const handshake = cleartext[ct_i..next_handshake_i];
                switch (handshake_type) {
                    .new_session_ticket => {
                        // 此客户端实现忽略新会话票证。
                    },
                    .key_update => {
                        if (handshake.len != 1) return failRead(c, error.TlsDecodeError);
                        switch (c.application_cipher) {
                            inline else => |*p| {
                                const pv = &p.tls_1_3;
                                const P = @TypeOf(p.*);
                                const server_secret = hkdfExpandLabel(P.Hkdf, pv.server_secret, "traffic upd", "", P.Hash.digest_length);
                                if (c.ssl_key_log) |key_log| logSecrets(key_log.writer, .{
                                    .counter = key_log.serverCounter(),
                                    .client_random = &key_log.client_random,
                                }, .{
                                    .SERVER_TRAFFIC_SECRET = &server_secret,
                                });
                                pv.server_secret = server_secret;
                                pv.server_key = hkdfExpandLabel(P.Hkdf, server_secret, "key", "", P.AEAD.key_length);
                                pv.server_iv = hkdfExpandLabel(P.Hkdf, server_secret, "iv", "", P.AEAD.nonce_length);
                            },
                        }
                        c.read_seq = 0;

                        switch (@as(tls.KeyUpdateRequest, @fromBackingInt(@intCast(handshake[0])))) {
                            .update_requested => {
                                switch (c.application_cipher) {
                                    inline else => |*p| {
                                        const pv = &p.tls_1_3;
                                        const P = @TypeOf(p.*);
                                        const client_secret = hkdfExpandLabel(P.Hkdf, pv.client_secret, "traffic upd", "", P.Hash.digest_length);
                                        if (c.ssl_key_log) |key_log| logSecrets(key_log.writer, .{
                                            .counter = key_log.clientCounter(),
                                            .client_random = &key_log.client_random,
                                        }, .{
                                            .CLIENT_TRAFFIC_SECRET = &client_secret,
                                        });
                                        pv.client_secret = client_secret;
                                        pv.client_key = hkdfExpandLabel(P.Hkdf, client_secret, "key", "", P.AEAD.key_length);
                                        pv.client_iv = hkdfExpandLabel(P.Hkdf, client_secret, "iv", "", P.AEAD.nonce_length);
                                    },
                                }
                                c.write_seq = 0;
                            },
                            .update_not_requested => {},
                            _ => return failRead(c, error.TlsIllegalParameter),
                        }
                    },
                    else => return failRead(c, error.TlsUnexpectedMessage),
                }
                ct_i = next_handshake_i;
                if (ct_i >= cleartext.len) break;
            }
            return 0;
        },
        .application_data => {
            r.end += cleartext.len;
            return 0;
        },
        else => return failRead(c, error.TlsUnexpectedMessage),
    }
}

fn rebase(r: *Reader, capacity: usize) void {
    if (r.buffer.len - r.end >= capacity) return;
    const data = r.buffer[r.seek..r.end];
    @memmove(r.buffer[0..data.len], data);
    r.seek = 0;
    r.end = data.len;
    assert(r.buffer.len - r.end >= capacity);
}

fn failRead(c: *Client, err: ReadError) error{ReadFailed} {
    c.read_err = err;
    return error.ReadFailed;
}

fn logSecrets(w: *Writer, context: anytype, secrets: anytype) void {
    inline for (@typeInfo(@TypeOf(secrets)).@"struct".field_names) |field_name| w.print("{s}" ++
        (if (@hasField(@TypeOf(context), "counter")) "_{d}" else "") ++ " {x} {x}\n", .{field_name} ++
        (if (@hasField(@TypeOf(context), "counter")) .{context.counter} else .{}) ++ .{
        context.client_random,
        @field(secrets, field_name),
    }) catch {};
}

fn big(x: anytype) @TypeOf(x) {
    return switch (native_endian) {
        .big => x,
        .little => @byteSwap(x),
    };
}

const KeyShare = struct {
    ml_kem768_kp: crypto.kem.ml_kem.MLKem768.KeyPair,
    secp256r1_kp: crypto.sign.ecdsa.EcdsaP256Sha256.KeyPair,
    secp384r1_kp: crypto.sign.ecdsa.EcdsaP384Sha384.KeyPair,
    x25519_kp: crypto.dh.X25519.KeyPair,
    sk_buf: [sk_max_len]u8,
    sk_len: std.math.IntFittingRange(0, sk_max_len),

    const sk_max_len = @max(
        crypto.dh.X25519.shared_length + crypto.kem.ml_kem.MLKem768.shared_length,
        crypto.ecc.P256.scalar.encoded_length,
        crypto.ecc.P384.scalar.encoded_length,
        crypto.dh.X25519.shared_length,
    );

    fn init(seed: *const [176]u8) error{IdentityElement}!KeyShare {
        return .{
            .ml_kem768_kp = try .generateDeterministic(seed[0..64].*),
            .secp256r1_kp = try .generateDeterministic(seed[64..96].*),
            .secp384r1_kp = try .generateDeterministic(seed[96..144].*),
            .x25519_kp = .generateDeterministic(seed[144..176].*),
            .sk_buf = undefined,
            .sk_len = 0,
        };
    }

    fn exchange(
        ks: *KeyShare,
        named_group: tls.NamedGroup,
        server_pub_key: []const u8,
    ) error{ TlsIllegalParameter, TlsDecryptFailure }!void {
        switch (named_group) {
            .x25519_ml_kem768 => {
                const hksl = crypto.kem.ml_kem.MLKem768.ciphertext_length;
                const xksl = hksl + crypto.dh.X25519.public_length;
                if (server_pub_key.len != xksl) return error.TlsIllegalParameter;

                const hsk = ks.ml_kem768_kp.secret_key.decaps(server_pub_key[0..hksl]) catch
                    return error.TlsDecryptFailure;
                const xsk = crypto.dh.X25519.scalarmult(ks.x25519_kp.secret_key, server_pub_key[hksl..xksl].*) catch
                    return error.TlsDecryptFailure;
                @memcpy(ks.sk_buf[0..hsk.len], &hsk);
                @memcpy(ks.sk_buf[hsk.len..][0..xsk.len], &xsk);
                ks.sk_len = hsk.len + xsk.len;
            },
            .secp256r1 => {
                const PublicKey = crypto.sign.ecdsa.EcdsaP256Sha256.PublicKey;
                const pk = PublicKey.fromSec1(server_pub_key) catch return error.TlsDecryptFailure;
                const mul = pk.p.mulPublic(ks.secp256r1_kp.secret_key.bytes, .big) catch
                    return error.TlsDecryptFailure;
                const sk = mul.affineCoordinates().x.toBytes(.big);
                @memcpy(ks.sk_buf[0..sk.len], &sk);
                ks.sk_len = sk.len;
            },
            .secp384r1 => {
                const PublicKey = crypto.sign.ecdsa.EcdsaP384Sha384.PublicKey;
                const pk = PublicKey.fromSec1(server_pub_key) catch return error.TlsDecryptFailure;
                const mul = pk.p.mulPublic(ks.secp384r1_kp.secret_key.bytes, .big) catch
                    return error.TlsDecryptFailure;
                const sk = mul.affineCoordinates().x.toBytes(.big);
                @memcpy(ks.sk_buf[0..sk.len], &sk);
                ks.sk_len = sk.len;
            },
            .x25519 => {
                const ksl = crypto.dh.X25519.public_length;
                if (server_pub_key.len != ksl) return error.TlsIllegalParameter;
                const sk = crypto.dh.X25519.scalarmult(ks.x25519_kp.secret_key, server_pub_key[0..ksl].*) catch
                    return error.TlsDecryptFailure;
                @memcpy(ks.sk_buf[0..sk.len], &sk);
                ks.sk_len = sk.len;
            },
            else => return error.TlsIllegalParameter,
        }
    }

    fn getSharedSecret(ks: *const KeyShare) ?[]const u8 {
        return if (ks.sk_len > 0) ks.sk_buf[0..ks.sk_len] else null;
    }
};

fn SchemeEcdsa(comptime scheme: tls.SignatureScheme) type {
    return switch (scheme) {
        .ecdsa_secp256r1_sha256 => crypto.sign.ecdsa.EcdsaP256Sha256,
        .ecdsa_secp384r1_sha384 => crypto.sign.ecdsa.EcdsaP384Sha384,
        else => @compileError("bad scheme"),
    };
}

fn SchemeRsa(comptime scheme: tls.SignatureScheme) type {
    return switch (scheme) {
        .rsa_pkcs1_sha256,
        .rsa_pkcs1_sha384,
        .rsa_pkcs1_sha512,
        .rsa_pkcs1_sha1,
        => Certificate.rsa.PKCS1v1_5Signature,
        .rsa_pss_rsae_sha256,
        .rsa_pss_rsae_sha384,
        .rsa_pss_rsae_sha512,
        .rsa_pss_pss_sha256,
        .rsa_pss_pss_sha384,
        .rsa_pss_pss_sha512,
        => Certificate.rsa.PSSSignature,
        else => @compileError("bad scheme"),
    };
}

fn SchemeEddsa(comptime scheme: tls.SignatureScheme) type {
    return switch (scheme) {
        .ed25519 => crypto.sign.Ed25519,
        else => @compileError("bad scheme"),
    };
}

fn SchemeHash(comptime scheme: tls.SignatureScheme) type {
    return switch (scheme) {
        .rsa_pkcs1_sha256,
        .ecdsa_secp256r1_sha256,
        .rsa_pss_rsae_sha256,
        .rsa_pss_pss_sha256,
        => crypto.hash.sha2.Sha256,
        .rsa_pkcs1_sha384,
        .ecdsa_secp384r1_sha384,
        .rsa_pss_rsae_sha384,
        .rsa_pss_pss_sha384,
        => crypto.hash.sha2.Sha384,
        .rsa_pkcs1_sha512,
        .ecdsa_secp521r1_sha512,
        .rsa_pss_rsae_sha512,
        .rsa_pss_pss_sha512,
        => crypto.hash.sha2.Sha512,
        .rsa_pkcs1_sha1,
        .ecdsa_sha1,
        => crypto.hash.Sha1,
        else => @compileError("bad scheme"),
    };
}

const CertificatePublicKey = struct {
    algo: Certificate.AlgorithmCategory,
    buf: [600]u8,
    len: u16,

    fn init(
        cert_pub_key: *CertificatePublicKey,
        algo: Certificate.AlgorithmCategory,
        pub_key: []const u8,
    ) error{CertificatePublicKeyInvalid}!void {
        if (pub_key.len > cert_pub_key.buf.len) return error.CertificatePublicKeyInvalid;
        cert_pub_key.algo = algo;
        @memcpy(cert_pub_key.buf[0..pub_key.len], pub_key);
        cert_pub_key.len = @intCast(pub_key.len);
    }

    const VerifyError = error{ TlsDecodeError, TlsBadSignatureScheme, InvalidEncoding } ||
        // ecdsa
        crypto.errors.EncodingError ||
        crypto.errors.NotSquareError ||
        crypto.errors.NonCanonicalError ||
        SchemeEcdsa(.ecdsa_secp256r1_sha256).Signature.VerifyError ||
        SchemeEcdsa(.ecdsa_secp384r1_sha384).Signature.VerifyError ||
        // rsa
        error{TlsBadRsaSignatureBitCount} ||
        Certificate.rsa.PublicKey.ParseDerError ||
        Certificate.rsa.PublicKey.FromBytesError ||
        Certificate.rsa.PSSSignature.VerifyError ||
        Certificate.rsa.PKCS1v1_5Signature.VerifyError ||
        // eddsa
        SchemeEddsa(.ed25519).Signature.VerifyError;

    fn verifySignature(
        cert_pub_key: *const CertificatePublicKey,
        sigd: *tls.Decoder,
        msg: []const []const u8,
    ) VerifyError!void {
        const pub_key = cert_pub_key.buf[0..cert_pub_key.len];

        try sigd.ensure(2 + 2);
        const scheme = sigd.decode(tls.SignatureScheme);
        const sig_len = sigd.decode(u16);
        try sigd.ensure(sig_len);
        const encoded_sig = sigd.slice(sig_len);

        if (cert_pub_key.algo != @as(Certificate.AlgorithmCategory, switch (scheme) {
            .ecdsa_secp256r1_sha256,
            .ecdsa_secp384r1_sha384,
            => .X9_62_id_ecPublicKey,
            .rsa_pkcs1_sha256,
            .rsa_pkcs1_sha384,
            .rsa_pkcs1_sha512,
            .rsa_pss_rsae_sha256,
            .rsa_pss_rsae_sha384,
            .rsa_pss_rsae_sha512,
            .rsa_pkcs1_sha1,
            => .rsaEncryption,
            .rsa_pss_pss_sha256,
            .rsa_pss_pss_sha384,
            .rsa_pss_pss_sha512,
            => .rsassa_pss,
            else => return error.TlsBadSignatureScheme,
        })) return error.TlsBadSignatureScheme;

        switch (scheme) {
            inline .ecdsa_secp256r1_sha256,
            .ecdsa_secp384r1_sha384,
            => |comptime_scheme| {
                const Ecdsa = SchemeEcdsa(comptime_scheme);
                const sig = try Ecdsa.Signature.fromDer(encoded_sig);
                const key = try Ecdsa.PublicKey.fromSec1(pub_key);
                var ver = try sig.verifier(key);
                for (msg) |part| ver.update(part);
                try ver.verify();
            },
            inline .rsa_pkcs1_sha256,
            .rsa_pkcs1_sha384,
            .rsa_pkcs1_sha512,
            .rsa_pss_rsae_sha256,
            .rsa_pss_rsae_sha384,
            .rsa_pss_rsae_sha512,
            .rsa_pss_pss_sha256,
            .rsa_pss_pss_sha384,
            .rsa_pss_pss_sha512,
            .rsa_pkcs1_sha1,
            => |comptime_scheme| {
                const RsaSignature = SchemeRsa(comptime_scheme);
                const Hash = SchemeHash(comptime_scheme);
                const PublicKey = Certificate.rsa.PublicKey;
                const components = try PublicKey.parseDer(pub_key);
                const exponent = components.exponent;
                const modulus = components.modulus;
                switch (modulus.len) {
                    inline 128, 256, 384, 512 => |modulus_len| {
                        const key: PublicKey = try .fromBytes(exponent, modulus);
                        const sig = RsaSignature.fromBytes(modulus_len, encoded_sig);
                        try RsaSignature.concatVerify(modulus_len, &sig, msg, key, Hash);
                    },
                    else => return error.TlsBadRsaSignatureBitCount,
                }
            },
            inline .ed25519 => |comptime_scheme| {
                const Eddsa = SchemeEddsa(comptime_scheme);
                if (encoded_sig.len != Eddsa.Signature.encoded_length) return error.InvalidEncoding;
                const sig = Eddsa.Signature.fromBytes(encoded_sig[0..Eddsa.Signature.encoded_length].*);
                if (pub_key.len != Eddsa.PublicKey.encoded_length) return error.InvalidEncoding;
                const key = try Eddsa.PublicKey.fromBytes(pub_key[0..Eddsa.PublicKey.encoded_length].*);
                var ver = try sig.verifier(key);
                for (msg) |part| ver.update(part);
                try ver.verify();
            },
            else => unreachable,
        }
    }
};

fn tryDownloadRootCert(chain: *Certificate.Chain, options: *const Options) !void {
    if (Certificate.Chain != void) switch (options.ca) {
        else => {},
        .bundle => |ca| {
            chain.verify(options.realtime_now) catch |err| switch (err) {
                error.Unexpected => return error.TlsCertificateNotVerified,
                else => |e| return e,
            };
            var bundle: Certificate.Bundle = .empty;
            defer bundle.deinit(ca.gpa);
            if (bundle.rescan(ca.gpa, ca.io, options.realtime_now)) {
                try ca.lock.lock(ca.io);
                defer ca.lock.unlock(ca.io);
                std.mem.swap(Certificate.Bundle, ca.bundle, &bundle);
            } else |err| switch (err) {
                error.Canceled => |e| return e,
                else => {},
            }
            return; // 操作系统已代为验证证书
        },
    };
    return error.TlsCertificateNotVerified;
}

/// 此处优先级顺序的选择依据是 Zig 标准库提供的
/// 密码算法以及各算法的速度。下方给出
/// 这些算法相对性能的若干测量数据。
///
/// 使用 0.11.0-dev.810+c2f5848fe 测量,
/// 平台为 x86_64-linux,Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz:
/// zig run .lib/std/crypto/benchmark.zig -OReleaseFast
///       aegis-128l:      15382 MiB/s
///        aegis-256:       9553 MiB/s
///       aes128-gcm:       3721 MiB/s
///       aes256-gcm:       3010 MiB/s
/// chacha20Poly1305:        597 MiB/s
///
/// 使用 0.11.0-dev.810+c2f5848fe 测量,
/// 平台为 x86_64-linux,Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz:
/// zig run .lib/std/crypto/benchmark.zig -OReleaseFast -mcpu=baseline
///       aegis-128l:        629 MiB/s
/// chacha20Poly1305:        529 MiB/s
///        aegis-256:        461 MiB/s
///       aes128-gcm:        138 MiB/s
///       aes256-gcm:        120 MiB/s
const cipher_suites = if (crypto.core.aes.has_hardware_support)
    array(u16, tls.CipherSuite, .{
        .AEGIS_128L_SHA256,
        .AEGIS_256_SHA512,
        .AES_128_GCM_SHA256,
        .ECDHE_RSA_WITH_AES_128_GCM_SHA256,
        .AES_256_GCM_SHA384,
        .ECDHE_RSA_WITH_AES_256_GCM_SHA384,
        .CHACHA20_POLY1305_SHA256,
        .ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
    })
else
    array(u16, tls.CipherSuite, .{
        .CHACHA20_POLY1305_SHA256,
        .ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
        .AEGIS_128L_SHA256,
        .AEGIS_256_SHA512,
        .AES_128_GCM_SHA256,
        .ECDHE_RSA_WITH_AES_128_GCM_SHA256,
        .AES_256_GCM_SHA384,
        .ECDHE_RSA_WITH_AES_256_GCM_SHA384,
    });

fn testReadError(input_buf: []const u8, tls_version: tls.ProtocolVersion, cipher: tls.ApplicationCipher) ReadError {
    var input_reader: Reader = .fixed(input_buf);
    var read_buf: [tls.max_ciphertext_record_len]u8 = undefined;
    var c: Client = .{
        .input = &input_reader,
        .reader = .{
            .buffer = &read_buf,
            .vtable = &.{ .stream = stream, .readVec = readVec },
            .seek = 0,
            .end = 0,
        },
        .output = undefined,
        .writer = undefined,
        .tls_version = tls_version,
        .read_seq = 0,
        .write_seq = 0,
        .received_close_notify = false,
        .allow_truncation_attacks = false,
        .application_cipher = cipher,
        .ssl_key_log = null,
    };
    var w: Writer = .failing;
    std.testing.expectError(error.ReadFailed, c.reader.stream(&w, .unlimited)) catch
        @panic("expected ReadFailed");
    return c.read_err.?;
}

test "empty inner plaintext" {
    const AEAD = crypto.aead.chacha_poly.ChaCha20Poly1305;
    const key: [AEAD.key_length]u8 = @splat(0);
    const iv: [AEAD.nonce_length]u8 = @splat(0);

    const plaintext = [1]u8{0x00};
    var ciphertext: [plaintext.len]u8 = undefined;
    var tag: [AEAD.tag_length]u8 = undefined;
    const content_len: u16 = plaintext.len + AEAD.tag_length;
    const record_header = [_]u8{ 0x17, 0x03, 0x03 } ++ mem.toBytes(big(content_len));
    AEAD.encrypt(&ciphertext, &tag, &plaintext, &record_header, iv, key);

    try std.testing.expectEqual(error.TlsDecodeError, testReadError(
        &record_header ++ ciphertext ++ tag,
        .tls_1_3,
        .{ .CHACHA20_POLY1305_SHA256 = .{ .tls_1_3 = .{
            .server_key = key,
            .server_iv = iv,
            .client_secret = undefined,
            .server_secret = undefined,
            .client_key = undefined,
            .client_iv = undefined,
        } } },
    ));
}

test "record shorter than tag" {
    const AEAD = crypto.aead.chacha_poly.ChaCha20Poly1305;
    const record_len: u16 = AEAD.tag_length - 1;
    const header = [_]u8{ 0x17, 0x03, 0x03 } ++ mem.toBytes(big(record_len));
    const wire = header ++ @as([record_len]u8, @splat(0));

    try std.testing.expectEqual(error.TlsRecordOverflow, testReadError(
        &wire,
        .tls_1_3,
        .{ .CHACHA20_POLY1305_SHA256 = .{ .tls_1_3 = .{
            .server_key = undefined,
            .server_iv = undefined,
            .client_secret = undefined,
            .server_secret = undefined,
            .client_key = undefined,
            .client_iv = undefined,
        } } },
    ));
}

test "TLS 1.2 record shorter than IV plus tag" {
    const P = tls.ApplicationCipherT(crypto.aead.aes_gcm.Aes128Gcm, crypto.hash.sha2.Sha256, 8);
    const record_len: u16 = P.record_iv_length + P.mac_length - 1;
    const header = [_]u8{ 0x17, 0x03, 0x03 } ++ mem.toBytes(big(record_len));

    try std.testing.expectEqual(error.TlsRecordOverflow, testReadError(
        &(header ++ @as([record_len]u8, @splat(0))),
        .tls_1_2,
        .{ .AES_128_GCM_SHA256 = .{ .tls_1_2 = mem.zeroes(P.Tls_1_2) } },
    ));
}

test "zero-length key_update body" {
    const Chacha = crypto.aead.chacha_poly.ChaCha20Poly1305;
    const plaintext = [_]u8{ 0x18, 0x00, 0x00, 0x00, 0x16 };
    const header = [_]u8{ 0x17, 0x03, 0x03 } ++ mem.toBytes(big(@as(u16, plaintext.len + Chacha.tag_length)));
    var ct: [plaintext.len]u8 = undefined;
    var tag: [Chacha.tag_length]u8 = undefined;
    Chacha.encrypt(&ct, &tag, &plaintext, &header, @splat(0), @splat(0));
    const wire = header ++ ct ++ tag;
    try std.testing.expectEqual(error.TlsDecodeError, testReadError(
        &wire,
        .tls_1_3,
        .{ .CHACHA20_POLY1305_SHA256 = .{ .tls_1_3 = .{
            .server_key = @splat(0),
            .server_iv = @splat(0),
            .client_secret = undefined,
            .server_secret = undefined,
            .client_key = undefined,
            .client_iv = undefined,
        } } },
    ));
}