Encoding and Crypto

编码与密码学

讲 Content-Encoding / Transfer-Encoding 的解码策略，以及公开的 codec / crypto 面。产品路径一般经 HTTP/TLS 间接用到；直接调用见 Codec 与 Crypto API。

结论

主题	行为
Content-Encoding	gzip deflate br compress zstd dcz aes128gcm exi pack200-gzip identity
链长	最多 2 级；反序解码
解压炸弹	单级膨胀比 ≤ 1024（WKNET_HARD_MAX_DECODE_EXPANSION_RATIO）；总量跟响应/调用方容量
Transfer-Encoding	chunked/gzip/deflate/compress（≤4）；br 仅 CE 不支持 TE
EXI	无外部 Schema 流 → Infoset 等价 XML；外部 Schema/strict → STATUS_NOT_SUPPORTED
Pack200	Java 5–8 稳定格式 → 语义等价 JAR
Crypto	CNG 优先；ChaCha/CCM/X25519/X448/FFDHE/Ed* 为内核内软件实现

Content-Encoding

无调用方 Accept-Encoding 时，引擎注入默认
gzip, deflate, br, zstd, identity（deflate 运行时不可用则 br, identity）。
SendOptions.AcceptEncodingPreferences 可带 qvalue，并驱动响应 CE fail-closed 校验（含 identity;q=0 / *;q=0）。

coding	要点
gzip	RFC 1952；校验头 CRC16、尾 CRC32、ISIZE
deflate	zlib 自动识别 + Adler-32；裸 DEFLATE 走内核路径并运行时探测 DeflateRuntimeAvailable
br	内置 Brotli
compress	完整 LZW（.Z）
zstd	内置 Zstandard
dcz	调用方提供 zstd 字典；缺字典 fail-closed
aes128gcm	RFC 8188 keying material；缺 key 或认证失败 fail-closed
exi	见下
pack200-gzip	见下
identity	跳过

• 未知 coding → STATUS_NOT_SUPPORTED。
• 字典 / AES keying material：经 CodingDecodeMaterials 或 wknet::codec::DecodeMaterials（静态表或回调）提供。
• 公开解码入口：wknet::codec::DecodeOne / DecodeChain / DecodeExi / DecodePack200（include/wknet/codec/Codec.h）。

解压炸弹

• decoded aggregate 跟随响应缓冲或调用方 MaxResponseBytes / 目标容量。
• 单级膨胀比 ≤ 1024（WKNET_HARD_MAX_DECODE_EXPANSION_RATIO）；超限 → STATUS_INVALID_NETWORK_RESPONSE。
  该上限要覆盖高度可压缩的合法响应（例如 echo 服务把大请求体重编码为 JSON 再 gzip，膨胀可达数百倍），绝对体积仍由 MaxResponseBytes 约束。
• WebSocket permessage-deflate 另受 MaxMessageBytes 与同类膨胀约束。

EXI 边界

• 范围：W3C EXI 1.0 Second Edition 无外部 Schema 流。
• 支持：四种 alignment、Options、保真项、内建 XML Schema 类型、xsi:type / xsi:nil。
• 输出：Infoset 等价 XML。
• 不支持 / 拒绝：外部 Schema、strict grammar → STATUS_NOT_SUPPORTED。

Pack200 边界

• 范围：Java 5–8 稳定格式 150.7 / 160.1 / 170.1 / 171.0。
• 输入：裸 Pack200 或 gzip 包装；多 segment、class/file/bytecode、自定义 attribute layout、overflow index、常量池与 BCI relocation。
• 输出：语义等价 JAR。
• 专项测试使用离线语料并校验 SHA256SUMS 与 provenance。

Transfer-Encoding

• 识别 chunked / gzip / deflate / compress，最多 4 级；反序解码。
• identity → STATUS_INVALID_NETWORK_RESPONSE。
• br → STATUS_NOT_SUPPORTED（br 只作为 Content-Encoding）。
• 仅最外层 chunked 收 trailer；重复 chunked、带参数 token → 非法。
• 请求侧用户手写 Transfer-Encoding / TE 一律拒绝；framing 由库生成。

公开 codec 面

命名空间 wknet::codec：

• Coding 枚举与上表 CE 对齐（含 DictionaryCompressedZstd / Aes128Gcm / Exi / Pack200Gzip）。
• ExternalMaterial：字典与 AES-128-GCM keying material。
• DecodeOne：单 coding；DecodeChain：按 CE 列表反序。
• DecodeExi / DecodePack200：专项解码。
• DeflateRuntimeAvailable()：探测内核 deflate 路径是否可用。

HTTP 层等价类型为 ContentCoding / AcceptCoding / CodingDecodeMaterials（Types.h），由会话在响应路径上调用同一解码逻辑。

公开 crypto 面与 CNG vs 软件

命名空间 wknet::crypto（头文件在 include/wknet/crypto/）。优先内核态 CNG/BCrypt；下列原语为内核内软件补齐。

原语	实现
SHA-1/256/384/512、HMAC、HKDF	CNG（HKDF 基于 HMAC；Expand 限 out≤digest×255）
AES-GCM	CNG（tag 16；key 16/32）
ChaCha20-Poly1305	软件（解密前常量时间验 tag）
AES-CCM / CCM8	软件
NIST P-256/384/521 ECDH/ECDSA	CNG
X25519 / X448	软件 Montgomery ladder
FFDHE 2048–8192	软件模幂（RFC 7919；公钥范围校验）
RSA-PKCS1 / RSA-PSS 验签	CNG（PSS salt=摘要长；最小模数 2048）
Ed25519 / Ed448 验签	软件 PureEdDSA（完整消息，非预哈希 digest）

公开入口摘要：

• Aead：Encrypt / Decrypt（Aead.h）
• KeyExchange：密钥对与共享密钥（KeyExchange.h）
• Ed25519Verify / Ed448Verify
• CngProviderCache：会话级预打开 BCrypt 算法句柄；软件路径不使用缓存
• TlsClientCredential：mTLS 签名回调；私钥留在调用方

硬化惯例：密钥与中间量 RtlSecureZeroMemory；FFDHE 拒绝非法 y；SPKI/导入路径强制 RSA 下限。

与协议栈的关系

• HTTP 响应 CE 失败 → 请求失败（fail-closed），不会静默当 identity 用。
• TLS 记录层与证书路径使用同一 crypto 原语；信任锚与 pin 由调用方提供（见 TLS 文档）。
• 不把 WinHTTP / WinINet / SChannel 作为内核主路径。
• 支持范围见 能力边界。

---

English

Encoding & Crypto

Decode policy for Content-Encoding / Transfer-Encoding, plus the public codec / crypto surface. Product paths usually reach these through HTTP/TLS; for direct calls see Codec & Crypto API.

Summary

Topic	Behavior
Content-Encoding	gzip deflate br compress zstd dcz aes128gcm exi pack200-gzip identity
Chain length	At most 2 codings; decoded in reverse order
Decompression bomb	Per-step expansion ≤ 1024 (WKNET_HARD_MAX_DECODE_EXPANSION_RATIO); aggregate follows response/caller capacity
Transfer-Encoding	chunked/gzip/deflate/compress (≤4); br only as Content-Encoding
EXI	Schema-less streams → Infoset-equivalent XML; external Schema/strict → STATUS_NOT_SUPPORTED
Pack200	Java 5–8 stable formats → semantically equivalent JAR
Crypto	CNG first; ChaCha/CCM/X25519/X448/FFDHE/Ed* are in-kernel software

Content-Encoding

When the caller supplies no Accept-Encoding, the engine injects
gzip, deflate, br, zstd, identity (or br, identity if deflate is unavailable at runtime).
SendOptions.AcceptEncodingPreferences may carry qvalues and drive fail-closed response CE validation (including identity;q=0 / *;q=0).

coding	Notes
gzip	RFC 1952; verifies header CRC16, trailer CRC32, ISIZE
deflate	zlib autodetection + Adler-32; raw DEFLATE uses the kernel path with DeflateRuntimeAvailable probe
br	Bundled Brotli
compress	Full LZW (.Z)
zstd	Bundled Zstandard
dcz	Caller-provided zstd dictionary; missing dictionary fails closed
aes128gcm	RFC 8188 keying material; missing key or auth failure fails closed
exi	See below
pack200-gzip	See below
identity	No-op

• Unknown coding → STATUS_NOT_SUPPORTED.
• Dictionaries / AES keying material: via CodingDecodeMaterials or wknet::codec::DecodeMaterials (static table or callback).
• Public decode entry points: wknet::codec::DecodeOne / DecodeChain / DecodeExi / DecodePack200 (include/wknet/codec/Codec.h).

Decompression bombs

• Decoded aggregate follows the response buffer or caller MaxResponseBytes / destination capacity.
• Per-step expansion ratio ≤ 1024 (WKNET_HARD_MAX_DECODE_EXPANSION_RATIO); over limit → STATUS_INVALID_NETWORK_RESPONSE.
  This ceiling must admit highly compressible legitimate responses (e.g. echo services that re-encode a large request body as JSON then gzip, expanding hundreds of times). Absolute size is still bounded by MaxResponseBytes.
• WebSocket permessage-deflate is additionally bounded by MaxMessageBytes and the same class of expansion limits.

EXI bounds

• Scope: W3C EXI 1.0 Second Edition schema-less streams.
• Supported: all four alignments, Options, fidelity features, built-in XML Schema types, xsi:type / xsi:nil.
• Output: Infoset-equivalent XML.
• Unsupported / refused: external Schema or strict grammar → STATUS_NOT_SUPPORTED.

Pack200 bounds

• Scope: Java 5–8 stable formats 150.7 / 160.1 / 170.1 / 171.0.
• Input: raw Pack200 or gzip-wrapped; multi-segment, class/file/bytecode, custom attribute layouts, overflow indexes, constant-pool and BCI relocation.
• Output: a semantically equivalent JAR.
• Dedicated tests load offline corpora and verify SHA256SUMS plus provenance.

Transfer-Encoding

• Recognizes chunked / gzip / deflate / compress, up to 4 codings; reverse-decoded.
• identity → STATUS_INVALID_NETWORK_RESPONSE.
• br → STATUS_NOT_SUPPORTED (br is Content-Encoding only).
• Only the outermost chunked layer accepts trailers; repeated chunked or parameterized tokens are illegal.
• Caller-supplied request Transfer-Encoding / TE is always rejected; framing is library-generated.

Public codec surface

Namespace wknet::codec:

• Coding enum aligns with the CE table above (including DictionaryCompressedZstd / Aes128Gcm / Exi / Pack200Gzip).
• ExternalMaterial: dictionary and AES-128-GCM keying material.
• DecodeOne: single coding; DecodeChain: reverse CE-list order.
• DecodeExi / DecodePack200: specialized decoders.
• DeflateRuntimeAvailable(): probes whether the kernel deflate path is usable.

HTTP-layer equivalents are ContentCoding / AcceptCoding / CodingDecodeMaterials (Types.h); the session invokes the same decode logic on the response path.

Public crypto surface and CNG vs software

Namespace wknet::crypto (headers under include/wknet/crypto/). Kernel CNG/BCrypt is preferred; the primitives below are filled in by in-kernel software.

Primitive	Implementation
SHA-1/256/384/512, HMAC, HKDF	CNG (HKDF on HMAC; Expand limited to out≤digest×255)
AES-GCM	CNG (tag 16; key 16/32)
ChaCha20-Poly1305	Software (constant-time tag check before decrypt)
AES-CCM / CCM8	Software
NIST P-256/384/521 ECDH/ECDSA	CNG
X25519 / X448	Software Montgomery ladder
FFDHE 2048–8192	Software modexp (RFC 7919; public-key range checks)
RSA-PKCS1 / RSA-PSS verify	CNG (PSS salt = digest length; min modulus 2048)
Ed25519 / Ed448 verify	Software PureEdDSA (full message, not a pre-hash digest)

Public entry summary:

• Aead: Encrypt / Decrypt (Aead.h)
• KeyExchange: key pairs and shared secrets (KeyExchange.h)
• Ed25519Verify / Ed448Verify
• CngProviderCache: session-scoped pre-opened BCrypt algorithm handles; software paths do not use the cache
• TlsClientCredential: mTLS sign callback; private keys remain with the caller

Hardening habits: RtlSecureZeroMemory on keys and intermediates; FFDHE rejects illegal y; SPKI/import paths enforce the RSA floor.

Relation to the stack

• Failed HTTP response CE → request failure (fail-closed); never silently treated as identity.
• The TLS record layer and certificate path use the same crypto primitives; trust anchors and pins are caller-supplied (see TLS docs).
• WinHTTP / WinINet / SChannel are not the kernel main path.
• See the capability matrix for support scope.