TLS and Trust

TLS 与信任

HTTPS 默认 校验证书（CertPolicy::Verify）。库不内置系统 CA：信任锚、中间 CA、SPKI pin、撤销证据均由调用方经 CertificateStore / 相关 API 提供。密码学走内核 CNG/BCrypt（及必要的内核内软件实现），不用 SChannel。

版本路径

• 允许范围内优先 TLS 1.3（纯 1.3 ClientHello）；否则直接 TLS 1.2。
• 无握手内自动降级。若对端证明只能 1.2，失败可分类为 VersionNegotiation，由 session 显式重连 1.2。
• 带 TLS 1.3→1.2 降级哨兵的 ServerHello 视为攻击，硬失败。
• 默认 MinVersion=Tls12、MaxVersion=Tls13；可收紧为仅 1.3。

策略档位

TlsPolicy.Profile：

Profile	含义
ModernDefault（默认）	现代套件/群/签名；兼容开关若误开 → STATUS_INVALID_PARAMETER
CompatibilityExplicit	允许分别打开 RSA-kx、CBC、SHA-1 签名、真重协商

默认关闭、需显式开启：TLS 1.2 RSA-kx / CBC / SHA-1 / 重协商、post-handshake client auth、RequireRevocationCheck。开启方式见 能力边界。

TLS 1.2 强制：Extended Master Secret、安全重协商指示；CBC 必须 Encrypt-then-MAC。

证书与主机名

校验在扩展内核栈上运行。要点：

• 链长度有界；解析期拒绝重复扩展与未知 critical 扩展。
• 主机名：SAN dNSName 通配仅限单个最左标签；IP literal 只匹配 iPAddress SAN；域名匹配从不回退 CN（CN 不参与主机名等价判定）。
• SPKI pin：已配置 pin 的主机强校验叶 SPKI；未配置 pin 的主机 fail-open。
• 撤销：纯离线、证据驱动（stapled OCSP、静态条目、provider 回调的 OCSP/CRL DER）。库从不在线抓取。RequireRevocationCheck / 强模式查不到或证据无效 → fail-closed（STATUS_TRUST_FAILURE）。

// 信任锚 + 可选 pin（示意）
wknet::http::CertificateStoreOptions o = {};
// o.TrustAnchors / Pins / ... 由调用方填充
wknet::http::CertificateStore* store = nullptr;
NTSTATUS st = wknet::http::CertificateStoreCreate(&o, &store);
config.Tls.Store = store;
config.Tls.Certificate = wknet::http::CertPolicy::Verify;
// SessionClose 后 CertificateStoreClose(store);

生产环境严禁 CertPolicy::NoVerify（跳过链与主机校验）。NoVerify 响应默认也不参与 H3 Alt-Svc 学习。

mTLS

TlsClientCredential 携带证书链与 Sign 回调。私钥留在调用方，库内只通过回调完成签名。

会话恢复

• 恢复票据绑定 policy 身份、SNI、ALPN、cipher、版本（各版本缓存条数有上限）。
• TLS 1.3 0-RTT early data 仅存在于内部连接选项，未暴露在 wknet::http::TlsConfig / SendOptions；产品 HTTP 路径不能按公共字段开启。

与 HTTP 层的交界

场景	行为
默认 HTTPS	TCP TLS + HTTP/1.1 或 ALPN h2
H3 Auto	仅已认证 TLS 响应可写入 Alt-Svc；SNI/证书/authority 绑定 origin
代理 HTTPS	CONNECT 后再 TLS 到目标
WebSocket wss	同一 TLS 配置与校验模型
HTTPS→HTTP redirect	默认拒绝降级

常见失败码：STATUS_TRUST_FAILURE（链/主机/pin/锚/撤销）、STATUS_NOT_SUPPORTED（策略/版本/0-RTT）、STATUS_INVALID_NETWORK_RESPONSE（记录/握手解码）。更多见 错误码与 FAQ。

---

English

TLS & Trust

HTTPS verifies certificates by default (CertPolicy::Verify). The library does not ship system CAs: trust anchors, intermediate CAs, SPKI pins, and revocation evidence are supplied by the caller through CertificateStore and related APIs. Cryptography uses kernel CNG/BCrypt (plus required in-kernel software fills) — not SChannel.

Version path

• Prefer TLS 1.3 when in range (pure 1.3 ClientHello); otherwise speak TLS 1.2 directly.
• No in-handshake automatic downgrade. If the peer proves it can only do 1.2, the failure may be classified as VersionNegotiation so session can explicitly reconnect at 1.2.
• A ServerHello carrying a TLS 1.3→1.2 downgrade sentinel is treated as an attack and hard-fails.
• Defaults: MinVersion=Tls12, MaxVersion=Tls13; may be tightened to TLS 1.3 only.

Policy profile

TlsPolicy.Profile:

Profile	Meaning
ModernDefault (default)	Modern ciphers/groups/signatures; accidental compatibility flags → STATUS_INVALID_PARAMETER
CompatibilityExplicit	Allows RSA-kx, CBC, SHA-1 signatures, and true renegotiation individually

Default-off opt-ins: TLS 1.2 RSA-kx / CBC / SHA-1 / renegotiation, post-handshake client auth, and RequireRevocationCheck. How to enable: Capability matrix · Default-off.

TLS 1.2 hard requirements: Extended Master Secret and secure renegotiation indication; CBC requires Encrypt-then-MAC.

Certificates and hostnames

Validation runs on an expanded kernel stack. Highlights:

• Bounded chain length; parse-time rejection of duplicate and unknown-critical extensions.
• Hostnames: SAN dNSName wildcards are a single leftmost label only; IP literals match iPAddress SAN only; DNS matching never falls back to CN (CN is not used for hostname equivalence).
• SPKI pins: hosts with configured pins strongly check the leaf SPKI; unpinned hosts fail open.
• Revocation: offline and evidence-driven (stapled OCSP, static entries, provider-returned OCSP/CRL DER). The library never fetches online. Under RequireRevocationCheck / hard modes, missing or invalid evidence fails closed (STATUS_TRUST_FAILURE).

// Trust anchors + optional pins (sketch)
wknet::http::CertificateStoreOptions o = {};
// fill o.TrustAnchors / Pins / ...
wknet::http::CertificateStore* store = nullptr;
NTSTATUS st = wknet::http::CertificateStoreCreate(&o, &store);
config.Tls.Store = store;
config.Tls.Certificate = wknet::http::CertPolicy::Verify;
// after SessionClose: CertificateStoreClose(store);

Never use CertPolicy::NoVerify in production (skips chain and hostname checks). NoVerify responses also do not participate in H3 Alt-Svc learning by default.

mTLS

TlsClientCredential carries the certificate chain and a Sign callback. Private keys remain with the caller; the library only completes signatures through the callback.

Session resumption

• Resumption tickets bind policy identity, SNI, ALPN, cipher, and version (per-version cache caps apply).
• TLS 1.3 0-RTT early data exists only on internal connection options and is not exposed on wknet::http::TlsConfig / SendOptions; the product HTTP path cannot enable it through public fields.

Boundary with HTTP

Scenario	Behavior
Default HTTPS	TCP TLS + HTTP/1.1 or ALPN h2
H3 Auto	Only authenticated TLS responses may write Alt-Svc; SNI/cert/authority stay origin-bound
Proxied HTTPS	CONNECT, then TLS to the target
WebSocket wss	Same TLS config and validation model
HTTPS→HTTP redirect	Rejected by default

Common failures: STATUS_TRUST_FAILURE (chain/host/pin/anchor/revocation), STATUS_NOT_SUPPORTED (policy/version/0-RTT), STATUS_INVALID_NETWORK_RESPONSE (record/handshake decode). More: Errors & FAQ.