Floci KMS 服务深度解析:真实 AES-256-GCM 信封加密、非对称加解密与导入密钥材料全流程

原创2026-09-19 22:19:222,128 阅读
文章标签:云原生测试开发工具本地部署

Floci KMS 服务深度解析:真实 AES-256-GCM 信封加密、非对称加解密与导入密钥材料全流程

Floci(AWS Local Emulator)内置的 KMS 服务以 JSON 1.1 协议(X-Amz-Target: TrentService.*)对外提供 52 个密钥管理操作,覆盖密钥生命周期、授权(Grant)、非对称加解密、HMAC 与 MAC、密钥轮换以及外部密钥材料导入。本指南以该服务为对象,完整讲解其协议端点、操作清单、对称与非对称密码学实现、密文信封二进制格式、外部密钥导入状态机与可观测偏差,并结合源码给出可直接运行的 AWS CLI 实战命令,帮助你在本地开发与测试中获得与真实 AWS KMS 行为高度一致的服务。

协议与端点

KMS 服务遵循 AWS Query/JSON 1.1 风格协议,所有请求通过单一路径投递:

  • Protocol: JSON 1.1(请求头 X-Amz-Target: TrentService.*,其中 * 为具体操作名)
  • Endpoint: POST http://localhost:4566/

请求分发由 KmsJsonHandler.java 完成:handle(String action, JsonNode request, String region) 根据 X-Amz-Target 中的操作名 switch 到对应处理器,未知操作统一返回 UnsupportedOperation(HTTP 400)。区域信息由请求解析层注入,服务内部用 region::<keyId> 作为存储键,天然支持多区域隔离。

支持的 Actions 全景

下表完整列出了 Floci KMS 支持的操作及其语义(与 docs/services/kms.md 一致):

Action Description
CreateKey Create a new KMS key
GenerateRandom Generate random bytes
GetPublicKey Get public key material for asymmetric keys
DescribeKey Get key metadata
ListKeys List all keys
CreateGrant Create a grant for a KMS key
ListGrants List grants for a KMS key
ListRetirableGrants List grants retirable by a principal
RevokeGrant Revoke (administratively delete) a grant
RetireGrant Retire a grant (token- or key+grant-based)
Encrypt Encrypt plaintext with a key
Decrypt Decrypt ciphertext
ReEncrypt Re-encrypt under a different key
GenerateDataKey Generate a data key (plaintext + encrypted)
GenerateDataKeyWithoutPlaintext Generate only the encrypted data key
Sign Sign a message with an asymmetric key
Verify Verify a signature
GenerateMac Generate a MAC with an HMAC key
VerifyMac Verify a MAC with an HMAC key
CreateAlias Create a friendly name for a key
UpdateAlias Repoint an alias at a different key
DeleteAlias Remove an alias
ListAliases List all aliases
ScheduleKeyDeletion Mark a key for deletion
CancelKeyDeletion Cancel pending deletion
TagResource Tag a key
UntagResource Remove tags
ListResourceTags List tags
GetKeyPolicy Get a key's resource policy
PutKeyPolicy Update a key's resource policy
ListKeyPolicies List a key's policy names (always the single default policy)
UpdateKeyDescription Update a key's description
GetKeyRotationStatus Check if automatic key rotation is enabled
EnableKeyRotation Enable automatic key rotation (symmetric keys only)
DisableKeyRotation Disable automatic key rotation
EnableKey Enable a key
DisableKey Disable a key
RotateKeyOnDemand Rotate key material on demand (symmetric keys only)
GetParametersForImport Get the wrapping key and import token for an EXTERNAL key
ImportKeyMaterial Import key material into an EXTERNAL key
DeleteImportedKeyMaterial Delete imported key material, returning the key to PendingImport

请求分发与错误模型(源码印证)

从 KmsJsonHandler.java 的分发表可见,每个 Action 都有独立处理器。错误响应统一走 AwsException → AwsErrorResponse 通道,异常类型(如 ValidationException、InvalidCiphertextException、KMSInvalidStateException、IncorrectKeyException、IncorrectKeyMaterialException、InvalidImportTokenException、ExpiredImportTokenException、InvalidAliasNameException、InvalidMacAlgorithmException、KMSInvalidMacException、LimitExceededException、NotFoundException 等)与真实 KMS 对齐,便于 SDK 与应用的错误处理逻辑在本地即可验证。

密钥创建:KeySpec / KeyUsage / Origin 的组合规则

CreateKey 的实现位于 KmsService.java。处理器层(KmsJsonHandler.java)同时兼容 KeySpec 与旧参数名 CustomerMasterKeySpec,默认值均为 SYMMETRIC_DEFAULT;KeyUsage 默认 ENCRYPT_DECRYPT。

服务层在创建时执行以下校验与初始化:

  • KeyUsage 与 KeySpec 兼容性校验:validateKeyUsageForSpec 依据 KmsKeySpec.allowedKeyUsages() 检查组合合法性,非法组合抛 ValidationException。
  • 默认策略生成:未显式传入 Policy 时,buildDefaultKeyPolicy 会生成以当前账户 arn:aws:iam::<account>:root 为 Principal、kms:* 全权限的标准默认策略。
  • 材料生成(generateKeyMaterial,KmsService.java):按 KmsKeySpec.KeyType 分支——
    • SYMMETRIC:生成 32 字节 AES-256 backing key(见下文信封机制);
    • HMAC:生成与规格匹配长度的随机字节串(如 HMAC_384 为 48 字节);
    • RSA(2048/3072/4096)、ED25519、ML_DSA、ECC(含 ECC_SECG_P256K1 与 SM2)、SM2:生成真实密钥对并持久化私钥(Base64 编码)。
    • SM2 规格仅在 cn-north-1 / cn-northwest-1 区域被接受,其他区域返回 UnsupportedOperationException,与真实 AWS 的区域限制一致。
  • Origin 解析(resolveOrigin):支持 AWS_KMS 与 EXTERNAL;AWS_CLOUDHSM、EXTERNAL_KEY_STORE 明确返回 UnsupportedOperationException,未知值返回 ValidationException。Origin=EXTERNAL 时新建密钥直接进入 PendingImport 状态且 enabled=false,等待材料导入(见下文)。
  • 确定性 KeyId:resolveKeyId 支持通过保留标签 floci:override-id 指定 KeyId(详见"测试辅助特性"一节),未指定时使用随机 UUID。

非对称加密:真实 RSAES-OAEP

对于 RSA 密钥(RSA_2048、RSA_3072、RSA_4096),Encrypt、Decrypt、ReEncrypt 执行真实的 RSAES-OAEP 运算,前提是 EncryptionAlgorithm 为 RSAES_OAEP_SHA_1 或 RSAES_OAEP_SHA_256。其行为与真实 AWS KMS 对齐的关键点:

  • 密文长度:输出为模数长度的原始 RSA 密文,例如 RSA_2048 恰好 256 字节。
  • 互操作性:用 GetPublicKey 取得的公钥在本地(任何标准 OpenSSL / Java / Go 实现)加密得到的结果,可以在 Floci 中用 Decrypt 解开;反之亦然。经典信封加密模式(envelope pattern)在本地即可端到端跑通。
  • 只需公钥加密:只有加密方需要公钥,私钥永不出服务。
  • 行为约束(与 AWS 一致):非对称 Decrypt 必须携带 KeyId(原始 RSA 密文不内嵌密钥元数据);对非对称密钥传入 EncryptionContext 会被拒绝(ValidationException);明文超过该密钥 OAEP 容量时校验失败。

OAEP 容量与长度校验在 KmsService.java 中实现:按 RFC 8017 7.1.1,OAEP 最多容纳 k - 2*hLen - 2 字节(k 为模数字节数:2048→256、3072→384、4096→512;SHA-1 时 hLen=20,SHA-256 时 hLen=32)。RSA-OAEP 的具体实现(rsaOaep)显式构造 OAEPParameterSpec,将 MGF1 摘要固定为与主摘要相同(SHA-256 对应 MGF1-SHA256),规避了 JDK 命名变换默认 MGF1-SHA1 的问题;解密失败统一收敛为 InvalidCiphertextException,不向调用方泄露"字节是垃圾、长度错误还是密钥不匹配"的差异。

对称密钥(SYMMETRIC_DEFAULT)走服务内置密文信封格式,该格式与真实 AWS KMS 的密文不兼容,详见下一节。

对称密文信封:真实 AES-256-GCM 与版本化二进制布局

Encrypt、Decrypt、ReEncrypt、GenerateDataKey 对 SYMMETRIC_DEFAULT 明文使用真实的 AES-256-GCM 保护。加密所用的数据加密密钥("backing key")按密钥独立生成——密钥创建时即产生,或为 Origin=EXTERNAL 密钥导入的材料,且任何 API 都不会暴露该材料。

对外,密文与真实 KMS 一样是 base64 编码的不透明字节;对内则是一个带版本的二进制信封(KmsService.java 的常量定义与 encryptEnvelope 的实现):

offset      size  field
0           4     magic "KMS3" (0x4B 0x4D 0x53 0x33)
4           1     format version (currently 1)
5           2     key id length (big-endian unsigned short)
7           N     key id (UTF-8)
7+N         2     backing key id length (big-endian unsigned short)
9+N         M     backing key id (UTF-8)
9+N+M       12    AES-GCM IV (random, generated per call)
21+N+M      ...   AES-256-GCM ciphertext, followed by the 16-byte GCM tag

设计要点:

  • KeyId 自描述:信封头内嵌 key id,使 Decrypt 仅凭密文即可定位密钥——与真实 KMS 一致,对称密钥解密不需要 KeyId 参数。
  • 完整 AAD 绑定:GCM 的附加认证数据(AAD)为"从头部到 IV 为止的全部字节"加上"规范化 EncryptionContext 的 SHA-256 指纹"(contextFingerprint,见 KmsService.java,按排序后的键值对做长度前缀序列化后哈希,空上下文指纹为空串)。因此:用错误的密钥、错误的 backing key 版本、错误的 EncryptionContext,或密文任意位置(头部、IV、密文、标签)发生比特翻转,都会以同样的方式触发 GCM 标签校验失败,统一呈现为 InvalidCiphertextException,绝不会返回明文。
  • 头部即认证数据:aadHeader 是"直到并包含 IV 的全部字节"(EnvelopeV3),被篡改的 key id / backing key id 会直接导致 GCM 校验失败,而不是"静默地用错误的材料解密"。
  • 解析健壮性:任何畸形头部(长度前缀错误、截断、未知版本号)都归类为坏密文(InvalidCiphertextException),而非服务端错误(500)。

密钥轮换与旧 backing key 保留

RotateKeyOnDemand(KmsService.java)会铸造新的 backing key 并将后续加密切换到它,但保留密钥状态中的旧 backing key,因此轮换前加密的密文在轮换后仍可解密——与真实 KMS 保留历史 backing key 的行为一致。每把密钥的按需轮换有配额限制(ON_DEMAND_ROTATION_LIMIT = 25,超限抛 LimitExceededException);密钥处于禁用状态时抛 DisabledException;自动轮换与按需轮换都仅对 SYMMETRIC_DEFAULT + ENCRYPT_DECRYPT 且 Origin=AWS_KMS 的密钥开放(validateRotationSupported,KmsService.java),对导入材料密钥抛 UnsupportedOperationException。

遗留 blob 格式(只读兼容)

Decrypt 为向后兼容仍接受两种更早的、未认证的格式,但 Encrypt 已不再产生它们:

  • kms:v2:<keyId>:<nonceHex>:<contextFingerprintHex>:<base64(plaintext)>
  • kms:<keyId>:<base64(plaintext)>

两种格式都没有使用真实密钥材料:负载就是 base64 编码的明文本身,因此持有 v1/v2 blob 的人可以直接读出明文,篡改后的 blob 也仍能"解密"出原始值。任何已按此形状持久化的密文(例如本修复之前存入数据库的数据)仍可继续解密,避免既有数据被孤立;但新的 Encrypt 调用一律产出上文描述的 AES-GCM 信封。

惰性自愈:在 backing key 机制存在之前创建的密钥,其 JSON 中没有 backingKeys/currentBackingKeyId 字段。ensureBackingKeyMaterial(KmsService.java)在密钥首次用于密码学操作时惰性生成 backing key 材料并立即持久化。该方法采用双重检查锁定(double-checked locking,backingKeyMaterialLock)防止并发首次使用时各自铸造不同的 backing key:未自愈的密钥才进入同步块,并在块内重新读取、复查后才生成,保证无论多少并发首次使用,最终只有一份 backing key 被持久化。

导入密钥材料:EXTERNAL Origin 的完整状态机

CreateKey 接受 Origin=EXTERNAL,创建一把没有任何密钥材料、状态为 PendingImport 的密钥。随后按真实 KMS 的三步流程完成导入:

  1. GetParametersForImport:返回一把真实的 RSA 公钥(作为 wrapping key)与一个 import token(KmsService.java)。wrapping key 对的生成与算法校验在 KmsKeyImport.java。
  2. 客户端包装:标准客户端(AWS CLI / SDK)用该公钥包装密钥材料。
  3. ImportKeyMaterial:服务端用保留的私钥解包,成功后将密钥置为 Enabled(KmsService.java)。

支持参数与约束:

  • WrappingAlgorithm:RSAES_OAEP_SHA_256 与 RSAES_OAEP_SHA_1;RSAES_PKCS1_V1_5 被拒绝——与 AWS 一致,后者已于 2023 年 10 月 10 日停止支持。RSA_AES_KEY_WRAP_* 变体用于包装超过 RSA 模数容量的材料,本模拟器中可导入的密钥规格材料最长 64 字节,无需此类变体,同样被拒绝(UnsupportedOperationException)。
  • WrappingKeySpec:RSA_2048、RSA_3072、RSA_4096。
  • 解包失败统一报错:用错误的密钥包装、或用与请求不同的算法包装,一律返回 InvalidCiphertextException,与 AWS 一致,不向调用方区分失败原因(KmsKeyImport.java)。
  • Token 一次性:import token 与一把密钥绑定,被使用它的那次导入"消费"掉;再次调用 GetParametersForImport 会使之前发放的 token 失效;token 签发后 24 小时过期(IMPORT_PARAMETERS_VALIDITY),过期后 ImportKeyMaterial 返回 ExpiredImportTokenException。
  • ExpirationModel:默认 KEY_MATERIAL_EXPIRES,此时必须提供 ValidTo——必须是未来时间且不超过 365 天(validateValidTo,KmsService.java);KEY_MATERIAL_DOES_NOT_EXPIRE 则禁止携带 ValidTo。
  • 过期语义:ValidTo 到达后材料被丢弃、密钥回到 PendingImport,与 DeleteImportedKeyMaterial 效果一致。过期判断在密钥下次被读取时惰性执行(expireImportedKeyMaterialIfDue,KmsService.java),而非定时器驱动——服务对外不可观测到这种差异。对已处于 PendingDeletion 的密钥删除材料,不会改变其删除中的状态。
  • SYMMETRIC_DEFAULT 导入材料的身份:导入材料本身就是信封中命名的 backing key,服务不会为密钥再生成任何其他材料。删除或过期材料即移除该 backing key,只有重新导入相同的材料,此前产出的密文才能再次解密。
  • 材料身份校验:KeyMaterialId 由 key id 与材料本身派生(keyMaterialId = SHA-256(keyId ‖ material),KmsService.java),ImportKeyMaterial 与 DeleteImportedKeyMaterial 均返回它。重新导入必须携带与首次导入完全相同的材料,不同材料被拒并返回 IncorrectKeyMaterialException。
  • 状态机约束:PendingImport 状态的密钥拒绝密码学操作、EnableKey、DisableKey(KMSInvalidStateException);从未导入材料(或材料在待删除期间被删除/过期)的密钥,CancelKeyDeletion 会回到 PendingImport 而非一个无法服务的可用状态;对没有材料的密钥执行 DeleteImportedKeyMaterial 成功返回(与 AWS 相同)。
  • 自动轮换被拒:KMS 不拥有导入材料、无法代为轮换,因此对导入材料密钥启用自动轮换会被拒绝,与 AWS 一致。

已知偏差(Deviations)

  • Origin=EXTERNAL 仅支持 SYMMETRIC_DEFAULT 与 HMAC_* 规格(材料为原始字节串)。真实 AWS KMS 还支持以 DER 编码密钥对导入非对称材料;本模拟器在 CreateKey 阶段即以 UnsupportedOperationException 拒绝"非对称规格 + EXTERNAL"组合,而不是创建一把永远无法签名/解密的密钥(requireImportableSpec,KmsService.java)。
  • 真实 KMS 通过在同一对称密钥上持有多个导入材料实现导入材料的按需轮换,此能力未模拟:对已有材料的密钥再次 ImportKeyMaterial(ImportType=NEW_KEY_MATERIAL)返回 UnsupportedOperationException;ListKeyRotations 未实现(validateImportType,KmsService.java)。

Grant 支持范围:生命周期完整,授权不生效

Grant 生命周期操作(CreateGrant、ListGrants、ListRetirableGrants、RevokeGrant、RetireGrant)均已支持,但生命周期支持不等于基于 Grant 的授权强制执行:加密类操作(Encrypt、Decrypt、Sign、Verify、GenerateDataKey 等)执行时不会评估 Grant。Grant 可被创建、存储与查询,但在密码学操作中不生效。

从源码看,createGrant 会做与 AWS 一致的参数校验:Operations 必须是 GRANT_OPERATIONS 枚举成员(KmsService.java 定义了来自 kms/2014-11-01 service-2.json 的 17 个操作);Name 需匹配 ^<a href="https://link.gitcode.com/i/e22527ea9d7483cb95a962e8af888bc8" target="_blank">a-zA-Z0-9:/_-]+$ 且长度 1–256;Constraints 仅接受 EncryptionContextSubset、EncryptionContextEquals、SourceArn 三个成员并校验类型与 ARN 正则。ListGrants / ListRetirableGrants 支持 Marker + Limit 分页(默认 50、上限 100),NextMarker 为 base64 编码的最后一个 GrantId,非法 marker 返回 InvalidMarkerException。RetireGrant 同时支持基于 token 与基于 KeyId+GrantId 两种路径([KmsService.java)。

配置

Variable Default Description
FLOCI_SERVICES_KMS_ENABLED true Enable or disable the service

将该环境变量设为 false 可整体禁用 KMS 服务。服务数据的持久化由存储层完成:密钥、别名、Grant 分别落在 kms-keys.json、kms-aliases.json、kms-grants.json(KmsService.java),具体文件位置与存储后端配置见 docs/configuration/storage.md。

实战示例

以下命令完整演示"建密钥 → 建别名 → 加密 → 解密 → 生成数据密钥"的闭环,可直接在 Floci 本地端点(默认 localhost:4566)上运行:

export AWS_ENDPOINT_URL=http://localhost:4566

# Create a symmetric key
KEY_ID=$(aws kms create-key \
  --description "My encryption key" \
  --query KeyMetadata.KeyId --output text \
  --endpoint-url $AWS_ENDPOINT_URL)

# Create an alias
aws kms create-alias \
  --alias-name alias/my-key \
  --target-key-id $KEY_ID \
  --endpoint-url $AWS_ENDPOINT_URL

# Encrypt
CIPHER=$(aws kms encrypt \
  --key-id alias/my-key \
  --plaintext "Hello, World!" \
  --query CiphertextBlob --output text \
  --endpoint-url $AWS_ENDPOINT_URL)

# Decrypt
aws kms decrypt \
  --ciphertext-blob $CIPHER \
  --query Plaintext --output text \
  --endpoint-url $AWS_ENDPOINT_URL | base64 --decode

# Generate a data key (envelope encryption)
aws kms generate-data-key \
  --key-id alias/my-key \
  --key-spec AES_256 \
  --endpoint-url $AWS_ENDPOINT_URL

要点说明:

  • aws kms 命令通过 --endpoint-url 指向 Floci 端点;AWS_ENDPOINT_URL 是 AWS CLI v2 的统一端点环境变量,二者择一即可。
  • Encrypt 输出 CiphertextBlob 为 base64 文本;Decrypt 返回的 Plaintext 也是 base64,需要用 base64 --decode 还原。
  • generate-data-key --key-spec AES_256 返回的响应同时包含 Plaintext(明文字节,本地使用后用掉即可)与 CiphertextBlob(可交由 KMS 解密)。
  • 别名(alias)在 resolveKey 中统一解析:既支持 alias/xxx 与完整别名 ARN(arn:...:alias/xxx),也支持 key id 与 key ARN(.../key/<id>)。UpdateAlias 要求新旧目标密钥"同族"(同为对称、同为非对称或同为 HMAC),与 AWS 规则一致(sameKeyFamily,KmsService.java)。

导入外部密钥材料示例

三步导入流程可完全用 AWS CLI 完成:

export AWS_ENDPOINT_URL=http://localhost:4566

# 1) 创建 EXTERNAL 密钥(状态 PendingImport)
KEY_ID=$(aws kms create-key --origin EXTERNAL \
  --key-spec SYMMETRIC_DEFAULT \
  --query KeyMetadata.KeyId --output text \
  --endpoint-url $AWS_ENDPOINT_URL)

# 2) 获取 wrapping key 公钥与 import token(默认 RSAES_OAEP_SHA_256 / RSA_2048)
aws kms get-parameters-for-import \
  --key-id $KEY_ID \
  --wrapping-algorithm RSAES_OAEP_SHA_256 \
  --wrapping-key-spec RSA_2048 \
  --endpoint-url $AWS_ENDPOINT_URL > import-params.json
# 从响应中提取 ImportToken 与 PublicKey(Base64),并用标准工具包装 32 字节材料

# 3) 导入材料,密钥转为 Enabled
aws kms import-key-material \
  --key-id $KEY_ID \
  --import-token <token> \
  --encrypted-key-material fileb://EncryptedMaterial.bin \
  --expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE \
  --endpoint-url $AWS_ENDPOINT_URL

注意事项(源码确认):token 24 小时有效且一次性;ImportKeyMaterial 返回的 KeyMaterialId 派生自 key id 与材料;同一材料可再次导入,不同材料被拒(IncorrectKeyMaterialException);DeleteImportedKeyMaterial 后密钥回到 PendingImport。

测试辅助特性:floci:override-id

CreateKey 还接受一个保留的创建时标签 floci:override-id,供测试需要确定性 KeyId 时使用:

  • Floci 将该标签值直接用作创建的密钥 id(resolveKeyId,KmsService.java),空白值(400,TagException)与超过 256 字符的值均被拒绝;
  • 该保留标签会从存储的资源标签中剥离(ReservedTags.stripReservedTags);
  • 后续通过 TagResource 添加任何 floci:* 标签都会被拒绝(ReservedTags.rejectReservedTagsOnUpdate,见 KmsService.java)。

测试与验证矩阵

Floci 仓库为 KMS 提供了多语言、多工具链的验证覆盖,可作为行为契约参考:

这些测试共同印证:Floci KMS 的对外行为以"与真实 AWS KMS 尽可能一致"为设计目标——包括错误类型、参数约束、密文语义与状态机边界,同时明确标注了不支持的能力(如非对称材料导入、多材料轮换、Grant 授权强制)以免误导使用者。

登录后查看全文
floci