密钥统管时代来临：《电子认证服务使用密码管理办法》7月1日施行，CA机构如何应对密钥管理合规挑战

┌──────────────────────────────────────────────────────┐
│                  CA 电子认证服务系统                    │
├──────────────┬───────────────┬───────────────────────┤
│  签发系统     │   OCSP系统    │    时间戳系统          │
│  (适配层)     │   (适配层)    │    (适配层)            │
├──────────────┴───────────────┴───────────────────────┤
│           统一密钥服务适配层 (KMS Adapter)              │
│    ┌─────────────────────────────────────────┐       │
│    │  GM/T 0033 API  │  REST API  │  PKCS#11 │       │
│    └─────────────────────────────────────────┘       │
├──────────────────────────────────────────────────────┤
│              本地HSM缓存层（高可用）                     │
│    ┌──────────┐  ┌──────────┐  ┌──────────┐         │
│    │ HSM主设备 │  │ HSM备设备 │  │ 密钥缓存  │         │
│    │ (国密二级)│  │ (国密二级)│  │ (内存加密)│         │
│    └──────────┘  └──────────┘  └──────────┘         │
└──────────────────────────────────────────────────────┘
                          │
                          │ 安全通道 (国密TLS)
                          ▼
┌──────────────────────────────────────────────────────┐
│          省级/国家级统一密钥管理系统                      │
│    ┌─────────────────────────────────────────┐       │
│    │  密钥生成 │ 密钥分发 │ 密钥备份 │ 密钥销毁 │       │
│    └─────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────┘

"""
CA密钥管理系统适配层
功能：统一管理本地HSM与统一密钥管理系统的接入
环境要求：
  - Python 3.9+
  - gmssl >= 3.2.1 (国密算法库)
  - cryptography >= 42.0 (SM4-CBC支持)
  - 国密HSM设备（支持GM/T 0018）
  - 统一密钥管理系统API（基于GM/T 0033）
注意：gmssl 3.2.x的crypt_ecb在DECRYPT模式有bug，SM4-CBC需用cryptography库
"""

import os
import json
import logging
from typing import Optional, Tuple, Dict
from dataclasses import dataclass, field
from enum import Enum

from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.primitives import padding as sym_padding
from cryptography.hazmat.backends import default_backend

logger = logging.getLogger(__name__)


class KeyType(Enum):
    """密钥类型枚举"""
    SM2_SIGN = "sm2_sign"          # SM2签名密钥
    SM2_ENCRYPT = "sm2_encrypt"    # SM2加密密钥
    SM4_SYMMETRIC = "sm4"          # SM4对称密钥


class KeyStatus(Enum):
    """密钥状态"""
    ACTIVE = "active"
    ROTATION_PENDING = "rotation_pending"
    RETIRED = "retired"
    DESTROYED = "destroyed"


@dataclass
class KeyMetadata:
    """密钥元数据"""
    key_id: str
    key_type: KeyType
    status: KeyStatus
    created_at: str
    expires_at: str
    algorithm: str = "SM2"
    key_size: int = 256
    source: str = "local_hsm"  # local_hsm | unified_kms
    extra: Dict = field(default_factory=dict)


class SM4KeyWrapper:
    """
    SM4密钥包装器
    用于保护传输中的密钥材料（密钥加密密钥方案）
    注意：gmssl 3.2.x的crypt_ecb在DECRYPT模式返回空bytes
    因此SM4-CBC使用cryptography库实现
    """

    def __init__(self, kek_key: bytes):
        """
        Args:
            kek_key: 密钥加密密钥（KEK），必须为16字节（SM4-128）
        """
        if len(kek_key) != 16:
            raise ValueError(f"KEK必须为16字节，实际{len(kek_key)}字节")
        self.kek_key = kek_key

    def wrap_key(self, plaintext_key: bytes) -> bytes:
        """使用SM4-CBC加密包装密钥材料"""
        # 生成随机IV
        iv = os.urandom(16)
        # PKCS7填充
        padder = sym_padding.PKCS7(128).padder()
        padded_data = padder.update(plaintext_key) + padder.finalize()
        # SM4-CBC加密
        cipher = Cipher(
            algorithms.SM4(self.kek_key),
            modes.CBC(iv),
            backend=default_backend()
        )
        encryptor = cipher.encryptor()
        ciphertext = encryptor.update(padded_data) + encryptor.finalize()
        # 返回: IV + 密文
        return iv + ciphertext

    def unwrap_key(self, wrapped_key: bytes) -> bytes:
        """解包被SM4-CBC加密的密钥材料"""
        if len(wrapped_key) < 32:  # 至少IV(16) + 一个块(16)
            raise ValueError("wrapped_key长度不足")
        iv = wrapped_key[:16]
        ciphertext = wrapped_key[16:]
        # SM4-CBC解密
        cipher = Cipher(
            algorithms.SM4(self.kek_key),
            modes.CBC(iv),
            backend=default_backend()
        )
        decryptor = cipher.decryptor()
        padded_data = decryptor.update(ciphertext) + decryptor.finalize()
        # 去除PKCS7填充
        unpadder = sym_padding.PKCS7(128).unpadder()
        return unpadder.update(padded_data) + unpadder.finalize()


class KMSAdapter:
    """
    统一密钥管理系统适配层
    负责协调本地HSM与统一密钥管理系统的密钥操作
    """

    def __init__(self, config: dict):
        """
        Args:
            config: 配置字典，包含：
                - kms_endpoint: 统一密钥管理系统API地址
                - kms_token: 认证令牌
                - local_hsm_lib: 本地HSM PKCS#11库路径
                - kek_key_id: KEK密钥ID（存储在HSM中）
                - migration_mode: 迁移模式 (local|hybrid|unified)
        """
        self.kms_endpoint = config["kms_endpoint"]
        self.kms_token = config["kms_token"]
        self.local_hsm_lib = config.get("local_hsm_lib")
        self.kek_key_id = config.get("kek_key_id")
        self.migration_mode = config.get("migration_mode", "hybrid")
        self._key_cache: Dict[str, KeyMetadata] = {}

    def generate_key(
        self,
        key_type: KeyType,
        key_id: str,
        key_usage: str = "sign"
    ) -> KeyMetadata:
        """
        生成密钥对

        根据迁移模式选择不同的密钥生成策略：
        - local: 完全本地HSM生成（迁移前）
        - hybrid: 本地生成，同步上报KMS（迁移中）
        - unified: 请求KMS生成或分发（迁移后）

        Args:
            key_type: 密钥类型
            key_id: 密钥标识符
            key_usage: 密钥用途（sign/encrypt/timestamp）

        Returns:
            KeyMetadata: 密钥元数据
        """
        if self.migration_mode == "local":
            return self._generate_local(key_type, key_id, key_usage)
        elif self.migration_mode == "hybrid":
            return self._generate_hybrid(key_type, key_id, key_usage)
        else:  # unified
            return self._generate_unified(key_type, key_id, key_usage)

    def _generate_local(
        self, key_type: KeyType, key_id: str, key_usage: str
    ) -> KeyMetadata:
        """本地HSM生成密钥（迁移前模式）"""
        logger.info(f"[LOCAL] 本地HSM生成密钥: {key_id}, 类型: {key_type.value}")
        # 实际实现中调用HSM的PKCS#11接口
        # 此处为架构示意
        metadata = KeyMetadata(
            key_id=key_id,
            key_type=key_type,
            status=KeyStatus.ACTIVE,
            created_at=self._now(),
            expires_at=self._now_plus_years(5),
            source="local_hsm",
            extra={"hsm_slot": 0, "key_usage": key_usage}
        )
        self._key_cache[key_id] = metadata
        return metadata

    def _generate_hybrid(
        self, key_type: KeyType, key_id: str, key_usage: str
    ) -> KeyMetadata:
        """
        混合模式生成密钥
        本地HSM生成密钥对，将公钥同步上报KMS，私钥不出HSM
        """
        logger.info(f"[HYBRID] 混合模式生成密钥: {key_id}, 类型: {key_type.value}")

        # Step 1: 本地HSM生成密钥对
        local_meta = self._generate_local(key_type, key_id, key_usage)

        # Step 2: 上报公钥信息到KMS（仅公钥，私钥不离开HSM）
        try:
            self._report_key_to_kms(key_id, key_type, key_usage)
        except Exception as e:
            logger.error(f"上报KMS失败，降级为本地模式: {e}")
            local_meta.extra["kms_sync"] = f"failed: {e}"
            return local_meta

        local_meta.extra["kms_sync"] = "success"
        local_meta.source = "hybrid"
        logger.info(f"[HYBRID] 密钥 {key_id} 已同步上报KMS")
        return local_meta

    def _generate_unified(
        self, key_type: KeyType, key_id: str, key_usage: str
    ) -> KeyMetadata:
        """
        统一模式生成密钥
        请求KMS生成密钥，通过安全通道分发到本地HSM
        """
        logger.info(f"[UNIFIED] 请求KMS生成密钥: {key_id}")

        # Step 1: 向KMS请求密钥生成
        # 实际实现中通过REST API调用KMS
        # response = requests.post(
        #     f"{self.kms_endpoint}/api/key/generate",
        #     headers={"Authorization": f"Bearer {self.kms_token}"},
        #     json={"key_id": key_id, "type": key_type.value, "usage": key_usage}
        # )

        # Step 2: KSM生成密钥后，通过SM4-KEK加密分发到本地HSM
        # 本地HSM解密后存储

        metadata = KeyMetadata(
            key_id=key_id,
            key_type=key_type,
            status=KeyStatus.ACTIVE,
            created_at=self._now(),
            expires_at=self._now_plus_years(5),
            source="unified_kms",
            extra={"kms_managed": True, "key_usage": key_usage}
        )
        self._key_cache[key_id] = metadata
        return metadata

    def rotate_key(self, old_key_id: str) -> Tuple[KeyMetadata, KeyMetadata]:
        """
        密钥轮换
        生成新密钥，将旧密钥标记为轮换待退役

        Returns:
            (new_key_metadata, old_key_metadata)
        """
        old_meta = self._key_cache.get(old_key_id)
        if not old_meta:
            raise KeyError(f"密钥 {old_key_id} 不存在")

        new_key_id = f"{old_key_id}-rot-{self._now()}"
        new_meta = self.generate_key(
            old_meta.key_type, new_key_id,
            old_meta.extra.get("key_usage", "sign")
        )
        old_meta.status = KeyStatus.ROTATION_PENDING
        logger.info(f"密钥轮换: {old_key_id} -> {new_key_id}")
        return new_meta, old_meta

    def destroy_key(self, key_id: str) -> bool:
        """
        密钥销毁
        安全擦除密钥材料，更新状态
        """
        meta = self._key_cache.get(key_id)
        if not meta:
            logger.warning(f"密钥 {key_id} 不存在，无法销毁")
            return False

        # 实际实现中调用HSM的安全擦除接口
        meta.status = KeyStatus.DESTROYED
        logger.info(f"密钥已销毁: {key_id}")
        return True

    def _report_key_to_kms(
        self, key_id: str, key_type: KeyType, key_usage: str
    ) -> dict:
        """上报公钥信息到KMS（实际实现中为HTTP API调用）"""
        # 架构示意：实际通过requests.post发送
        logger.info(f"上报KMS: key_id={key_id}, type={key_type.value}")
        return {"status": "reported", "key_id": key_id}

    @staticmethod
    def _now() -> str:
        from datetime import datetime, timezone
        return datetime.now(timezone.utc).isoformat()

    @staticmethod
    def _now_plus_years(years: int) -> str:
        from datetime import datetime, timezone, timedelta
        # 简化实现：实际应使用dateutil
        dt = datetime.now(timezone.utc) + timedelta(days=years * 365)
        return dt.isoformat()


# 使用示例
if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)

    config = {
        "kms_endpoint": "https://kms.example.gov.cn",
        "kms_token": "your-auth-token",
        "local_hsm_lib": "/usr/lib/libhsm.so",
        "kek_key_id": "kek-001",
        "migration_mode": "hybrid"  # 推荐迁移初期使用hybrid模式
    }

    adapter = KMSAdapter(config)

    # 生成CA签名密钥
    sign_key = adapter.generate_key(
        KeyType.SM2_SIGN, "ca-sign-2026-001", "sign"
    )
    print(f"签名密钥: {sign_key.key_id}, 来源: {sign_key.source}")

    # 生成加密密钥
    enc_key = adapter.generate_key(
        KeyType.SM2_ENCRYPT, "ca-encrypt-2026-001", "encrypt"
    )
    print(f"加密密钥: {enc_key.key_id}, 来源: {enc_key.source}")

    # 密钥轮换
    new_key, old_key = adapter.rotate_key("ca-sign-2026-001")
    print(f"轮换: {old_key.key_id} -> {new_key.key_id}")

    # SM4密钥包装示例
    kek = os.urandom(16)  # 实际应从HSM获取
    wrapper = SM4KeyWrapper(kek)
    secret = b"敏感密钥材料（32字节）" + b"\x00" * 13
    wrapped = wrapper.wrap_key(secret)
    unwrapped = wrapper.unwrap_key(wrapped)
    assert secret == unwrapped, "解包验证失败"
    print("SM4密钥包装验证通过")