diff --git a/docs/features/protocols-and-certs/TLCP.md b/docs/features/protocols-and-certs/TLCP.md index 58149253..2cc459ff 100644 --- a/docs/features/protocols-and-certs/TLCP.md +++ b/docs/features/protocols-and-certs/TLCP.md @@ -138,5 +138,101 @@ int main() { con = SSL_new(ctx); } ``` + +## 双证书 keyUsage 检查(8.5.0) + +自 8.5.0 起,NTLS/TLCP 握手在校验证书链后,默认会对**对端**签名证书与加密证书检查 `keyUsage`(依据 GB/T 20518-2018 附录用途约定,并兼容常见实现): + +| 证书类型 | 要求(至少满足其一) | +| --- | --- | +| 签名证书 | `digitalSignature` 或 `nonRepudiation` | +| 加密证书 | `keyEncipherment`、`dataEncipherment` 或 `keyAgreement` | + +说明: + +- 证书**必须**携带 `keyUsage` 扩展;缺省扩展会导致握手失败。 +- 不要求与附录掩码完全相等,也不强制扩展为 critical。 +- 该检查**默认开启**。若需与仅部分实现、或证书 KU 不规范的对端互通,可显式关闭。 + +关闭示例(API): + +```c +SSL_CTX_set_ntls_cert_key_usage_check(ctx, 0); /* 0=关闭,1=开启 */ +/* 或针对单个 SSL 对象 */ +SSL_set_ntls_cert_key_usage_check(ssl, 0); +``` + +命令行(`s_client` / `s_server`): + +```bash +openssl s_client ... -enable_ntls -ntls -disable_ntls_cert_key_usage_check +openssl s_server ... -enable_ntls -disable_ntls_cert_key_usage_check +``` + +配置项(`SSL_CONF`):`enable_ntls_cert_key_usage_check`,取值为 `on` / `off`。 + +建议签发双证书时按 GB/T 20518-2018 附录设置 `keyUsage`,并将扩展标记为 `critical`: + +```text +# 签名证书(附录 C.3) +keyUsage = digitalSignature, nonRepudiation + +# 加密证书(附录 C.4) +keyUsage = keyEncipherment, dataEncipherment, keyAgreement +``` + +## 获取对端签名证书与加密证书(8.5.0) + +NTLS 握手成功后,可用下列接口分别取得对端的签名证书与加密证书(均为内部引用,**不要** `X509_free`): + +```c +#include + +X509 *sign_cert = SSL_get0_peer_sign_certificate_ntls(ssl); +X509 *enc_cert = SSL_get0_peer_enc_certificate_ntls(ssl); + +if (sign_cert == NULL || enc_cert == NULL) { + /* 非 NTLS 连接、握手未完成,或对端未提供对应证书 */ +} +``` + +行为要点: + +- 仅在当前连接为 NTLS 时有效;否则返回 `NULL`。 +- 签名证书对应会话中的对端身份证书;加密证书取自对端证书链中的加密证书位置(客户端与服务端在链中的索引不同,接口已封装)。 +- 适合在应用层分别校验、展示或缓存双证书,而无需自行解析 Certificate 消息顺序。 + +## NTLS CKE 标准兼容性更新(8.5.0) + +### ECC 套件:预主密钥中的协议版本检查 + +对使用 SM2 加密预主密钥的 ECC 类套件,服务端在解密 ClientKeyExchange 后会按 GB/T 38636-2020 第 6.4.5.8 节校验 `PMS.client_version` 是否与 `ClientHello.client_version` 一致。 + +- 校验失败时**不**单独抛出可区分的解密告警,而是改用随机预主密钥继续握手(与 RFC 5246 对 RSA PKCS #1.5 预主密钥版本不匹配的处理类似),以降低服务端被利用为解密预言机的风险。 +- 应用侧无需额外配置;请保证客户端写入的 PMS 前两字节与 ClientHello 版本一致。 + +### ECDHE 套件:ClientKeyExchange 长度前缀兼容 + +GB/T 38636-2020 第 6.4.5.8 节将 ECDHE 的 ClientKeyExchange 载荷描述为带长度前缀的 `opaque ClientECDHEParams<0..2^16-1>`,而既有部分实现按“裸”`ClientECDHEParams` 编解码。 + +Tongsuo 默认仍使用与既有生态兼容的编码;若需发送符合标准向量前缀的 CKE,可开启严格模式: + +```c +SSL_CTX_set_ntls_strict_ecdhe_cke(ctx, 1); /* 默认 0:兼容模式 */ +SSL_set_ntls_strict_ecdhe_cke(ssl, 1); +``` + +命令行: + +```bash +openssl s_client ... -enable_ntls -ntls -enable_ntls_strict_ecdhe_cke \ + -cipher ECDHE-SM2-WITH-SM4-SM3 \ + -sign_cert ... -sign_key ... -enc_cert ... -enc_key ... +``` + +配置项:`enable_ntls_strict_ecdhe_cke`,取值为 `on` / `off`。 + +服务端接收时会自动识别两种编码形式(有无 2 字节长度前缀),一般无需改服务端配置即可与严格/兼容客户端互通。 + ## 说明 由于国密双证书的握手流程和协议版本号与标准 tls 流程存在一定的不同,因此我们选择将双证书的实现(代码里命名为 ntls)同现有的 tls 状态机拆分开来,然后在入口处通过对请求的版本号进行识别,然后使其进入正确的状态机。 diff --git a/docs/release-note/Tongsuo-8.5.0-pre2.md b/docs/release-note/Tongsuo-8.5.0-pre2.md new file mode 100644 index 00000000..0d1503c1 --- /dev/null +++ b/docs/release-note/Tongsuo-8.5.0-pre2.md @@ -0,0 +1,20 @@ +# Tongsuo 8.5.0-pre2 发布 + +:::tip +发布时间:2026年8月3日 + +发布内容:Tongsuo 8.5.0-pre2 + +下载地址:[https://github.com/Tongsuo-Project/Tongsuo/releases/tag/8.5.0-pre2](https://github.com/Tongsuo-Project/Tongsuo/releases/tag/8.5.0-pre2) + +::: + + +本次发布重要更新: + +- 铜锁8.5.0的第二个预发布版本(-pre2),欢迎下载试用。 +- 和-pre1版本相比的更新主要包括: + - 修复若干CVE和安全问题,CVE修复同步至OpenSSL 3.5.7 + - 修复若干编译问题 + - 提供BoringSSL-style QUIC接口 + - 提供白盒SM4功能 \ No newline at end of file diff --git a/docs/release-note/Tongsuo-8.5.0.md b/docs/release-note/Tongsuo-8.5.0.md new file mode 100644 index 00000000..10898b3b --- /dev/null +++ b/docs/release-note/Tongsuo-8.5.0.md @@ -0,0 +1,43 @@ +# Tongsuo 8.5.0 发布 + +:::tip +发布时间:2026年9月30日 + +发布内容:Tongsuo 8.5.0 + +下载地址:[https://github.com/Tongsuo-Project/Tongsuo/releases/tag/8.5.0](https://github.com/Tongsuo-Project/Tongsuo/releases/tag/8.5.0) + +::: + + +本次发布重要更新: + +- 铜锁 8.5.0 正式版本,欢迎下载使用。本版本在 OpenSSL 3.5.4 基础上增强性能与协议能力,并完善 NTLS/TLCP 相关行为。 +- 重要更新(8.4.0 ~ 8.5.0): + - 修复若干 CVE 和安全问题 + - 修复若干编译问题 + - 优化 AES-GCM、SM4-GCM、HMAC、CMAC、RSA 等密码学方案以及 TLS 协议的性能,相较 8.4.0 最多可翻倍 + - TLS 连接的安全等级默认设置为 2,禁用过低的协议版本(如 TLS1.1)和安全强度低于 112bit 的密码原语;NTLS 的 ECDHE 套件(SM2-AKE)安全等级为 3 + - 支持 PQC 算法 ML-KEM、ML-DSA 和 SLH-DSA,支持 PQC 密钥协商机制 curveSM2MLKEM768、X25519MLKEM768 等 + - 实现 QUIC 协议(RFC9000),并提供 BoringSSL-style QUIC 接口 + - 实现 TCP Fast Open(RFC7413) + - 实现 HPKE(RFC9180) + - 实现 AES-GCM-SIV(RFC8452) + - 支持在 TLS 中使用 raw public key(RFC7250) + - 支持使用 brotli 和 zstd 进行证书压缩(RFC8879) + - 支持在 TLS1.3 ClientHello 中包含多个 keyshare + - 添加 TLS round-trip 时间测量功能 + - NTLS 默认开启双证书 keyUsage 检查 + - 增加获取 NTLS 对端签名证书与加密证书的 API + - NTLS 加强 ECC-CKE 协议版本检查,针对 ECDHE-CKE 提供兼容的编码方案 + - 提供白盒 SM4 功能 + - SMTC Provider 适配蚂蚁密码卡(atf_slibce) + - 增加 SDF 框架和部分功能接口 + - 随机数熵源增加 rtcode、rtmem 和 rtsock + - speed 支持测试 SM2 密钥对生成和 SM4 密钥对生成 + - 增加 TSAPI,支持常见密码学算法 + - 增加 SM2 两方门限解密/签名算法 + - 增加商用密码检测和认证 Provider,包括身份认证、完整性验证、算法自测试、随机数自检、熵源健康测试;增加 mod 应用,包括生成 SMTC 配置、自测试功能 + - 基础代码迁移到 OpenSSL 3.5.4 + +NTLS 相关能力说明见:[国密 TLCP 使用手册](/docs/features/TLCP)。 diff --git a/docs/release-note/index.md b/docs/release-note/index.md index 0eb95553..5f78240e 100644 --- a/docs/release-note/index.md +++ b/docs/release-note/index.md @@ -14,6 +14,7 @@ https://github.com/Tongsuo-Project/Tongsuo/releases | 版本 | 维护状态 | |-------|-----------------| +| 8.5.x | 当前稳定版本 | | 8.4.x | 长期维护,至少维护至2029年 | | 8.3.x | 长期维护,至少维护至2028年 | | 8.2.x | 停止维护 |