Python kms 的 AWS / GCP / Azure 统一封装

不建议手写跨云 kms 封装。因 aws、gcp、azure 在密钥生命周期、权限模型、加密原语及错误码上差异显著，强行抽象会导致维护难、调试难；应仅做路由与凭证管理，保留各平台原生 api 调用。

为什么别自己写跨云 KMS 封装

直接说结论：不建议手写统一的 AWS / GCP / Azure KMS 封装。三者密钥生命周期、权限模型、加密原语支持、错误码体系完全不同，强行抽象一层只会让逻辑更难维护、更难 debug。

比如 AWS KMS 的 encrypt() 默认用对称密钥，GCP KMS 的 encrypt() 要求显式传 plaintext 和 additional_authenticated_data，而 Azure Key Vault 的 encrypt() 实际调的是 wrapKey() 或 encrypt()（取决于算法），且不支持 AEAD 模式。这些差异不是接口名对齐就能掩盖的。

常见错误现象：decrypt() 返回 invalid ciphertext、PermissionDenied: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied、InvalidAlgorithmError: Unsupported algorithm 'RSA_OAEP_2048_SHA256' —— 这些几乎都源于封装层抹平了底层约束，把本该在调用侧检查的参数 / 权限 / 算法兼容性，推到了运行时才暴露。

真要统一封装，只做“路由 + 公共凭证管理”

如果业务确实需要统一入口（比如配置切换云厂商），就只做最薄的一层：根据环境变量或配置决定调哪个 client，并复用认证逻辑。其余全部透传，不加抽象。

立即学习 “Python 免费学习笔记（深入）”；

• AWS 用 boto3.client('kms')，GCP 用 google.cloud.kms_v1.KeyManagementServiceClient()，Azure 用 azure.keyvault.keys.CryptographyClient —— 各自初始化，不共用类
• 公共部分只包括：AWS_ACCESS_KEY_ID / GCP_CREDENTIALS_PATH / AZURE_CLIENT_ID 等凭据加载逻辑，以及统一的密钥 ID 格式解析（如 aws://us-east-1/alias/mykey → 提取 region/alias）
• 加密 / 解密函数签名必须保留各平台原生参数，例如 gcp_encrypt(key_name, plaintext, aad=None) 和 aws_encrypt(key_id, plaintext, encryption_context=None) 分开存在，不合并成一个 encrypt(key_uri, data)

密钥 URI 设计是唯一值得标准化的地方

不同云的密钥标识方式五花八门：AWS 是 ARN 或别名，GCP 是完整资源路径，Azure 是 key URL。统一 URI 格式能减少配置混乱，但必须可逆、无损、不引入歧义。

推荐格式：{provider}://{location}/{key_path}，例如：

aws://us-west-2/alias/app-prod-db-key gcp://us-central1/projects/my-proj/locations/us-central1/keyRings/prod/cryptoKeys/db-key azure://https://myvault.vault.azure.net/keys/db-key

关键点：

• 不尝试把 gcp 的 cryptoKeyVersions/1 版本号塞进 URI —— 版本控制应由调用方显式传参，不是 URI 职责
• azure 的 URI 必须保留完整 HTTPS 地址，因为 Azure Key Vault 不支持 region 级别路由，URL 本身就是 endpoint
• 解析函数不要做网络请求，只做字符串拆分和校验；真正的 client 初始化和调用，留在后续步骤里

测试时最容易漏掉的其实是权限粒度

本地跑通不代表生产可用。三个平台对密钥操作的最小权限要求差异极大，而且错误提示往往模糊。

典型坑：

• AWS：kms:Decrypt 权限必须绑定到密钥策略（Key Policy）+ IAM policy 双重生效，缺一不可；只改 IAM 会报 AccessDeniedException，但实际是 Key Policy 拒绝
• GCP：cloudkms.cryptoKeyVersions.useToDecrypt 是最低权限，但如果你用了 additional_authenticated_data，还必须有 cloudkms.cryptoKeyVersions.viewPublicKey —— 文档里藏得深，不看源码很难发现
• Azure：Key Vault Keys Encrypt 权限只管 encrypt()，wrapKey() 需要单独的 Key Vault Keys Wrap Key 权限；而且角色必须分配给密钥本身，不是整个 vault

真正上线前，每个云环境都要用真实账号跑一次端到端加解密，不能只 mock client。

复杂点不在代码结构，而在权限配置和密钥状态管理——比如 GCP 密钥版本默认是 disabled，Azure 密钥默认 enabled=False，AWS 则没有“禁用版本”概念。这些状态差异，封装层根本没法统一。