Floci KMS 服务深度解析:真实 AES-256-GCM 信封加密、非对称加解密与导入密钥材料全流程
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 的三步流程完成导入:
GetParametersForImport:返回一把真实的 RSA 公钥(作为 wrapping key)与一个 import token(KmsService.java)。wrapping key 对的生成与算法校验在 KmsKeyImport.java。- 客户端包装:标准客户端(AWS CLI / SDK)用该公钥包装密钥材料。
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 提供了多语言、多工具链的验证覆盖,可作为行为契约参考:
- 单元测试:KmsServiceTest.java 覆盖服务层的参数校验与状态机;KmsIntegrationTest.java 覆盖 HTTP 层集成行为。
- AWS CLI 兼容性:compatibility-tests/sdk-test-awscli/test/kms.bats 用 Bats 断言了 create/describe/list key、create/list alias、encrypt/decrypt、generate-data-key 等操作的 CLI 行为(含加解密往返的字节级校验)。
- Go SDK:compatibility-tests/sdk-test-go/tests/kms_test.go 验证 AWS SDK for Go 的调用路径。
- Java / Node / Python SDK:
sdk-test-java、sdk-test-node(kms.test.ts、kms-features.test.ts)、sdk-test-python(test_kms.py)各有对应覆盖。 - Terraform / OpenTofu 兼容性:compatibility-tests/compat-terraform/test/kms-update-alias-tf/main.tf 验证
aws_kms_alias的update_alias流程在 Terraform Provider 下的兼容表现。
这些测试共同印证:Floci KMS 的对外行为以"与真实 AWS KMS 尽可能一致"为设计目标——包括错误类型、参数约束、密文语义与状态机边界,同时明确标注了不支持的能力(如非对称材料导入、多材料轮换、Grant 授权强制)以免误导使用者。