AWS EmulatorのKMSで、文字列を暗号化して元に戻す方法

​​AWS Emulator​AWS CLI,AWS KMS

AWS Emulator を手元で動かすと、AWS KMS の鍵を作り、文字列を暗号化して、元に戻すまでを AWS のアカウントなしで試せます。データベースのパスワードや API キーのような短い秘密の文字列を KMS で暗号化して保存するプログラムがあり、それをローカル環境や CI でテストしたいときに使える手順です。AWS CLI v2 では、暗号文も復号の結果も base64 で出てくるので、どこで base64 を戻すかもあわせて確かめます。

補足

検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.385(2026年11月14日リリース)、AWS CLI 2.40.3 です。AWS のアカウントと認証情報は使っていません。本物の AWS KMS での動きと料金は確かめておらず、記事で触れるところは公式ドキュメントを出どころにしています。エミュレーターは IAM ポリシーやキーポリシーを AWS と同じようには評価しないと公式ドキュメントに書かれているので、権限まわりは扱いません。暗号化と復号に使ったのは対称鍵(SYMMETRIC_DEFAULT)だけで、非対称鍵、データキー(GenerateDataKey)、SDK(Boto3 など)からの呼び出しは試していません。

エミュレーターを起動して、AWS CLI を向ける

AWS Emulator の入れ方は公式の Linux 向けの手順のとおりです。起動は aws-emulator で、-t off はテレメトリーを切る指定です。

bash
aws-emulator -t off

エミュレーターを動かしたまま別の端末を開き、公式ドキュメントにある環境変数を設定して、AWS CLI の送り先と認証情報をエミュレーターに向けます。

bash
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

aws sts get-caller-identity の ARN が user/emulator になっていれば、エミュレーターに届いています。以下の出力では、12桁のアカウントIDを <12桁のアカウントID> に置き換えています。

text
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator

鍵を作って、エイリアスを付ける

起動した直後は、鍵が1つもありません。create-key で鍵を作ります。何も指定しないと、暗号化と復号に使う対称鍵(KeyUsage が ENCRYPT_DECRYPT、KeySpec が SYMMETRIC_DEFAULT)になりました。

text
$ aws kms list-keys
{
    "Keys": []
}
$ aws kms create-key --description "example key"
{
    "KeyMetadata": {
        "AWSAccountId": "<12桁のアカウントID>",
        "KeyId": "fa0de1b9-36eb-45b7-bedb-8db7f984fc9f",
        "Arn": "arn:aws:kms:us-east-1:<12桁のアカウントID>:key/fa0de1b9-36eb-45b7-bedb-8db7f984fc9f",
        "CreationDate": "2026-11-15T01:48:10.733000+00:00",
        "Enabled": true,
        "Description": "example key",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "CUSTOMER",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "MultiRegion": false,
        "CurrentKeyMaterialId": "e23ae03ba4870a5b805d72de94faba8d0a5fcacbe68f81f5ff29aac579daa1a8"
    }
}

以下のコマンドでは、ここで作られた鍵 ID(fa0de1b9-…)をそのまま書いています。手元で試すときは、自分の環境で出た鍵 ID に置き換えてください。鍵 ID は作るたびに変わるので、プログラムやテストからは覚えやすい名前で呼べるように、エイリアスを付けておきます。create-alias は成功しても何も出力しません。

text
$ aws kms create-alias --alias-name alias/example-key --target-key-id fa0de1b9-36eb-45b7-bedb-8db7f984fc9f
$ aws kms list-aliases
{
    "Aliases": [
        {
            "AliasName": "alias/example-key",
            "AliasArn": "arn:aws:kms:us-east-1:<12桁のアカウントID>:alias/example-key",
            "TargetKeyId": "fa0de1b9-36eb-45b7-bedb-8db7f984fc9f",
            "CreationDate": "2026-11-15T01:48:12.065000+00:00",
            "LastUpdatedDate": "2026-11-15T01:48:12.065000+00:00"
        }
    ]
}

Encrypt のリファレンスによると、鍵は鍵 ID、鍵の ARN、エイリアス名、エイリアスの ARN のどれで指定してもよく、エイリアス名には alias/ を付けます。以下では alias/example-key で指定します。

文字列を暗号化する

暗号化する文字列を、改行を付けずにファイルに書いておきます。日本語を含めて31バイトです。

text
$ printf %s "パスワード: example-secret" > plain.txt; wc -c plain.txt
31 plain.txt

encrypt の --plaintext には fileb:// を付けてファイルを渡します。AWS CLI でファイルからパラメーターを読む方法の説明では、バイナリのデータを渡すときは fileb:// を使うことになっています。

text
$ aws kms encrypt --key-id alias/example-key --plaintext fileb://plain.txt
{
    "CiphertextBlob": "ASRmYTBkZTFiOS0zNmViLTQ1YjctYmVkYi04ZGI3Zjk4NGZjOWbHzNzdVpje7z7lFLDPx7qUyf531jjCIVAT/Kj4tMKuzuJPLH60wOf1bRgvFRPcqX6pkui6I93xMop0DQ==",
    "KeyId": "arn:aws:kms:us-east-1:<12桁のアカウントID>:key/fa0de1b9-36eb-45b7-bedb-8db7f984fc9f",
    "EncryptionAlgorithm": "SYMMETRIC_DEFAULT"
}

CiphertextBlob が暗号文です。Encrypt のリファレンスにあるとおり、AWS CLI では base64 の文字列で出てきます。保存するときは、--query で取り出して base64 -d でバイナリに戻しておくと、復号のときにそのまま fileb:// で渡せます。検証環境では97バイトのファイルになりました。

text
$ aws kms encrypt --key-id alias/example-key --plaintext fileb://plain.txt --query CiphertextBlob --output text | base64 -d > cipher.bin; wc -c cipher.bin
97 cipher.bin

復号して、元の文字列に戻す

decrypt には、暗号文のファイルを fileb:// で渡します。対称鍵で暗号化したときは、鍵を指定しなくても復号できました。

text
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin
{
    "KeyId": "arn:aws:kms:us-east-1:<12桁のアカウントID>:key/fa0de1b9-36eb-45b7-bedb-8db7f984fc9f",
    "Plaintext": "44OR44K544Ov44O844OJOiBleGFtcGxlLXNlY3JldA==",
    "EncryptionAlgorithm": "SYMMETRIC_DEFAULT",
    "KeyMaterialId": "e23ae03ba4870a5b805d72de94faba8d0a5fcacbe68f81f5ff29aac579daa1a8"
}

復号の結果の Plaintext も base64 です。base64 -d で戻すと、元の文字列が出てきました。cmp で比べても、plain.txt と1バイトも違いません。

text
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin --query Plaintext --output text | base64 -d; echo
パスワード: example-secret
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin --query Plaintext --output text | base64 -d | cmp - plain.txt && echo "plain.txt と同じ"
plain.txt と同じ
元の文字列を encrypt で base64 の CiphertextBlob にし、base64 -d で97バイトの cipher.bin にする。それを decrypt で base64 の Plaintext にし、base64 -d で元の文字列に戻す流れを、上から下に並べた図
暗号化から復号までの流れ。base64 の文字列とバイナリを変換する場所を示した(検証環境の出力から作図)

Decrypt のリファレンスによると、対称鍵の暗号文には、どの鍵で暗号化したかの情報が入っているので、--key-id は省けます。ただし、鍵を指定するのがベストプラクティスとされています。指定すると、その鍵しか使わず、別の鍵で暗号化された暗号文なら失敗するからです。

検証環境でも、もう1つ鍵を作って --key-id に指定すると IncorrectKeyException になり、暗号化に使ったエイリアスを指定すると復号できました。でたらめなバイト列(garbage の7バイト)を渡したときは InvalidCiphertextException でした。

text
$ aws kms create-key --description "other key" --query KeyMetadata.KeyId --output text
fc24a77c-cb05-4928-9b2c-e73613d5afd2
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin --key-id fc24a77c-cb05-4928-9b2c-e73613d5afd2

aws: [ERROR]: An error occurred (IncorrectKeyException) when calling the Decrypt operation: The key ID in the request does not identify a CMK that can perform this operation.
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin --key-id alias/example-key --query Plaintext --output text | base64 -d; echo
パスワード: example-secret
$ printf garbage > bad.bin; aws kms decrypt --ciphertext-blob fileb://bad.bin

aws: [ERROR]: An error occurred (InvalidCiphertextException) when calling the Decrypt operation:

文字列を直接渡すとエラーになる

fileb:// を使わずに、文字列をそのまま --plaintext に書くと、検証環境では次のエラーで止まりました(終了コード255)。

text
$ aws kms encrypt --key-id alias/example-key --plaintext "パスワード: example-secret"

aws: [ERROR]: string argument should contain only ASCII characters

AWS CLI v2 の変更点の説明によると、AWS CLI v2 はバイナリの入力と出力を、既定で base64 の文字列として扱います。--plaintext に書いた文字列も、base64 として読まれます。元の文字列のまま渡したいときは、設定ファイルの cli_binary_format の説明にあるとおり、コマンドに --cli-binary-format raw-in-base64-out を付けます(AWS CLI v1 の既定の動きです)。検証環境では、この指定で文字列のまま暗号化できました。この指定を付けた encrypt でも、CiphertextBlob は既定と同じく base64 で出てきました。base64 -d で戻して復号すると、元の文字列になりました。

text
$ aws kms encrypt --key-id alias/example-key --plaintext "パスワード: example-secret" --cli-binary-format raw-in-base64-out --query CiphertextBlob --output text | base64 -d > cipher2.bin; aws kms decrypt --ciphertext-blob fileb://cipher2.bin --query Plaintext --output text | base64 -d; echo
パスワード: example-secret

なお、同じ plain.txt を2回暗号化して暗号文の SHA-256 を比べると、毎回違う値でした。暗号文どうしを比べても、元の文字列が同じかどうかは分かりません。

text
$ for i in 1 2; do aws kms encrypt --key-id alias/example-key --plaintext fileb://plain.txt --query CiphertextBlob --output text | sha256sum; done
99e4a4f2e7a52b67ce90669cb36c67e2bfa8270555b818007f966b5750de68de  -
21cedd74bb2c75a47b33d14d83e1c69c369055004e5f56ffcc98f80f1df3f672  -

暗号化できる大きさは4096バイトまで

Encrypt のリファレンスには、Encrypt で暗号化できるのは4096バイトまでで、個人を特定する番号やデータベースのパスワードのような少量のデータに使うものだと書かれています。検証環境でも、4096バイトは暗号化でき、4097バイトと空のファイルは ValidationException になりました。

text
$ aws kms encrypt --key-id alias/example-key --plaintext fileb://p4096 --query EncryptionAlgorithm --output text
SYMMETRIC_DEFAULT
$ aws kms encrypt --key-id alias/example-key --plaintext fileb://p4097

aws: [ERROR]: An error occurred (ValidationException) when calling the Encrypt operation: 1 validation error detected: Value at 'plaintext' failed to satisfy constraint: Member must have length less than or equal to 4096
$ aws kms encrypt --key-id alias/example-key --plaintext fileb:///dev/null

aws: [ERROR]: An error occurred (ValidationException) when calling the Encrypt operation: 1 validation error detected: Value at 'plaintext' failed to satisfy constraint: Member must have length greater than or equal to 1

p4096 と p4097 は、head -c 4096 /dev/zero のようにして作った、中身が0のファイルです。それより大きいデータには、データキーを使います。データキーの説明によると、GenerateDataKey で作るデータキーは大きなデータの暗号化にも使える対称鍵で、KMS の外(OpenSSL や AWS Encryption SDK など)で使うものです。

暗号化コンテキストを付けた暗号文は、同じコンテキストを渡さないと戻せない

--encryption-context で、キーと値の組を暗号文に結び付けられます。暗号化コンテキストの説明によると、同じ暗号化コンテキストを渡さないと復号できません。同じ説明では、暗号化するデータが何かを表す値を入れるように勧めています。例に挙がっているのは、ファイルを暗号化するときにファイルのパスの一部を使う方法で、ファイルの名前を変えたり別の場所に移したりすると、コンテキストが変わって復号に失敗します。

purpose=example,app=demo を付けて暗号化した暗号文は、検証環境では次のようになりました。

  • 暗号化コンテキストを付けずに復号すると、InvalidCiphertextException
  • 値を1つ変えて purpose=example,app=other にすると、InvalidCiphertextException
  • 並びを逆にして app=demo,purpose=example にすると、元の文字列に戻る
text
$ aws kms encrypt --key-id alias/example-key --plaintext fileb://plain.txt --encryption-context purpose=example,app=demo --query CiphertextBlob --output text | base64 -d > ctx.bin; wc -c ctx.bin
97 ctx.bin
$ aws kms decrypt --ciphertext-blob fileb://ctx.bin --query Plaintext --output text

aws: [ERROR]: An error occurred (InvalidCiphertextException) when calling the Decrypt operation:
$ aws kms decrypt --ciphertext-blob fileb://ctx.bin --encryption-context purpose=example,app=other --query Plaintext --output text

aws: [ERROR]: An error occurred (InvalidCiphertextException) when calling the Decrypt operation:
$ aws kms decrypt --ciphertext-blob fileb://ctx.bin --encryption-context app=demo,purpose=example --query Plaintext --output text | base64 -d; echo
パスワード: example-secret

エラーの理由は表示されず、メッセージは空でした。壊れた暗号文を渡したときと同じ InvalidCiphertextException なので、復号に失敗したら、暗号化コンテキストが合っているかも確かめる必要があります。

注意

暗号化コンテキストは秘密の値として扱われず、暗号化もされません。AWS CloudTrail のログにそのまま記録されるため、機密の情報を入れないようにと、暗号化コンテキストの説明に書かれています。パスワードそのものや個人の情報は入れないでください。

鍵を無効にしたり、削除を予約したりしたとき

disable-key で鍵を無効にすると、その鍵では暗号化も復号もできなくなりました。どちらも DisabledException です。enable-key で有効に戻すと、前に作った暗号文がまた復号できました。

text
$ aws kms disable-key --key-id fa0de1b9-36eb-45b7-bedb-8db7f984fc9f
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin

aws: [ERROR]: An error occurred (DisabledException) when calling the Decrypt operation: arn:aws:kms:us-east-1:<12桁のアカウントID>:key/fa0de1b9-36eb-45b7-bedb-8db7f984fc9f is disabled.
$ aws kms enable-key --key-id fa0de1b9-36eb-45b7-bedb-8db7f984fc9f
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin --query Plaintext --output text | base64 -d; echo
パスワード: example-secret

鍵の削除は、すぐには行われません。schedule-key-deletion で日数を決めて予約すると、KeyState が PendingDeletion になり、DeletionDate に削除される日時が入りました。予約は cancel-key-deletion で取り消せます。取り消したあとの状態は、有効ではなく Disabled でした。CancelKeyDeletion のリファレンスにも、取り消しが成功すると Disabled になり、使うには EnableKey で有効にすると書かれています。

text
$ aws kms schedule-key-deletion --key-id fc24a77c-cb05-4928-9b2c-e73613d5afd2 --pending-window-in-days 7
{
    "KeyId": "arn:aws:kms:us-east-1:<12桁のアカウントID>:key/fc24a77c-cb05-4928-9b2c-e73613d5afd2",
    "DeletionDate": "2026-11-22T01:48:31.734000+00:00",
    "KeyState": "PendingDeletion",
    "PendingWindowInDays": 7
}
$ aws kms cancel-key-deletion --key-id fc24a77c-cb05-4928-9b2c-e73613d5afd2
{
    "KeyId": "arn:aws:kms:us-east-1:<12桁のアカウントID>:key/fc24a77c-cb05-4928-9b2c-e73613d5afd2"
}
$ aws kms describe-key --key-id fc24a77c-cb05-4928-9b2c-e73613d5afd2 --query KeyMetadata.KeyState --output text
Disabled
注意

KMS の鍵の削除の説明によると、本物の AWS KMS で鍵が削除されると、その鍵で暗号化したデータは復号できなくなり、取り戻せません。削除の前には7〜30日(既定は30日)の待ち期間があり、その間は暗号化にも復号にも使えません。使うかどうか分からない鍵は、削除せずに無効にしておくように勧められています。

エミュレーターを起動し直すと、前の暗号文は戻せない

エミュレーターを止めて起動し直すと、list-keys は空になりました。前に保存した cipher.bin を復号しようとすると、AccessDeniedException になりました。メッセージには「リソースがこのリージョンにない」「許可するポリシーがない」などの理由が並んでいます。

text
$ aws kms list-keys
{
    "Keys": []
}
$ aws kms decrypt --ciphertext-blob fileb://cipher.bin

aws: [ERROR]: An error occurred (AccessDeniedException) when calling the Decrypt operation: User: arn:aws:iam::<12桁のアカウントID>:user/emulator is not authorized to perform: kms:Decrypt on the resource associated with this ciphertext because the resource does not exist in this Region, no resource-based policies allow access, or a resource-based policy explicitly denies access

AWS Emulator の説明にあるとおり、エミュレーターはリソースをメモリーにだけ置き、止めるとすべて消します。鍵も一緒に消えるので、テストでは、鍵を作るところから暗号化・復号までを1回の起動の中で済ませます。暗号文をファイルに残しておいて、エミュレーターを起動し直したあとのテストで使い回すことはできません。

どこまで本物と同じに動くかは、サービスや機能ごとに違います。忠実度(Fidelity)のページによると、今はリソースを作ったり一覧を出したりする API がいちばん本物に近く、暗号化や復号のような、サービスの本来の働きの部分はサービスによって差があります。公式ドキュメントによると、サービスごとの忠実度のスコアは、リリースごとに GitHub のリリースページで公開されます。

​Posted by 86