wop-python-sdk 0.1.0__py3-none-any.whl

wop_sdk/envelope.py

@@ -0,0 +1,165 @@
+# -*- coding: utf-8 -*-
+"""L2 数字信封（F5/D10/I3/I4/I7）。
+
+- 报文加密：AES-256-GCM（cryptography）/ SM4-GCM（自研 GCM × gmssl SM4）；
+  线上密文 = ciphertext‖tag 尾拼，整体 base64url 无填充；
+- DEK 包装：RSA-OAEP（显式双 SHA-256 + 空 label，F2 头号漂移源）/ SM2（C1C3C2 裸拼接）；
+- DEK 载荷：alg$base64url(key)$base64url(iv)；alg 族比对在解包后、bulk 解密前（D8/I3）；
+- 解密失败（GCM tag、KDF、C3、OAEP）对外一律"解密失败"（I7 模糊化）。
+"""
+import json
+import os
+from typing import Callable, Tuple, Union, cast
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding as _rsa_padding
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from .encoding import b64url_decode, b64url_encode
+from .errors import DecryptError, DekConsistencyError, ProtocolFormatError
+from .sm2crypto import Sm2Ops, sm2_decrypt, sm2_encrypt
+from .sm4gcm import sm4_gcm_decrypt, sm4_gcm_encrypt
+from .suites import Suite
+
+Csprng = Callable[[int], bytes]
+KeyMaterial = Union[rsa.RSAPublicKey, rsa.RSAPrivateKey, Sm2Ops]
+
+_AES_KEY_LEN = 32
+_SM4_KEY_LEN = 16
+_IV_LEN = 12
+_TAG_LEN = 16
+
+
+def message_encrypt(suite: Suite, key: bytes, iv: bytes, plaintext: bytes, aad: bytes = b"") -> bytes:
+    """报文对称加密 → ciphertext‖tag（F4 尾拼格式）。"""
+    if suite.family == "RSA":
+        if len(key) != _AES_KEY_LEN or len(iv) != _IV_LEN:
+            raise DecryptError("解密失败")
+        enc = Cipher(algorithms.AES(key), modes.GCM(iv)).encryptor()
+        return enc.update(plaintext) + enc.finalize() + enc.tag
+    if len(key) != _SM4_KEY_LEN or len(iv) != _IV_LEN:
+        raise DecryptError("解密失败")
+    return sm4_gcm_encrypt(key, iv, plaintext, aad)
+
+
+def message_decrypt(suite: Suite, key: bytes, iv: bytes, cipher_tag: bytes, aad: bytes = b"") -> bytes:
+    """报文对称解密（输入 ciphertext‖tag）；任何失败对外模糊（I7）。"""
+    if suite.family == "RSA":
+        if len(key) != _AES_KEY_LEN or len(iv) != _IV_LEN or len(cipher_tag) < _TAG_LEN:
+            raise DecryptError("解密失败")
+        cipher, tag = cipher_tag[:-_TAG_LEN], cipher_tag[-_TAG_LEN:]
+        dec = Cipher(algorithms.AES(key), modes.GCM(iv, tag)).decryptor()
+        try:
+            return dec.update(cipher) + dec.finalize()
+        except Exception:
+            raise DecryptError() from None
+    if len(key) != _SM4_KEY_LEN or len(iv) != _IV_LEN or len(cipher_tag) < _TAG_LEN:
+        raise DecryptError("解密失败")
+    try:
+        return sm4_gcm_decrypt(key, iv, cipher_tag, aad)
+    except ValueError:
+        raise DecryptError() from None
+
+
+# OAEP 显式参数化（F2/D10）：OAEP 摘要 SHA-256 + MGF1 摘要显式钉死 SHA-256 + 空 label。
+# JCA 串 OAEPWithSHA-256AndMGF1Padding 的 MGF1 默认 SHA-1，禁止依赖默认值。
+def _oaep_params() -> _rsa_padding.OAEP:
+    return _rsa_padding.OAEP(
+        mgf=_rsa_padding.MGF1(algorithm=hashes.SHA256()),
+        algorithm=hashes.SHA256(),
+        label=None,
+    )
+
+
+def wrap_dek(suite: Suite, wrap_pub: KeyMaterial, payload: bytes, csprng: Csprng = os.urandom) -> bytes:
+    """DEK 非对称包装（出向，平台公钥）。SM2 的 k 走 csprng（I4）。"""
+    if suite.family == "RSA":
+        return cast(rsa.RSAPublicKey, wrap_pub).encrypt(payload, _oaep_params())
+    return sm2_encrypt(cast(Sm2Ops, wrap_pub), csprng, payload)
+
+
+def unwrap_dek(suite: Suite, wrap_priv: KeyMaterial, wrapped: bytes) -> bytes:
+    """DEK 解包（入向）；失败对外模糊（I7）。"""
+    if suite.family == "RSA":
+        try:
+            return cast(rsa.RSAPrivateKey, wrap_priv).decrypt(wrapped, _oaep_params())
+        except Exception:
+            raise DecryptError() from None
+    try:
+        return sm2_decrypt(cast(Sm2Ops, wrap_priv), wrapped)
+    except DecryptError:
+        raise
+    except Exception:
+        raise DecryptError() from None
+
+
+def build_dek_payload(suite: Suite, key: bytes, iv: bytes) -> str:
+    """DEK 载荷 alg$base64url(key)$base64url(iv)（§6.1）。"""
+    return "%s$%s$%s" % (suite.message_alg, b64url_encode(key), b64url_encode(iv))
+
+
+def parse_dek_payload(suite: Suite, payload: str) -> Tuple[bytes, bytes]:
+    """解析 DEK 载荷（明文，已解包后调用）。
+
+    时序（D8/I3）：alg 段在载荷明文内部 → 解包之后、bulk 解密之前完成族比对。
+    alg 与套件族不符 → 一致性类（明确）；结构/编码错误 → 解析类（明确）。
+    """
+    parts = payload.split("$")
+    if len(parts) != 3:
+        raise ProtocolFormatError("DEK 载荷必须为 alg$key$iv 三段，实际 %d 段" % len(parts))
+    alg, key_b64u, iv_b64u = parts
+    if alg not in ("AES-256-GCM", "SM4-GCM"):
+        raise ProtocolFormatError("DEK 载荷 alg 未知：%r" % alg)
+    if alg != suite.message_alg:  # I3/I5：族比对先于 bulk 解密
+        raise DekConsistencyError(
+            "DEK 算法 %s 与套件 %s 要求的 %s 不符" % (alg, suite.security_req, suite.message_alg)
+        )
+    try:
+        key = b64url_decode(key_b64u)
+        iv = b64url_decode(iv_b64u)
+    except ValueError as exc:
+        raise ProtocolFormatError("DEK 载荷 key/iv 编码非法：%s" % exc) from exc
+    expected_key_len = _AES_KEY_LEN if suite.family == "RSA" else _SM4_KEY_LEN
+    if len(key) != expected_key_len or len(iv) != _IV_LEN:
+        raise ProtocolFormatError(
+            "DEK 载荷 key/iv 长度非法（key %d、iv %d）" % (len(key), len(iv))
+        )
+    return key, iv
+
+
+def seal_l2(
+    suite: Suite, platform_pub: KeyMaterial, plaintext: bytes, csprng: Csprng = os.urandom
+) -> Tuple[bytes, str]:
+    """L2 加密封装 → (wireBody, x-wop-encrypt 头)。
+
+    DEK 与 IV 均由 csprng 生成（I4：同一密钥下 IV 永不复用，生成点唯一）。
+    """
+    key_len = _AES_KEY_LEN if suite.family == "RSA" else _SM4_KEY_LEN
+    key = csprng(key_len)
+    iv = csprng(_IV_LEN)
+    cipher_tag = message_encrypt(suite, key, iv, plaintext)
+    wire_body = json.dumps({"encrypted": b64url_encode(cipher_tag)}, separators=(",", ":")).encode()
+    payload = build_dek_payload(suite, key, iv).encode("utf-8")
+    wrapped = wrap_dek(suite, platform_pub, payload, csprng)
+    return wire_body, "L2;dek=" + b64url_encode(wrapped)
+
+
+def open_l2(suite: Suite, wrap_priv: KeyMaterial, wire_body: bytes, dek_b64u: str) -> bytes:
+    """L2 解密（F6 第 3–5 步）：DEK 解包（模糊）→ alg 族比对（明确）→ bulk 解密（模糊）。"""
+    try:
+        wrapped = b64url_decode(dek_b64u)
+    except ValueError:
+        raise DecryptError() from None
+    payload = unwrap_dek(suite, wrap_priv, wrapped).decode("utf-8", errors="strict")
+    key, iv = parse_dek_payload(suite, payload)
+    try:
+        obj = json.loads(wire_body)
+        encrypted = obj["encrypted"]
+    except Exception:
+        raise DecryptError() from None
+    try:
+        cipher_tag = b64url_decode(encrypted)
+    except (ValueError, TypeError):
+        raise DecryptError() from None
+    return message_decrypt(suite, key, iv, cipher_tag)

wop_sdk/errors.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""WOP SDK 错误分类（crypto-strategy-spec §10.2）。
+
+明确/模糊分界原则（I7）：鉴权前可判定的公开协议知识 → 明确（帮助商户集成自查）；
+依赖密钥参与的判定 → 模糊（防 oracle）。验签/解密失败的对外消息不区分原因细节。
+"""
+
+
+class WopSdkError(Exception):
+    """SDK 错误基类。"""
+
+
+class SuiteParseError(WopSdkError):
+    """解析类：securityReq 三段式/前缀/格式错误。对外语义明确。"""
+
+
+class UnsupportedSuiteError(WopSdkError):
+    """支持类：算法不在列表、跨族、密钥长度非法（I5）。对外语义明确。"""
+
+
+class ProtocolFormatError(WopSdkError):
+    """解析类：线上头结构（x-wop-sign / x-wop-encrypt / digest header）格式错误。明确。"""
+
+
+class KeyMaterialError(WopSdkError):
+    """配置类：密钥材料缺失/格式不符/不在指定曲线（D12、I5）。配置期可判定，明确。"""
+
+
+class DigestMismatchError(WopSdkError):
+    """完整性类：摘要不匹配。公开协议知识，明确。"""
+
+
+class SignatureVerifyError(WopSdkError):
+    """验签类：签名验证失败。对外模糊——不区分原因细节（I7）。"""
+
+    def __init__(self, message: str = "签名验证失败"):
+        super().__init__(message)
+
+
+class DecryptError(WopSdkError):
+    """解密类：DEK 解包失败、GCM tag 失败、SM2 密文校验失败。对外模糊（I7）。"""
+
+    def __init__(self, message: str = "解密失败"):
+        super().__init__(message)
+
+
+class DekConsistencyError(WopSdkError):
+    """一致性类：DEK alg 与套件族不符。公开映射知识，明确（D8/I3）。"""

wop_sdk/keys.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+"""密钥材料解析（D12 分发契约）。
+
+- RSA 公钥 = X.509 SPKI DER，Base64 编码（PEM 仅作可选包装）
+- RSA 私钥 = PKCS#8 DER，Base64 编码（PEM 可选包装）
+- SM2 公钥 = 未压缩点 04‖X‖Y（65 字节），Base64 编码；必须在 sm2p256v1 曲线上（I5）
+- SM2 私钥 = d 标量（32 字节大端），1 ≤ d < n
+"""
+import base64
+import binascii
+from dataclasses import dataclass
+from typing import Optional
+
+from cryptography.exceptions import InvalidKey
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.serialization import load_der_private_key, load_der_public_key
+
+from .errors import KeyMaterialError
+
+# sm2p256v1 曲线参数（GB/T 32918.5）
+_SM2_P = 0xFFFFFFFEFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF00000000FFFFFFFFFFFFFFFF
+_SM2_A = 0xFFFFFFFEFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF00000000FFFFFFFFFFFFFFFC
+_SM2_B = 0x28E9FA9E9D9F5E344D5A9E4BCF6509A7F39789F515AB8F92DDBCBD414D940E93
+_SM2_N = 0xFFFFFFFEFFFFFFFFFFFFFFFFFFFFFFFF7203DF6B21C6052B53BBF40939D54123
+
+
+@dataclass(frozen=True)
+class Sm2PublicKey:
+    """SM2 公钥点（X‖Y 128 hex，无 04 前缀；uncompressed 含 04）。"""
+
+    xy_hex: str
+    uncompressed: bytes
+
+
+def _material_to_der(material: str) -> bytes:
+    """密钥材料 → DER 字节：接受 PEM 包装或单行 Base64（标准/URL 字母表，允许 padding）。"""
+    text = material.strip()
+    if "-----BEGIN" in text:
+        body = "".join(line for line in text.splitlines() if "-----" not in line)
+    else:
+        body = "".join(text.split())
+    if not body:
+        raise KeyMaterialError("密钥内容为空")
+    try:
+        return base64.b64decode(body, validate=True)
+    except (binascii.Error, ValueError):
+        pass
+    try:
+        return base64.urlsafe_b64decode(body + "=" * (-len(body) % 4))
+    except (binascii.Error, ValueError):
+        raise KeyMaterialError("密钥材料无法解码为 Base64") from None
+
+
+def load_rsa_public_key(material: str, expected_bits: Optional[int] = None) -> rsa.RSAPublicKey:
+    der = _material_to_der(material)
+    try:
+        key = load_der_public_key(der)
+    except (InvalidKey, ValueError, TypeError) as exc:
+        raise KeyMaterialError("RSA 公钥解析失败（应为 SPKI DER Base64/PEM）: %s" % exc) from exc
+    if not isinstance(key, rsa.RSAPublicKey):
+        raise KeyMaterialError("非 RSA 公钥材料")
+    if expected_bits is not None and key.key_size != expected_bits:
+        raise KeyMaterialError(
+            "RSA 公钥长度 %d 与套件要求 %d 不符" % (key.key_size, expected_bits)
+        )
+    return key
+
+
+def load_rsa_private_key(material: str, expected_bits: Optional[int] = None) -> rsa.RSAPrivateKey:
+    der = _material_to_der(material)
+    try:
+        key = load_der_private_key(der, password=None)
+    except (InvalidKey, ValueError, TypeError) as exc:
+        raise KeyMaterialError("RSA 私钥解析失败（应为 PKCS#8 DER Base64/PEM）: %s" % exc) from exc
+    if not isinstance(key, rsa.RSAPrivateKey):
+        raise KeyMaterialError("非 RSA 私钥材料")
+    if expected_bits is not None and key.key_size != expected_bits:
+        raise KeyMaterialError(
+            "RSA 私钥长度 %d 与套件要求 %d 不符" % (key.key_size, expected_bits)
+        )
+    return key
+
+
+def load_sm2_public_key(material: str) -> Sm2PublicKey:
+    der = _material_to_der(material)
+    if len(der) != 65 or der[0] != 0x04:
+        raise KeyMaterialError(
+            "SM2 公钥必须为未压缩点 04‖X‖Y（65 字节），实际 %d 字节" % len(der)
+        )
+    x = int.from_bytes(der[1:33], "big")
+    y = int.from_bytes(der[33:65], "big")
+    # I5：点必须在 sm2p256v1 曲线上（y² ≡ x³ + ax + b mod p）
+    if (y * y - (x * x * x + _SM2_A * x + _SM2_B)) % _SM2_P != 0:
+        raise KeyMaterialError("SM2 公钥点不在 sm2p256v1 曲线上")
+    return Sm2PublicKey(xy_hex=der[1:].hex(), uncompressed=der)
+
+
+def load_sm2_private_key(material: str) -> bytes:
+    der = _material_to_der(material)
+    if len(der) != 32:
+        raise KeyMaterialError("SM2 私钥必须为 32 字节大端标量 d，实际 %d 字节" % len(der))
+    d = int.from_bytes(der, "big")
+    if not 1 <= d < _SM2_N:
+        raise KeyMaterialError("SM2 私钥标量 d 超出 [1, n) 范围")
+    return der

wop_sdk/signature.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""结构化签名（F3/F7/D9）：SHA256withRSA（PKCS#1 v1.5）与 SM3withSM2（裸 r‖s 64B）。
+
+定长编码前置校验：长度不符按解析类拒绝，先于任何密码学运算（§3.3①）。
+"""
+import os
+from typing import Callable, Union, cast
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+
+from .errors import ProtocolFormatError, SignatureVerifyError
+from .sm2crypto import _N, Sm2Ops, sm2_sign_with_sm3, sm2_verify_with_sm3
+from .suites import Suite
+
+Csprng = Callable[[int], bytes]
+Signer = Union[rsa.RSAPrivateKey, Sm2Ops]
+Verifier = Union[rsa.RSAPublicKey, Sm2Ops]
+
+
+def sign(suite: Suite, signer: Signer, data: bytes, csprng: Csprng = os.urandom) -> bytes:
+    """加签：RSA → PKCS#1 v1.5 + SHA-256；SM2 → SM3withSM2 裸 r‖s（k 走 csprng，I4）。"""
+    if suite.family == "RSA":
+        key = cast(rsa.RSAPrivateKey, signer)
+        return key.sign(data, padding.PKCS1v15(), hashes.SHA256())
+    for _ in range(256):
+        k = int.from_bytes(csprng(32), "big")
+        if 1 <= k < _N:
+            return sm2_sign_with_sm3(signer, data, "%064x" % k)
+    raise SignatureVerifyError("签名验证失败")  # pragma: no cover —— 2^-2048 概率
+
+
+def verify(suite: Suite, verifier: Verifier, data: bytes, signature: bytes) -> None:
+    """验签；失败抛 SignatureVerifyError（I7：对外模糊，不区分原因细节）。
+
+    长度前置校验（解析类，先于密码学运算）：
+    RSA3072 → 384B；RSA4096 → 512B；SM2 → 恒 64B（63B/65B/DER 一律拒绝）。
+    """
+    if suite.family == "RSA":
+        if len(signature) != suite.key_bits // 8:
+            raise ProtocolFormatError(
+                "RSA 签名长度 %d 与套件 %d 位要求的 %d 字节不符"
+                % (len(signature), suite.key_bits, suite.key_bits // 8)
+            )
+        try:
+            pub = cast(rsa.RSAPublicKey, verifier)
+            pub.verify(signature, data, padding.PKCS1v15(), hashes.SHA256())
+        except InvalidSignature:
+            raise SignatureVerifyError() from None
+        return
+    if len(signature) != 64:
+        raise ProtocolFormatError(
+            "SM2 签名必须为裸 r||s 64 字节（禁 DER），实际 %d 字节" % len(signature)
+        )
+    if not sm2_verify_with_sm3(verifier, signature.hex(), data):
+        raise SignatureVerifyError()

wop_sdk/sm2crypto.py

@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+"""SM2 底层操作：签名（裸 r‖s，D9）、加密（C1C3C2，D9）、解密（含 gmssl 缺失的 C3 校验）。
+
+与 gmssl 原生 API 的差异（均为刻意为之）：
+1. 绕开 ``CryptSM2.__init__`` 的 ``public_key.lstrip("04")`` 缺陷——合法 X 以 '0'/'4' 字符
+   开头时（概率 ≈ 1/8）会被误剥，本类覆写 public_key 为标准 X‖Y 128+128 hex；
+2. gmssl ``decrypt`` 计算摘要 u 却从不比对 C3——本模块自研解密补上完整性校验，
+   C1C2C3 旧国标顺序密文在此必然失败（顺序钉死负向量的拦截点）；
+3. gmssl ``encrypt``/``random_hex`` 使用 ``random.choice``（非 CSPRNG）——本模块的 k
+   一律由调用方注入（生产走 csprng，测试走固定向量，I4）。
+"""
+from typing import Optional, cast
+
+from gmssl import sm3 as _sm3
+from gmssl.sm2 import CryptSM2, default_ecc_table
+
+from .errors import DecryptError, KeyMaterialError
+
+_N = int(default_ecc_table["n"], 16)
+_P = int(default_ecc_table["p"], 16)
+_A = int(default_ecc_table["a"], 16)
+_B = int(default_ecc_table["b"], 16)
+
+_MAX_K_RETRY = 256
+
+
+class Sm2Ops(CryptSM2):
+    """SM2 曲线运算封装（无可变共享状态）。"""
+
+    def __init__(self, private_key_hex: Optional[str] = None, public_xy_hex: Optional[str] = None):
+        super().__init__(private_key_hex or "00" * 32, "00" * 128)
+        # 覆写绕过 lstrip 缺陷；public_key 恒为 X‖Y（128+128 hex，无 04 前缀）
+        if public_xy_hex is not None:
+            if len(public_xy_hex) != 64 * 2:
+                raise KeyMaterialError("SM2 公钥 hex 必须为 X||Y 共 128 字符（X‖Y 各 32 字节）")
+            self.public_key = public_xy_hex
+        if private_key_hex is not None:
+            self.private_key = private_key_hex
+
+
+def _point_on_curve(xy_hex: str) -> bool:
+    x = int(xy_hex[:64], 16)
+    y = int(xy_hex[64:], 16)
+    return (y * y - (x * x * x + _A * x + _B)) % _P == 0
+
+
+def sm2_sign_with_sm3(ops: Sm2Ops, data: bytes, k_hex: str) -> bytes:
+    """SM3withSM2 签名：e = SM3(ZA‖M)，ZA userId = '1234567812345678'；输出裸 r‖s 64B。"""
+    e_hex = ops._sm3_z(data)
+    sig_hex = cast(str, ops.sign(bytes.fromhex(e_hex), k_hex))
+    return bytes.fromhex(sig_hex)
+
+
+def sm2_verify_with_sm3(ops: Sm2Ops, sig_hex: str, data: bytes) -> bool:
+    """SM3withSM2 验签（裸 r‖s hex）。"""
+    return bool(ops.verify_with_sm3(sig_hex, data))
+
+
+def sm2_encrypt(ops: Sm2Ops, csprng, plaintext: bytes) -> bytes:
+    """SM2 加密，线上格式 C1C3C2 裸拼接（C1 = 未压缩点 04‖X‖Y 65B）。
+
+    k 由 csprng 注入（I4：CSPRNG，随机数生成点收敛于调用方）。
+    """
+    for _ in range(_MAX_K_RETRY):
+        k = int.from_bytes(csprng(32), "big")
+        if 1 <= k < _N:
+            break
+    else:  # pragma: no cover —— CSPRNG 连续 256 次不可用采样概率 ≈ 2^-2048
+        raise DecryptError("解密失败")
+    c1_xy = cast(str, ops._kg(k, ops.ecc_table["g"]))
+    x2y2 = cast(str, ops._kg(k, ops.public_key))
+    x2, y2 = x2y2[:64], x2y2[64:]
+    c2 = _xor_kdf(plaintext, x2y2)
+    c3 = _sm3.sm3_hash(list(bytes.fromhex(x2 + plaintext.hex() + y2)))
+    return bytes.fromhex("04" + c1_xy + c3) + c2
+
+
+def sm2_decrypt(ops: Sm2Ops, cipher: bytes) -> bytes:
+    """SM2 解密（C1C3C2），C3 摘要校验失败抛 DecryptError（I7 模糊，不区分细节）。"""
+    if len(cipher) < 65 + 32 + 1 or cipher[0] != 0x04:
+        raise DecryptError("解密失败")
+    c1_xy_hex = cipher[1:65].hex()
+    if not _point_on_curve(c1_xy_hex):
+        raise DecryptError("解密失败")
+    c3_hex = cipher[65:97].hex()
+    c2 = cipher[97:]
+    x2y2 = cast(str, ops._kg(int(ops.private_key, 16), c1_xy_hex))
+    x2, y2 = x2y2[:64], x2y2[64:]
+    plaintext = _xor_kdf(c2, x2y2)
+    u = _sm3.sm3_hash(list(bytes.fromhex(x2 + plaintext.hex() + y2)))
+    if u != c3_hex:
+        raise DecryptError("解密失败")
+    return plaintext
+
+
+def _xor_kdf(data: bytes, xy_hex: str) -> bytes:
+    """SM2 KDF（x2‖y2 作种子）与数据异或；密钥流全零视为失败（概率 2^-128）。"""
+    t = _sm3.sm3_kdf(xy_hex.encode("utf-8"), len(data))
+    if int(t, 16) == 0:  # pragma: no cover —— KDF 全零概率 2^-128，不可确定性构造
+        raise DecryptError("解密失败")
+    form = "%%0%dx" % (len(data) * 2)
+    return bytes.fromhex(form % (int(data.hex(), 16) ^ int(t, 16)))
+
+
+def sm2_derive_public_hex(private_key_hex: str) -> str:
+    """由私钥标量 d 推导公钥 X‖Y（128 hex，签名 ZA 需要）。"""
+    ops = CryptSM2(private_key_hex, "00" * 128)
+    return cast(str, ops._kg(int(private_key_hex, 16), ops.ecc_table["g"]))

wop_sdk/sm4gcm.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""SM4-GCM（NIST SP 800-38D GCM 构造 × GB/T 32907 SM4 分组函数）。
+
+gmssl ≥3.2.2 仅提供 SM4 ECB/CBC，无 GCM；本模块以 gmssl ``one_round``（无 padding
+的单块加密原语）为底层分组函数实现 GCM（CTR + GHASH），正确性由黄金向量
+sm4gcm-encrypt 字节级锚定（D11：官方 SDK 即 SM 生态答案）。
+"""
+from gmssl.sm4 import SM4_ENCRYPT, CryptSM4
+
+_R = 0xE1 << 120  # GF(2^128) 约减多项式 x^128+x^7+x^2+x+1
+
+def _gf_mult(x: int, y: int) -> int:
+    """GF(2^128) 乘法（MSB-first 位串，SP 800-38D Algorithm 1）。"""
+    z, v = 0, x
+    for i in range(127, -1, -1):
+        if (y >> i) & 1:
+            z ^= v
+        if v & 1:
+            v = (v >> 1) ^ _R
+        else:
+            v >>= 1
+    return z
+
+
+class _Sm4Block:
+    """SM4 单块加密函数对象（密钥扩展一次，线程封闭使用）。"""
+
+    def __init__(self, key: bytes):
+        self._cipher = CryptSM4()
+        self._cipher.set_key(key, SM4_ENCRYPT)
+
+    def __call__(self, block: bytes) -> bytes:
+        return bytes(self._cipher.one_round(self._cipher.sk, list(block)))
+
+
+def _ghash(h: int, aad: bytes, cipher: bytes) -> int:
+    pad_a = (16 - len(aad) % 16) % 16
+    pad_c = (16 - len(cipher) % 16) % 16
+    data = (
+        aad
+        + b"\x00" * pad_a
+        + cipher
+        + b"\x00" * pad_c
+        + (len(aad) * 8).to_bytes(8, "big")
+        + (len(cipher) * 8).to_bytes(8, "big")
+    )
+    y = 0
+    for i in range(0, len(data), 16):
+        y = _gf_mult(y ^ int.from_bytes(data[i : i + 16], "big"), h)
+    return y
+
+
+def _gcm_core(block_fn, iv: bytes, data: bytes, aad: bytes, ghash_over_input: bool):
+    """GCM 公共路径：返回 (输出块, tag)。
+
+    GHASH 恒作用于密文：加密方向密文 = CTR 输出，解密方向密文 = 输入 data。
+    """
+    h = int.from_bytes(block_fn(b"\x00" * 16), "big")
+    j0 = iv + b"\x00\x00\x00\x01"
+    ctr = int.from_bytes(j0, "big")
+    out = bytearray()
+    for off in range(0, len(data), 16):
+        ctr = (ctr & ~0xFFFFFFFF) | ((ctr + 1) & 0xFFFFFFFF)  # inc32：仅低 32 位
+        keystream = block_fn(ctr.to_bytes(16, "big"))
+        out += bytes(p ^ k for p, k in zip(data[off : off + 16], keystream))
+    ghash_input = data if ghash_over_input else bytes(out)
+    s = _ghash(h, aad, ghash_input)
+    tag = bytes(a ^ b for a, b in zip(block_fn(j0), s.to_bytes(16, "big")))
+    return bytes(out), tag
+
+
+def sm4_gcm_encrypt(key: bytes, iv: bytes, plaintext: bytes, aad: bytes = b"") -> bytes:
+    """SM4-GCM 加密，返回 ciphertext‖tag（F4：tag 128bit 尾拼）。"""
+    out, tag = _gcm_core(_Sm4Block(key), iv, plaintext, aad, ghash_over_input=False)
+    return out + tag
+
+
+def sm4_gcm_decrypt(key: bytes, iv: bytes, cipher_tag: bytes, aad: bytes = b"") -> bytes:
+    """SM4-GCM 解密（输入 ciphertext‖tag）；tag 不符抛 ValueError。"""
+    if len(cipher_tag) < 16:
+        raise ValueError("密文短于 tag 长度")
+    cipher, tag = cipher_tag[:-16], cipher_tag[-16:]
+    out, expect = _gcm_core(_Sm4Block(key), iv, cipher, aad, ghash_over_input=True)
+    if bytes(a ^ b for a, b in zip(tag, expect)) != b"\x00" * 16:
+        raise ValueError("GCM tag 校验失败")
+    return out

wop_sdk/suites.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+"""securityReq 套件解析（F1，crypto-strategy-spec §2）。
+
+格式：WOP-<密钥算法标识>-<摘要算法标识>，三段式；
+映射关系集中注册于代码（单一注册表，D13），无运行时配置入口。
+"""
+from dataclasses import dataclass
+from typing import Optional
+
+from .errors import SuiteParseError, UnsupportedSuiteError
+
+# 密钥算法 → (族, RSA 位长)。SM2 族 key_bits=0。
+_KEY_ALGORITHMS = {
+    "RSA3072": ("RSA", 3072),
+    "RSA4096": ("RSA", 4096),
+    "SM2": ("SM", 0),
+}
+# 摘要算法 → (族, header 标签)；族与密钥算法族同名（I5 比对基准）
+_DIGEST_ALGORITHMS = {
+    "SHA256": ("RSA", "sha-256"),
+    "SM3": ("SM", "sm3"),
+}
+
+# 族 → 报文对称算法 / DEK 包装算法 / 签名算法名
+_FAMILY_MESSAGE_ALG = {"RSA": "AES-256-GCM", "SM": "SM4-GCM"}
+_FAMILY_KEY_WRAP = {3072: "RSA-3072-OAEP", 4096: "RSA-4096-OAEP"}
+_FAMILY_SIGN = {"RSA": "SHA256withRSA", "SM": "SM3withSM2"}
+
+
+@dataclass(frozen=True)
+class Suite:
+    """一次请求的算法上下文（不可变；spec §4.4 AlgorithmSuite 的 SDK 侧映像）。"""
+
+    security_req: str
+    family: str  # "RSA" | "SM"
+    key_bits: int  # 3072 | 4096 | 0（SM2）
+    digest_alg: str  # "SHA256" | "SM3"
+    digest_tag: str  # "sha-256" | "sm3"
+    sign_alg: str
+    message_alg: str  # "AES-256-GCM" | "SM4-GCM"
+    key_wrap_alg: str
+
+
+def parse_suite(security_req: Optional[str]) -> Suite:
+    """解析 securityReq；失败按 §2.4 分类（解析类/支持类）拒绝。"""
+    if security_req is None or not security_req.strip():
+        raise SuiteParseError("securityReq 为空")
+    parts = security_req.split("-")
+    if len(parts) != 3 or parts[0] != "WOP":
+        raise SuiteParseError(
+            "securityReq 格式错误：应为 WOP-<密钥算法>-<摘要算法> 三段式，实际 %r" % security_req
+        )
+    _, key_alg, digest_alg = parts
+    if key_alg not in _KEY_ALGORITHMS:
+        raise UnsupportedSuiteError("不支持的密钥算法：%s" % key_alg)
+    if digest_alg not in _DIGEST_ALGORITHMS:
+        raise UnsupportedSuiteError("不支持的摘要算法：%s" % digest_alg)
+    family, key_bits = _KEY_ALGORITHMS[key_alg]
+    digest_family, digest_tag = _DIGEST_ALGORITHMS[digest_alg]
+    # I5：国际/国密跨族组合禁止（§2.3）
+    if family != digest_family:
+        raise UnsupportedSuiteError(
+            "跨族算法组合被拒绝：%s（密钥族 %s 与摘要族 %s 不一致）"
+            % (security_req, family, digest_family)
+        )
+    if family == "RSA":
+        key_wrap_alg = _FAMILY_KEY_WRAP[key_bits]
+    else:
+        key_wrap_alg = "SM2"
+    return Suite(
+        security_req=security_req,
+        family=family,
+        key_bits=key_bits,
+        digest_alg=digest_alg,
+        digest_tag=digest_tag,
+        sign_alg=_FAMILY_SIGN[family],
+        message_alg=_FAMILY_MESSAGE_ALG[family],
+        key_wrap_alg=key_wrap_alg,
+    )