CipherHUB Cryptography Toolkit

[structured_message] 解剖任意 ASN.1/BER 字节的 TLV 结构，给出逐节点拆解树与 DER 判定（X.690）。 【算法】ASN.1 显微镜：定长（§8.1.3.3-5）/不定长 BER（§8.1.3.6，0x80+EOC）/ 分段八位串（§8.7）/高 tag 号（§8.1.2.4）均容忍；要求单根逐字节闭合。 【参数】 - asn1_in_hex：ASN.1/BER 字节的十六进制字符串（1B~128KB） 【输出】der_conformant、ber_features（walker 检出的 BER 特征清单）、 node_count、total_length、structure_tree（offset/header_len/total_len/ tag_hex/tag_number/class/constructed/length_form/value_hint/rfc_note）、 truncated、warnings。 【注意】der_conformant 是 walker 口径的近似（特征清单为空即判真）， 非完整 X.690 DER 校验器；BER 特征是识别 AWS KMS 回包等非规范编码的卖点。

[symmetric_cipher] 分组密码 CBC 模式加解密。 【算法】AES128（key=16B） / AES256（key=32B） / SM4（key=16B）。 【参数】 - algorithm：算法名 - process_type：Encrypt 或 Decrypt - input_data_in_hex：明文或密文 Hex（1B~16MB） - key_in_hex：密钥 Hex - iv_in_hex：初始向量 Hex（固定 16 字节 = 32 hex 字符） 【自动行为】加密自动 PKCS7 填充，解密自动去填充。 【输出】output_data_in_hex、output_length、output_sha256、algorithm。 【注意】解密时密文长度必须为 16 字节整数倍。

[structured_message] 把 CBOR 字节流解码为 JSON，并给出逐字段结构拆解树（RFC 8949）。 【算法】CBOR 解码，定长（§3.2.1）与不定长（§3.2.2）均容忍； 要求单数据项且逐字节闭合（尾随字节即拒绝）。 【参数】 - cbor_in_hex：CBOR 字节的十六进制字符串（1B~128KB） 【输出】decoded_json（bytes→{"hex":…}、tag→{"tag","value"}、 语义 tag→date_time/uuid 等标注形式）、decoded_type、decoded_length、 structure_tree（offset/header_len/total_len/major_type/length_form/rfc_note）、truncated、warnings。 【注意】structure_tree 超过 20000 节点或深度超 64 会截断并置 truncated=true；cbor2 对 tag 0/1/2/3 等有内置语义解码，wire 层形态以 structure_tree 为准。

[structured_message] 把 JSON 载荷编码为 CBOR 字节流（RFC 8949）。 【算法】CBOR 规范编码（RFC 8949 §4.2.1）或不定长教学编码（§3.2.2）。 【参数】 - json_payload：待编码的 JSON 文本（≤65536 字符），支持两类教学标记： {"$bytes": "<hex>"} 渲染为 byte string（major type 2）； {"$tag": <n>, "value": …} 渲染为 tagged value（major type 6） - canonical：True=规范形式（定长最短，map 键按长度+字节序排序） - prefer_indefinite：True=字符串/数组/map 用不定长编码（0x5f/0x7f/0x9f/0xbf + 0xff break） - coerce_integer_keys：True 时形如 "-35"/"0" 的十进制字符串键转整数键（复刻 Nitro attestation 的 protected 头 {1:-35}） 【输出】encoded_in_hex、encoded_length、canonical、structure_tree（逐字段拆解树）、truncated、warnings。 【注意】canonical 与 prefer_indefinite 互斥；JSON 对象键天然是字符串，需要整数键时用 coerce_integer_keys=true。

[cert] [x509_certificate] 解析 X.509 证书（国际 / 国密 GM SM2 双路径）。输入 PEM 证书（≤10KB），返回：证书类型（X.509 (international) / X.509 (GM SM2)，按签名算法 OID 是否落在国密分支 1.2.156.10197 自动判定）、版本、序列号 hex、签名算法及 OID、颁发者/主体 DN（dict 与 RFC4514 串）、有效期（UTC ISO-8601）与当前状态（valid/expired/not_yet_valid，仅信息展示）、是否自签、公钥类型与位数、SAN、扩展清单、SHA-256 与 SM3 双指纹。GM 证书额外返回主体 SM2 公钥：sm2_public_key_hex（裸坐标 X||Y，128 hex 字符）与 sm2_public_key_hex_uncompressed（未压缩点 04||X||Y，130 hex 字符，与 gmssl certparse 的 ECPoint 输出一致）。国际路径 cryptography 实现，SM2 公钥点位走 GmSSL C 库。解析失败（非法 PEM/DER）返回错误码 'Certificate parse failed'。

[cert] [x509_certificate] 用 CA 证书验证终端实体证书（单级直接签发验证）。语义：颁发者 DN 与 CA 主体 DN 匹配 + 签名可由 CA 公钥验证；不做链构建、不做吊销检查。有效期不参与 verified 判定，仅以 time_status 字段（valid/expired/not_yet_valid）信息性回显。GM 证书（签名 OID 落在 1.2.156.10197 国密分支）走 GmSSL C 的 x509_cert_verify_by_ca_cert（SM2withSM3，与 gmssl certverify CLI 同一函数），sm2_id 为签名者 ID（默认 '1234567812345678'，与 GmSSL SM2_DEFAULT_ID 同源，GM/T 0009 默认值，1~64 字节）；国际证书走 cryptography 的 verify_directly_issued_by（RSA/EC/Ed25519 等）。verified=false 是成功响应（附 reason 分类：DN 不匹配 / 签名验证失败），仅输入格式非法才返回错误码 'Certificate verify failed'。

[cms_enveloped] 解密 CMS EnvelopedData（RFC 5652 §6）/ authEnvelopedData（RFC 5083）， BER/DER 输入均容忍。 【算法】按消息声明还原算法：rsaesOaep 参数（hashFunc/MGF1/pSource， RFC 3560）重建 OAEP padding，内容算法按 OID 分派（CBC 去 PKCS#7 填充 / GCM 取独立 mac 字段验 AEAD，长度必须等于声明的 aes-ICVlen， authAttrs 存在时以 universal SET OF DER 作 AAD——RFC 5083 §3； EnvelopedData 下的 GCM 无定义，直接 reason 拒绝）。 【参数】 - cms_in_hex：信封 DER/BER 的十六进制（≤16MB） - recipient_private_key_in_pem：收件人 RSA 私钥 PEM（可选；不给则 仅做结构拆解） - recipient_private_key_password：私钥口令（未加密则留空） 【输出】decrypted（bool）、reason、plain_data_in_hex、version、 wrap/CEA（从消息声明还原）、recipients、ber_features（不定长容器/ 分段八位串/非最短长度等 BER 特征清单）、structure_tree。 【注意】结构性解析成功即 success——解密失败落 decrypted=false + reason，树照常返回；AWS KMS 回包这类 BER 信封可直接喂入。

[cms_enveloped] 构造 CMS EnvelopedData 信封（RFC 5652 §6，KeyTransRecipientInfo）。 【算法】密钥封装 RSAES-OAEP（RFC 8017 / RFC 3560 参数：hashFunc + MGF1 同哈希 + 空 pSource）或 RSAES-PKCS1-v1_5；内容加密 AES-128/256-CBC （RFC 3565，PKCS#7 填充）或 AES-128/256-GCM（RFC 5084 只为 authEnvelopedData 定义 GCM：RFC 5083 形态，version 恒 0、tag 独立 放 mac 字段、nonce 12B、aes-ICVlen 声明在参数里）。 【参数】 - recipient_certificate_in_pem：收件人 RSA 证书 PEM - key_wrap_algorithm：RSAES_OAEP_SHA_256（默认）/ SHA_1 / SHA_224 / SHA_384 / SHA_512 / RSAES_PKCS1_V1_5 - content_encryption_algorithm：AES256_CBC（默认）/ AES128_CBC / AES256_GCM / AES128_GCM - plain_data_in_hex：明文（1B~16MB） 【输出】cms_in_hex（DER 定长编码）、version、wrap/CEA 的 OID、 recipients 摘要（rid 类型/SKI 或 issuer+serial）、der_note、 structure_tree（ASN.1 TLV 拆解树）。 【注意】CEK 与 IV 服务端 CSPRNG 生成、永不回显；证书带 SKI 扩展时 rid=SKI、version=2（与 AWS KMS 回包同构），否则 issuerAndSerial、 version=0。

[cms_enveloped] 纯拆解 CMS EnvelopedData（RFC 5652 §6）/ authEnvelopedData（RFC 5083）， 不解密。 【算法】自写 ASN.1 TLV walker（X.690 BER 容忍）出结构树 + asn1crypto 出结构化字段，两层对照。 【参数】 - cms_in_hex：信封 DER/BER 的十六进制（≤16MB） 【输出】content_type_oid（envelopedData = 1.2.840.113549.1.7.3 / authEnvelopedData = 1.2.840.113549.1.9.16.1.23）、 version、recipients（rid 类型 / wrap 算法+OID / encryptedKey 字节数）、 content_encryption_iv_hex（IV 本就是公开字段）、 recipient_info_supported（非 KeyTrans 收件人置 False）、 ber_features、structure_tree（含 offset/length_form/rfc_note）。 【注意】KARI/KEKRI/PWRI/ORI 收件人（RFC 5652 §6.2.2-6.2.6）可拆解 标注，但本族不做其解密。

[cms_signed] 构造 CMS SignedData 签名消息（RFC 5652 §5）。 【算法】RSA PKCS#1 v1.5 或 ECDSA × SHA224/256/384/512； authenticatedAttributes 自动携带 contentType + messageDigest + signingTime + SMIMECapabilities，签名按 §5.4 计算在 signedAttrs 的 EXPLICIT SET OF（0x31）DER 重编码上（untag 规则）。 【参数】 - signer_certificate_in_pem：签名者证书 PEM（嵌入 certificates 集， 验签方可按 sid 定位） - signer_private_key_in_pem / signer_private_key_password：签名 私钥与口令（未加密留空） - hash_algorithm：Sha256（默认）/ Sha384 / Sha512 / Sha224 / Sha1 - detached：True 时 eContent 缺省（§5.2，载荷带外，验签必填 外部内容）；默认 False（attached，内容嵌消息） - data_in_hex：待签原文（1B~16MB） 【输出】cms_in_hex（DER 定长）、version（=1）、digest/signature 算法与 OID、signer_sid、certificates_embedded、detached、 structure_tree（ASN.1 TLV 拆解树）。 【注意】Ed25519 与 SHA1 签名被上游 PKCS7SignatureBuilder 拒绝 （add_signer 只收 RSA/EC × SHA224-512），返回签名失败错误码， 验签侧照常支持；RSA-PSS 构建未暴露——openssl cms -sign -keyopt rsa_padding_mode:pss 的产物可用 cms_signed_verify 验。

[cms_signed] 验签 CMS SignedData（RFC 5652 §5），BER/DER 输入均容忍。 【算法】按消息声明还原 digestAlgorithm / signatureAlgorithm： RSA PKCS#1 v1.5、ECDSA、Ed25519、SHA1 消息均可验；rsassa_pss 按 RFC 8017 A.2.3 参数（hashFunc / MGF1 / saltLength）重建 padding；signedAttrs 验签体是 EXPLICIT SET OF DER 重编码（§5.4）， BER 消息先规范形重编码再验。 【参数】 - cms_in_hex：SignedData DER/BER 的十六进制（≤16MB） - data_in_hex：外部内容（仅 detached 消息必填；attached 消息 以消息内嵌内容为准，忽略此字段） - signer_certificate_in_pem：签名者证书 PEM（可选；留空则从 消息 certificates 集按 sid 定位——KMS 验 Nitro 证明文档同思路） 【输出】verified（bool）、reason、key_source（provided_pem / embedded_certificates）、detached、content_in_hex（attached 时 回显 eContent）、content_matches（外部内容与 messageDigest 一致）、 digest/signature 算法与 OID、ber_features、structure_tree。 【注意】验签语义 = 签名可验证 + messageDigest 与内容一致；证书 链有效性属 cert_verify 职责（warnings 注明）；验签失败不返回 错误码，而是 verified=false + reason。

[cose_sign1] 纯拆解 COSE_Sign1 消息，不验签（RFC 9052 §4.2）。 【算法】CBOR 四元素数组 [protected, unprotected, payload, signature] 逐字段拆解；protected 头解码出 alg；payload 尝试嵌套 CBOR 解码。 【参数】 - cose_sign1_in_hex：COSE_Sign1 消息（≤128KB，hex） 【输出】protected_in_hex、protected_header、unprotected_header、 payload_in_hex、payload_json、payload_decoded、signature_raw_in_hex、 signature_format_note（裸 r||s 语义说明）、structure_tree。 【注意】structure_tree 与 cbor_decode 同构（offset/major_type/length_form/ rfc_note），四元素数组在树中可见 [protected, {}, payload, sig] 布局。

[cose_sign1] 构造并签名 COSE_Sign1 消息（RFC 9052 §4.2，算法 RFC 9053）。 【算法】ES256(-7, P-256+SHA-256) / ES384(-35, P-384+SHA-384) / ES512(-36, P-521+SHA-512) / EdDSA(-8, Ed25519)。ES 系签名为裸 r||s （坐标左补零到曲线宽度，ES512 坐标 66 字节、r||s 共 132 字节）。 【参数】 - algorithm：ES256 / ES384 / ES512 / EdDSA - ecc_private_key_in_pem：EC 或 Ed25519 私钥 PEM（须与算法曲线匹配） - ecc_private_key_password：私钥口令（未加密则留空） - payload_in_hex：待签 payload（1B~256KB） - external_aad_in_hex：外部 AAD（可选，默认空串） 【输出】cose_sign1_in_hex（完整 COSE_Sign1）、protected_in_hex、 sig_structure_in_hex（Sig_structure 待签字节，RFC 9052 §4.4，可直送 openssl dgst 交叉）、signature_raw_in_hex（裸 r||s）、 signature_der_in_hex / r_in_hex / s_in_hex（EdDSA 无此形态）、structure_tree。 【注意】签名真正覆盖的是 Sig_structure = ["Signature1", protected, external_aad, payload] 的规范编码，不是 payload 本身。

[cose_sign1] 验证 COSE_Sign1 签名（RFC 9052 §4.4 Sig_structure 重构验签）。 【算法】按 protected 头 alg 声明分派：-7/-35/-36（ES，裸 r||s → DER） 与 -8（Ed25519）。 【参数】 - cose_sign1_in_hex：COSE_Sign1 消息（≤128KB，hex） - ecc_public_key_in_pem：验签公钥 PEM。留空时从 payload 的 certificate 字段提取公钥（复刻 KMS 验 Nitro attestation 文档方式） - external_aad_in_hex：与签名时一致的外部 AAD（可选） 【输出】verified（bool）、reason、key_source（provided_pem 或 payload_certificate）、protected_header、payload_in_hex、payload_json、 payload_certificate_in_pem、sig_structure_in_hex、structure_tree。 【注意】verified=false 是成功响应（附 reason）；仅消息无法解析为 4 元素 COSE_Sign1 数组才返回错误码。

[symmetric_cipher] [symmetric_cipher] CTR 计数器模式加解密（AES-256-CTR / SM4-CTR）。CTR 是把块密码转成密钥流的模式：加解密为同一操作（密钥流 XOR），无填充，密文长度与明文等长，任意长度输入（1B ~ 16MB）。algorithm 可选 AES256CTR（key 32B，cryptography 实现）或 SM4CTR（key 16B，GmSSL C 库实现，与 eet 的 sm4-ctr 同源）。iv_in_hex 为 16 字节初始计数器块（32 hex 字符），同 key/iv 下加解密互为逆操作。注意：CTR 不提供认证（无 MAC/tag）——需要防篡改时优先用 stream_cipher 的 AEAD 模式（AES-GCM/ChaCha20-Poly1305/SM4-GCM），CTR 仅适合已有独立认证层或互操作对数场景。返回字段：output_data_in_hex、output_length、output_sha256、algorithm。

[symmetric_cipher] PKCS7 填充/去填充工具。 【参数】 - padding_action：DoPadding（填充到 16 字节对齐）或 UnPadding（去填充） - data_in_hex：待处理数据 Hex 【输出】output_data_in_hex、output_length。 【说明】块大小固定 16 字节（AES/SM4 块大小）。通常无需单独调用此工具，block_cipher 内部已自动处理填充。

[structured_message] 把 JSON 节点 DSL 编码为 DER 字节（X.690）。 【算法】DER 规范编码（定长最短 + SET OF 排序）；或教学 BER 不定长 （构造容器 0x80 + EOC，复刻 AWS KMS 回包形态）。 【参数】 - json_payload：节点 DSL（≤65536 字符），一节点一主键： {"integer": n}/{"enumerated": n}/{"boolean": true}/{"null": true}； {"oid": "1.2.840…"}（首弧 0/1 时次弧≤39）； {"octet_string": "<hex>"}/{"bit_string": {"hex","unused_bits":0..7}}； {"utf8_string"|"printable_string"|"ia5_string"|"numeric_string": s}； {"utc_time": "YYMMDDHHMMSSZ"}/{"generalized_time": "YYYYMMDDHHMMSS[.f]Z"}； {"sequence": [节点]}/{"set": [节点]}； {"context"|"application"|"private": {"number": n, "children": [节点]|"primitive_hex": "<hex>"}}（children=[单节点] 即 EXPLICIT、[内层孩子们] 即 IMPLICIT-constructed）； {"raw": {"tag_hex", "content_hex"}}（逃生舱） - der：True=规范 DER（SET OF 按 X.690 §11.6 完整子 TLV 字节排序） - ber_indefinite：True=构造容器不定长 BER（原语保持定长，§8.1.3.4） 【输出】encoded_in_hex、encoded_length、der、der_conformant、ber_features、 structure_tree（编码输出回剖的免费拆解树）、truncated、warnings。 【注意】der 与 ber_indefinite 互斥；两者皆 false 为定长 + SET OF 作者序的 教学 BER 态；时间只收线上原格式（不做 ISO 便捷转换）。

[ecc] ECDH + HKDF 密钥协商，双方各用私钥+对方公钥派生相同对称密钥。 【参数】 - alice_ecc_private_key_in_pem：己方私钥 PEM - bob_ecc_public_key_in_pem：对方公钥 PEM - hash_algorithm：HKDF 底层哈希（Sha256/Sha384/Sha512 等，不支持 Sm3） - salt：HKDF salt Hex（可选） - additional_info：HKDF info Hex（可选） - derived_key_length：派生密钥长度 16~1024 字节 - alice_ecc_private_key_password：若私钥加密则传入 【输出】derived_key_in_hex、derived_key_length。 【曲线限制】Ed25519 不可用，X25519 可用。

[ecc] ECC 私钥签名（SECP* 用 ECDSA，ED25519 用 EdDSA）。 【参数】 - ecc_private_key_in_pem：PEM 私钥 - data_in_hex：待签数据 Hex - sign_raw_data_mode：True=对原文签名（内部先哈希），False=data_in_hex 已是摘要 - hash_algorithm：Sha256/Sha384/Sha512 等（EdDSA 忽略此参数） - ecc_private_key_password：若私钥加密则传入 【输出】signature_in_hex、signature_length、curve_name。 【曲线限制】X25519 不可用于签名。

[ecc] ECC 公钥验签（SECP* 用 ECDSA，ED25519 用 EdDSA）。 【参数】 - ecc_public_key_in_pem：PEM 公钥 - data_in_hex：原始数据 Hex - signature_in_hex：签名 Hex - sign_raw_data_mode：必须与签名时一致 - hash_algorithm：必须与签名时一致 【输出】verified（bool，True=验签通过）、curve_name。 【曲线限制】X25519 不可用于验签。

[ecc] 生成 ECC 密钥对。 【曲线】ECC_SECP_256R1 / ECC_SECP_384R1 / ECC_SECP_521R1 / ECC_SECP256K1 / ECC_ED25519（仅签名）/ ECC_X25519（仅 ECDH）。 【参数】 - curve：曲线名 - private_key_password：可选，私钥 PEM 加密保护 【输出】public_key_in_pem、private_key_in_pem、curve。 【能力矩阵】 - SECP* / SECP256K1 → 签名 + 验签 + ECDH - ED25519 → 仅签名/验签（EdDSA） - X25519 → 仅 ECDH 密钥协商

[random] 使用操作系统 CSPRNG 生成安全随机字节。data_length 指定字节数（1-128），返回 data_in_hex 十六进制字符串。返回字段：data_in_hex（随机数据 Hex 编码）、data_length（实际字节数）。

[rsa] 生成 RSA 密钥对。 【参数】 - key_size：2048 / 3072 / 4096（位） - private_key_password：可选，设置后私钥 PEM 用 AES-256-CBC 加密保护 【输出】public_key_in_pem、private_key_in_pem、key_size。 【后续操作】公钥用于 rsa_encryption / rsa_verify，私钥用于 rsa_decryption / rsa_sign。

[sm2] 生成 SM2（SM2P256V1 / 国密曲线）密钥对。 【参数】 - private_key_password：必填，私钥 PEM 加密口令（1-64 字节；私钥只有加密 PEM 一种导出形态） 【输出】public_key_in_pem、private_key_in_pem、z_in_hex、point_x_in_hex、point_y_in_hex、public_key_in_hex、private_key_in_hex。 【后续操作】公钥用于 sm2_encryption / sm2_verify，私钥用于 sm2_decryption / sm2_sign。

[sm9_ibc] [sm9_ibc] 生成 SM9 标识密码主密钥（GM/T 0044，GmSSL C 实现）。key_kind='Sign' 生成签名主密钥（验签方持主公钥），'Enc' 生成加密主密钥（加密方持主公钥），默认 Enc。输出：master_public_key_in_pem（明文主公钥，分发给所有用户）与 master_private_key_in_pem（ENCRYPTED 口令加密主私钥，KGC 自留）。private_key_password 必填，1-32 UTF-8 字节。SM9 私钥 PEM 只有加密形态（无明文导出）。

[hash_digest] 计算消息摘要（支持多算法批量计算）。 【支持算法】Sha1 / Sha224 / Sha256 / Sha384 / Sha512 / Sm3 / Shake128 / Shake256。 【参数】 - plain_in_hex：明文 Hex 字符串（原始数据 1B ~ 16MB） - required_hash_modes：字符串数组，指定需要计算的算法列表，默认计算全部算法 - shake_output_length：SHAKE 系列的输出字节长度（32~256，默认 64），仅在 required_hash_modes 包含 Shake128 或 Shake256 时生效 【输出】Results 字典，每个算法对应 hash_sum_in_hex（摘要 Hex）和 hash_length（字节数）。 【SHAKE 说明】SHAKE128/256 是 XOF（可扩展输出函数），输出长度可变，适合需要自定义长度密钥派生的场景。

[utility] 健康检查 / 回显接口。客户端传入 client_msg 字符串，服务端原样回显并附加 server_msg，用于验证 MCP 通道连通性。返回字段：client_msg（回显）、server_msg（服务端附加消息）。

[hash_digest] 计算 HMAC（基于哈希的消息认证码）。 【支持算法】Sha1 / Sha224 / Sha256 / Sha384 / Sha512 / Sm3（不支持 SHAKE 系列，因 SHAKE 为 XOF 非固定长度哈希）。 【参数】 - key_in_hex：密钥 Hex。SHA 系按 RFC 2104 支持 16~256 字节（超块大小会先哈希）；若算法列表含 Sm3，上限为 64 字节（SM3 块大小，即 32~128 个 hex 字符）。 - plain_in_hex：待认证数据 Hex（1B ~ 16MB） - required_hash_modes：字符串数组，指定 HMAC 底层哈希算法列表，默认计算全部 6 种算法 【输出】Results 字典，每个算法对应 hmac_sum_in_hex（HMAC Hex 编码）和 hmac_length（字节数）。 【典型用途】消息完整性验证、API 签名、密钥确认。

[pqc_kem] 执行 X25519 + ML-KEM-768 混合密钥交换全流程演示。 【设计灵感】参考 IETF X-Wing 草案（draft-connolly-cfrg-xwing-kem）的思路，本工具实现的是通用拼接组合器（ecdh_ss || ml_kem_ss → HKDF-SHA256），并非 X-Wing 规范本身的组合器。 【参数】所有密钥参数均可选： - alice_x25519_private_key_pem / bob_x25519_private_key_pem：X25519 PEM 私钥 - alice_ml_kem_public_key_base64 / bob_ml_kem_public_key_base64：ML-KEM-768 公钥，支持 raw 或 SPKI DER Base64 - alice_ml_kem_secret_key_base64 / bob_ml_kem_secret_key_base64：ML-KEM-768 私钥，支持 raw 或 PKCS#8 DER Base64 - ML-KEM 公钥和私钥必须同时提供；留空则服务端使用 CSPRNG 随机生成 raw keypair 【流程】 1. Alice 和 Bob 各持有 X25519 + ML-KEM-768 密钥对 2. Alice 用 Bob 公钥做 X25519 ECDH + ML-KEM Encap 3. Bob 用自己私钥做 X25519 ECDH + ML-KEM Decap 4. 双方将 ecdh_ss || ml_kem_ss 通过 HKDF-SHA256 派生 32 字节最终密钥 【输出】双方中间值 + 最终密钥 + keys_match（bool）验证一致性。 【安全等级】组合后达到 NIST Level 3（ML-KEM-768）+ Level 1（X25519），抵抗经典和量子攻击。

[kdf] 执行密钥派生（KDF），从高熵秘密或口令派生对称密钥材料。 【支持算法】 - HKDF（默认）：RFC 5869 extract-then-expand，底层哈希 Sha256（默认）/ Sha384 / Sha512 - Sm3Kdf：GB/T 32918 密钥派生，SM3(Z ∥ be32(ct))，ct 从 1 起，适合对 SM2 ECDH 共享秘密派生密钥 - Pbkdf2Sm3：RFC 8018 PBKDF2，PRF 为 HMAC-SM3，用于口令拉伸 【参数】（按算法适用，错配会被拒） - algorithm：HKDF / Sm3Kdf / Pbkdf2Sm3，默认 HKDF - hash_algorithm：仅 HKDF，默认 Sha256 - input_in_hex：HKDF 的 IKM / Sm3Kdf 的共享秘密 Z，Hex（1B~16MB），与 password 二选一 - password：仅 Pbkdf2Sm3，口令原文 utf-8（1~1024B） - salt_in_hex：HKDF/Pbkdf2Sm3 可选盐 Hex（≤256B）。HKDF 空=未提供（RFC 5869 补 HashLen 零）；Pbkdf2Sm3 空=服务端生成 16B 随机盐并在响应回显 - info_in_hex：仅 HKDF，可选上下文信息 Hex（≤256B） - iterations：仅 Pbkdf2Sm3，10000~4000000（默认 10000；受 8s 网关约束，eet CLI 上限为 16777216，互通测试建议取 ≤100 万区间） - derived_key_length：派生长度，16~1024B（默认 32；Pbkdf2Sm3 上限 256B） 【输出】derived_key_in_hex、derived_key_in_base64、salt_used_in_hex（实际使用的盐，Pbkdf2Sm3 未提供盐时回显服务端随机盐）、salt_generated、algorithm、hash_algorithm、iterations、derived_key_length、input_bytes。 【典型用途】ECDH 共享秘密到会话密钥的收口、口令到加密密钥的拉伸、多上下文密钥隔离（HKDF info）。

[pqc_signature] 独立计算 ML-DSA 的 64 字节 mu 值（FIPS 204 Section 6.2）。 【用途】用于验证或调试 EXTERNAL_MU 模式的中间值，或与 AWS KMS EXTERNAL_MU 签名流程对接。 【计算公式】 - tr = SHAKE-256(raw_pk, 64) - M' = 0x00 || len(ctx) || ctx || message - mu = SHAKE-256(tr || M', 64) 【参数】 - public_key_spki_in_hex：公钥 hex（SPKI DER 或裸公钥均可），并校验 OID/长度与 algorithm 一致 - message_in_hex：原始消息 hex（最大 2048 字节，空字符串表示空消息） - context_in_hex：可选上下文 hex（最大 255 字节） - algorithm：ML-DSA-44 / ML-DSA-65（默认）/ ML-DSA-87 【输出】tr_in_hex、mu_in_hex、raw_pk_in_hex、algorithm、message_bytes。

[pqc_signature] 生成 ML-DSA 密钥对（FIPS 204，后量子数字签名标准）。 【算法选择】algorithm 支持 ML-DSA-44（NIST Level 2）/ ML-DSA-65（Level 3，默认）/ ML-DSA-87（Level 5）。 【安全等级参考】ML-DSA-44 ≈ AES-128 / ML-DSA-65 ≈ AES-192 / ML-DSA-87 ≈ AES-256。 【输出】public_key_in_hex（SPKI DER hex）、public_key_in_base64、private_key_in_hex（PKCS#8 DER hex）、private_key_in_base64、algorithm、nist_level、public_key_bytes、private_key_bytes。 【典型用途】生成密钥对后，私钥用于 ml_dsa_sign 签名，公钥用于 ml_dsa_verify 验签。

[pqc_signature] 使用 ML-DSA 私钥对消息签名（FIPS 204）。 【双模式】sign_mode 支持 RAW（默认）和 EXTERNAL_MU 两种模式。 - RAW 模式：直接签名原始消息（liboqs，最大 256 字节） - EXTERNAL_MU 模式：先计算 mu = SHAKE-256(tr||M', 64)，再通过 OpenSSL 3.5+ mu 模式签名（最大 2048 字节），与 AWS KMS ML-DSA EXTERNAL_MU 语义等价 【消息长度策略】 - RAW：最大 256 字节，空消息合法 - EXTERNAL_MU：最大 2048 字节，空消息合法 - > 256 且 <= 2048 字节：使用 EXTERNAL_MU - > 2048 字节：拒绝 【算法】algorithm 支持 ML-DSA-44 / ML-DSA-65（默认）/ ML-DSA-87。 【参数】 - private_key_in_hex：ml_dsa_keygen 返回的私钥 hex - public_key_spki_in_hex：EXTERNAL_MU 模式必填，ml_dsa_keygen 返回的公钥 hex（SPKI DER） - message_in_hex：待签消息 hex - context_in_hex：可选上下文 hex（最大 255 字节） - sign_mode：RAW 或 EXTERNAL_MU（默认 RAW） 【输出】signature_in_hex、signature_in_base64、algorithm、message_bytes、signature_bytes。

[pqc_signature] 使用 ML-DSA 公钥验证签名（FIPS 204）。 【双模式】sign_mode 支持 RAW（默认）和 EXTERNAL_MU 两种模式，必须与签名时使用的模式一致。 - RAW 模式：直接验证原始消息签名（liboqs，最大 256 字节，空消息合法） - EXTERNAL_MU 模式：先计算 mu，再通过 OpenSSL 3.5+ mu 模式验签，可验证 AWS KMS EXTERNAL_MU 签名（最大 2048 字节，空消息合法） 【算法】algorithm 支持 ML-DSA-44 / ML-DSA-65（默认）/ ML-DSA-87。 【参数】 - public_key_spki_in_hex：公钥 hex（SPKI DER 或裸公钥均可），并校验 OID/长度与 algorithm 一致 - message_in_hex：原始消息 hex，空字符串表示空消息 - signature_in_hex：签名 hex - context_in_hex：签名时使用的 context（必须一致） - sign_mode：RAW 或 EXTERNAL_MU（默认 RAW） 【输出】verified（bool，True=验签通过）、algorithm、message_bytes。

[pqc_kem] 使用 ML-KEM 私钥执行密钥解封装（FIPS 203）。 【算法】ML-KEM-512 / ML-KEM-768 / ML-KEM-1024。 【参数】 - algorithm：必须与 keygen/encap 一致 - secret_key_in_hex：ml_kem_keygen 返回的私钥 hex - ciphertext_in_hex：ml_kem_encap 返回的密文 hex 【输出】shared_secret_in_hex、shared_secret_in_base64、shared_secret_sha256、shared_secret_bytes、algorithm。 【安全特性】若密文被篡改，ML-KEM Implicit Rejection 不抛异常，返回确定性伪随机值（IND-CCA2 安全），不泄露私钥信息。 【完整流程】keygen → encap(pub) → decap(sk, ct) → 双方 shared_secret 一致

[pqc_kem] 使用 ML-KEM 公钥执行密钥封装（FIPS 203）。 【算法】ML-KEM-512 / ML-KEM-768 / ML-KEM-1024。 【参数】 - algorithm：必须与 keygen 时一致 - public_key_in_hex：ml_kem_keygen 返回的公钥 hex 【输出】ciphertext_in_hex、ciphertext_in_base64、shared_secret_in_hex、shared_secret_in_base64、shared_secret_sha256、ciphertext_bytes、shared_secret_bytes、algorithm。 【说明】每次 encap 产生不同密文（随机化），共享密钥始终 32 字节。发送 ciphertext 给密钥持有方，对方用 ml_kem_decap 恢复相同的 shared_secret。

[pqc_kem] 生成 ML-KEM 密钥对（FIPS 203，后量子密钥封装标准）。 【算法选择】ML-KEM-512（NIST Level 1）/ ML-KEM-768（Level 3，推荐）/ ML-KEM-1024（Level 5）。 【参数】 - algorithm：算法名 - seed_in_hex：64 字节种子 hex（128 字符），确定性生成 - use_random_seed：True 时忽略 seed_in_hex，使用 CSPRNG 【输出】public_key_in_hex、public_key_in_base64、secret_key_in_hex、secret_key_in_base64、seed_in_hex、algorithm、nist_level、public_key_bytes、secret_key_bytes。 【后续操作】公钥用于 ml_kem_encap，私钥用于 ml_kem_decap。

[rsa] RSA 私钥解密。 【参数】 - rsa_private_key_in_pem：PEM 格式私钥 - cipher_data_in_hex：密文 Hex（长度 = key_size/8 字节） - rsa_padding_mode：必须与加密时一致 - password：若私钥有密码保护则传入 【输出】plain_data_in_hex、plain_length。

[rsa] RSA 公钥加密。 【参数】 - rsa_public_key_in_pem：PEM 格式公钥 - plain_data_in_hex：明文 Hex - rsa_padding_mode：RSAES_PKCS1_V1_5 / RSAES_OAEP_SHA_1 / RSAES_OAEP_SHA_224 / RSAES_OAEP_SHA_256 / RSAES_OAEP_SHA_384 / RSAES_OAEP_SHA_512 【明文长度限制】受 key_size 和 padding 约束：PKCS1v1.5 上限 = 模长字节 − 11；OAEP 上限 = 模长字节 − 2×哈希输出 − 2（RSA-4096 + OAEP-SHA256 = 446 字节，OAEP-SHA512 = 382 字节）。 【输出】cipher_data_in_hex、cipher_length。 【安全建议】推荐使用 OAEP 而非 PKCS1v1.5。

[rsa] RSA 私钥签名。 【参数】 - rsa_private_key_in_pem：PEM 格式私钥 - data_in_hex：待签数据 Hex - rsa_sign_padding_mode：RSA_SIGN_PKCS1_V1_5_SHA{1,224,256,384,512} 或 RSA_SIGN_PSS_SHA{1,224,256,384,512} - rsa_sign_raw_data_mode：True=对原文签名（内部先哈希），False=data_in_hex 已是摘要值 - password：若私钥有密码保护则传入 【输出】signature_in_hex、signature_length。 【安全建议】推荐 PSS 而非 PKCS1v1.5。

[rsa] RSA 公钥验签。 【参数】 - rsa_public_key_in_pem：PEM 格式公钥 - data_in_hex：原始数据 Hex - signature_in_hex：签名 Hex - rsa_sign_padding_mode：必须与签名时一致 - rsa_sign_raw_data_mode：必须与签名时一致 【输出】verified（bool，True=验签通过）。

[sm2] SM2 私钥解密。 【参数】 - sm2_private_key_in_pem：PEM 格式私钥 - cipher_data_in_hex：密文 Hex - cipher_format：必须指定 C1C3C2_ASN1 / C1C2C3_ASN1 / C1C3C2 / C1C2C3 - sm2_private_key_password：若私钥加密则传入 【输出】plain_data_in_hex、plain_length。 【注意】cipher_format 必须与加密时的格式对应，否则解密失败。

[sm2] SM2 公钥加密。 【参数】 - sm2_public_key_in_pem：PEM 格式公钥 - plain_data_in_hex：明文 Hex 【输出】cipher_in_hex_with_format 字典，同时返回四种编码格式： - C1C3C2_ASN1：ASN.1 DER 编码（推荐，国标 GM/T 0009） - C1C2C3_ASN1：ASN.1 DER 旧格式 - C1C3C2：原始拼接格式 - C1C2C3：原始拼接旧格式 【注意】每次加密因随机 k 不同，密文不同，这是正常行为。

[sm2] 解析 SM2 加密私钥（ENCRYPTED PRIVATE KEY PEM）结构，返回 ASN.1 内部字段的 JSON 视图。用于调试与教学，不会解出私钥值。返回字段：structure（ASN.1 结构 JSON，含加密算法 OID、盐、迭代次数等）。

[sm2] 将 SM2 PEM 公钥转换为裸 Hex 编码（未压缩点，04 || X || Y）。返回字段：public_key_in_hex（130 个 hex 字符，65 字节）。

[sm2] SM2 私钥签名。 【参数】 - sm2_private_key_in_pem：PEM 格式私钥 - data_in_hex：待签数据 Hex。 · RAW 模式（sign_raw_data_mode=True）：消息原文 Hex，服务端走标准 SM2 流程，内部计算 e = SM3(ZA || M) 后签名。 · DIGEST 模式（sign_raw_data_mode=False）：必须传 32 字节 SM3 摘要 e 的 Hex（64 个 hex 字符），服务端不再做任何隐式 SM3，直接对 e 做裸 SM2 签名，与 KMS / ECC / RSA 的 DIGEST 模式语义一致。 - sign_raw_data_mode：True=RAW（原文），False=DIGEST（32 字节摘要） - sm2_private_key_password：若私钥加密则传入 【输出】signature_in_hex_with_format 字典： - RS：r||s 原始拼接（各 32 字节，共 64 字节） - RS_ASN1：ASN.1 DER 编码（推荐用于验签） 【验签时需使用 RS_ASN1 格式的签名，且 sign_raw_data_mode 必须与签名时一致】

[sm2] SM2 公钥验签。 【参数】 - sm2_public_key_in_pem：PEM 格式公钥 - data_in_hex：待验签数据 Hex。 · RAW 模式（sign_raw_data_mode=True）：消息原文 Hex，服务端走标准 SM2 流程，内部计算 e = SM3(ZA || M) 后验签。 · DIGEST 模式（sign_raw_data_mode=False）：必须传 32 字节 SM3 摘要 e 的 Hex（64 个 hex 字符），服务端不再做任何隐式 SM3，直接对 e 做裸 SM2 验签，与 KMS / ECC / RSA 的 DIGEST 模式语义一致。 - signature_in_hex：签名 Hex（必须为 RS_ASN1 格式） - signature_format：固定为 RS_ASN1 - sign_raw_data_mode：必须与签名时一致；True=RAW，False=DIGEST 【输出】verified（bool，True=验签通过）。 【完整流程】generate_sm2 → sm2_sign → sm2_verify

[sm9_ibc] [sm9_ibc] SM9 标识解密（GM/T 0044）。接收方用 KGC 派发的用户钥解密：输入 user_private_key_in_pem（SM9ExtractKey key_kind=Enc 输出）、private_key_password（用户钥口令，与提取时一致）、identity（接收方标识，必须与加密时一致）、cipher_data_in_hex（DER 密文，≤367 字节）。输出：plain_data_in_hex、plain_length。口令错或标识不符返回 'SM9 decrypt failed'。

[sm9_ibc] [sm9_ibc] SM9 标识加密（GM/T 0044）。任何人持主公钥即可加密：输入 master_public_key_in_pem（key_kind=Enc 的主公钥）、identity（接收方标识，密文与标识绑定）、plain_data_in_hex（明文 hex，1-255 字节，SM9 单次加密上限受 KDF 块计数器约束）。输出：cipher_in_hex / cipher_in_base64（DER 编码密文，C1/C3/C2 结构，≤367 字节）。

[sm9_ibc] [sm9_ibc] KGC 按标识提取 SM9 用户私钥（GM/T 0044）。输入：key_kind（Sign/Enc）、master_private_key_in_pem（GenerateSm9 输出的加密主私钥）、private_key_password（主私钥口令，提取的用户钥也以同一口令加密）、identity（被派发方标识，如邮箱/账号，1-63 UTF-8 字节）。内置 N-1 探针：GmSSL 加密 PEM 导入无口令校验，错口令可能静默解出垃圾主密钥，因此派生后当场完成一次签名验回/加解密往返（probe_verified=true）才输出。输出：user_private_key_in_pem。错口令返回 'SM9 extract user key failed'。