nsmithuk/local-kms

Local KMS (LKMS)

镜像概述

Local KMS (LKMS) 是AWS Key Management Service (KMS)的模拟实现，专为本地开发和测试设计，采用Go语言编写。该镜像支持真实加密算法（AES、ECDSA、RSA），但仅用于开发测试环境，不可用于生产环境。

核心功能和特性

支持功能

• 密钥类型：
  • 对称密钥（AES）
  • 非对称密钥（ECC_NIST和RSA）
• 客户主密钥（CMK）管理：
  • 启用/禁用密钥
  • 计划密钥删除
  • 启用/禁用自动密钥轮换
• 密钥别名管理
• 加密操作：
  • 支持加密上下文（Encryption Contexts）
• 解密操作
• 数据密钥生成：
  • 带或不带明文的数据密钥
  • 带或不带明文的数据密钥对
• 随机数据生成
• 密钥材料导入
• 消息签名与验证：
  • 支持RAW和DIGEST模式
• 标签管理
• 密钥策略：支持Get和Put操作
• 种子功能：启动时加载预定义密钥和别名，提供确定性、可版本化的测试密钥管理（已存在的密钥不会被覆盖）

暂不支持功能

• ECC_SECG_P256K1密钥
• 授权（Grants）
• 自定义密钥存储相关操作

使用场景和适用范围

适用于需要与AWS KMS交互的应用程序的本地开发和测试，可替代真实AWS KMS服务，避免产生云服务费用，同时提供可控、可重复的测试环境。

使用方法和配置说明

快速启动（Docker）

基本运行

bash
docker run -p 8080:8080 docker.xuanyuan.run/nsmithuk/local-kms

LKMS将在8080端口启动，默认配置下无需额外参数。

种子文件挂载

通过挂载包含seed.yaml的目录，实现启动时加载预定义密钥：

bash
docker run -p 8080:8080 \
--mount type=bind,source="$(pwd)"/init,target=/init \
docker.xuanyuan.run/nsmithuk/local-kms

容器默认在/init/seed.yaml路径查找种子文件。

数据持久化

通过挂载/data目录，实现密钥数据在容器重启后保留：

bash
docker run -p 8080:8080 \
--mount type=bind,source="$(pwd)"/data,target=/data \
docker.xuanyuan.run/nsmithuk/local-kms

种子文件格式

种子文件采用YAML格式，支持对称密钥（AES）和非对称密钥（ECC、RSA）定义，以及密钥别名配置。

简单示例

yaml
Keys:
  Symmetric:
    Aes:
      - Metadata:
          KeyId: bc436485-5092-42b8-92a3-0aa8b93536dc
        BackingKeys:
          - 5cdaead27fe7da2de47945d73cd6d79e36494e73802f3cd3869f1d2cb0b5d7a9
  Asymmetric:
    Ecc:
      - Metadata:
          KeyId: 800d5768-3fd7-4edd-a4b8-4c81c3e4c147
          KeyUsage: SIGN_VERIFY
          Description: ECC key with curve secp256r1
        PrivateKeyPem: |
          -----BEGIN EC PRIVATE KEY-----
          MHcCAQEEIMnOrUrXr8rwne7d8f01cfwmpS/w+K7jcyWmmeLDgWKaoAoGCCqGSM49
          AwEHoUQDQgAEYNMBBZ3h1ipuph1iO5k+yLvTs94UN71quXN3f0P/tprs2Fp2FEas
          M7m7XZ2xlDK3wcEAs1QEIoQjjwnhcptQ6A==
          -----END EC PRIVATE KEY-----

Aliases:
  - AliasName: alias/testing
    TargetKeyId: bc436485-5092-42b8-92a3-0aa8b93536dc

多密钥示例

yaml
Keys:
  Symmetric:
    Aes:
      - Metadata:
          KeyId: bc436485-5092-42b8-92a3-0aa8b93536dc
        BackingKeys:
          - 34743777217A25432A46294A404E635266556A586E3272357538782F413F4428
          - 614E645267556B58703273357638792F423F4528472B4B6250655368566D5971
      - Metadata:
          KeyId: 49c5492b-b1bc-42a8-9a5c-b2015e810c1c
        BackingKeys:
          - 5cdaead27fe7da2de47945d73cd6d79e36494e73802f3cd3869f1d2cb0b5d7a9

Aliases:
  - AliasName: alias/dev
    TargetKeyId: bc436485-5092-42b8-92a3-0aa8b93536dc
  - AliasName: alias/test
    TargetKeyId: 49c5492b-b1bc-42a8-9a5c-b2015e810c1c

可选字段说明

• Metadata -> Description：密钥描述（自由文本）
• Metadata -> Origin：密钥来源，设为EXTERNAL时表示导入自定义密钥材料，此时BackingKeys可选（最多1个256位十六进制密钥）
• Metadata -> KeyUsage：非对称密钥用途，ECC仅支持SIGN_VERIFY，RSA支持SIGN_VERIFY或ENCRYPT_DECRYPT
• NextKeyRotation：AES密钥专用，ISO 8601格式日期，用于设置自动轮换时间（若日期已过，首次访问时触发轮换）

环境变量配置

注意：密钥和别名基于ARN存储，包含账户ID和区域信息，修改KMS_ACCOUNT_ID或KMS_REGION会导致现有数据不可访问。

与AWS KMS的已知差异

调用ScheduleKeyDeletion时，AWS返回的时间戳采用科学计数法（如1.5565824E9），而LKMS返回整数形式（如1556582400）。两者在JSON解析中等效，不影响AWS SDK使用。

使用示例

使用CLI（awslocal）

创建客户主密钥

bash
awslocal kms create-key

加密数据

bash
awslocal kms encrypt \
--key-id 0579fe9c-129b-490a-adb0-42589ac4a017 \
--plaintext "My Test String"

解密数据

bash
awslocal kms decrypt \
--ciphertext-blob fileb://encrypted.dat

生成数据密钥

bash
awslocal kms generate-data-key \
--key-id 0579fe9c-129b-490a-adb0-42589ac4a017 \
--key-spec AES_128

使用HTTPie

创建客户主密钥

bash
http -v --json POST http://localhost:8080/ \
X-Amz-Target:TrentService.CreateKey

加密数据（Base64编码）

bash
http -v --json POST http://localhost:8080/ \
X-Amz-Target:TrentService.Encrypt \
KeyId=f154ba79-0b7d-4f19-9983-309f706ebc83 \
Plaintext='SGVsbG8='

解密数据

bash
http -v --json POST http://localhost:8080/ \
X-Amz-Target:TrentService.Decrypt \
CiphertextBlob='S2Fybjphd3M6a21zOmV1LXdlc3QtMjoxMTExMjIyMjMzMzM6a2V5L2YxNTRiYTc5LTBiN2QtNGYxOS05OTgzLTMwOWY3MDZlYmM4MwAAAABjIzzp52djy/L4prvuGoG+jZ6OJzgQGi6n2CRO5dmfJHw='

生成种子文件非对称密钥

RSA密钥生成函数

bash
function rsakey(){
local bits=$1
if ! [[ "$bits" =~ ^(2048|3072|4096)$ ]];
then
   echo "RSA密钥长度必须为：2048 3072 4096"
   return
fi

keyId=$(uuidgen | tr '[:upper:]' '[:lower:]')
echo "
Keys:
  Asymmetric:
    Rsa:
      - Metadata:
          KeyId: ${keyId}
          KeyUsage: SIGN_VERIFY # 或 ENCRYPT_DECRYPT
          Description: ${bits}位RSA密钥
        PrivateKeyPem: |
$(openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:${bits} -pkeyopt rsa_keygen_pubexp:65537 | sed 's/^/          /')
"
}

使用：rsakey 2048（生成2048位RSA密钥）

ECC密钥生成函数

bash
function ecckey(){
local curve=$1
if ! [[ "$curve" =~ ^(secp256r1|secp384r1|secp521r1)$ ]];
then
   echo "曲线必须为：secp256r1 secp384r1 secp521r1"
   return
fi
keyId=$(uuidgen | tr '[:upper:]' '[:lower:]')

echo "
Keys:
  Asymmetric:
    Ecc:
      - Metadata:
          KeyId: ${keyId}
          KeyUsage: SIGN_VERIFY
          Description: ${curve}曲线ECC密钥
        PrivateKeyPem: |
$(openssl ecparam -name ${curve} -genkey -noout | sed 's/^/          /')
"
}

使用：ecckey secp256r1（生成secp256r1曲线ECC密钥）

许可证

本项目采用MIT许可证，详见LICENSE文件。