Top / Amazon Web Service / AWS KMS / Ciphertext

AWS KMS Ciphertext

This page shows how to write Terraform and CloudFormation for AWS KMS Ciphertext and write them securely.

terraform-logo

Review your .tf file for AWS best practices

Shisho Cloud, our free checker to make sure your Terraform configuration follows best practices, is available (beta).

aws_kms_ciphertext (Terraform)

The Ciphertext in AWS KMS can be configured in Terraform with the resource name aws_kms_ciphertext. The following sections describe 5 examples of how to use the resource and its parameters.

Example Usage from GitHub

encrypt.tf#L6
resource "aws_kms_ciphertext" "github_app_key_base64" {
  count     = var.encryption.encrypt ? 1 : 0
  key_id    = var.encryption.kms_key_id
  plaintext = var.github_app.key_base64

  context = {
main.tf#L1
resource "aws_kms_ciphertext" "main" {
  key_id = var.config.key_id

  plaintext = var.config.plaintext
}
kms.tf#L13
resource "aws_kms_ciphertext" "this" {
  key_id    = aws_kms_key.this.key_id
  plaintext = "hello world"
}

output "b1_key_arn" {
kms_ciphertext.tf#L4
resource "aws_kms_ciphertext" "kms_ciphertext" {
  count = var.enable_kms_ciphertext ? 1 : 0

  key_id    = var.kms_ciphertext_key_id != "" ? var.kms_ciphertext_key_id : (var.enable_kms_key ? element(aws_kms_key.kms_key.*.key_id, 0) : null)
  plaintext = var.kms_ciphertext_plaintext
kms_ciphertext.tf#L4
resource "aws_kms_ciphertext" "kms_ciphertext" {
  count = var.enable_kms_ciphertext ? 1 : 0

  key_id    = var.kms_ciphertext_key_id != "" ? var.kms_ciphertext_key_id : (var.enable_kms_key ? element(aws_kms_key.kms_key.*.key_id, 0) : null)
  plaintext = var.kms_ciphertext_plaintext

Review your Terraform file for AWS best practices

Shisho Cloud, our free checker to make sure your Terraform configuration follows best practices, is available (beta).

Parameters

>> from Terraform Registry

Explanation in Terraform Registry

The KMS ciphertext resource allows you to encrypt plaintext into ciphertext by using an AWS KMS customer master key. The value returned by this resource is stable across every apply. For a changing ciphertext value each apply, see the aws_kms_ciphertext data source.

Note: All arguments including the plaintext be stored in the raw state as plain-text. Read more about sensitive data in state.

>> from Terraform Registry

AWS::KMS::Key (CloudFormation)

The Key in KMS can be configured in CloudFormation with the resource name AWS::KMS::Key. The following sections describe 10 examples of how to use the resource and its parameters.

Example Usage from GitHub

template.yml#L9
    Type: AWS::KMS::Key
    Properties:
      Description: Symmetric key for demo
      Enabled: True
      EnableKeyRotation: True
      KeySpec: SYMMETRIC_DEFAULT
kms_key_without_key_policy.yml#L5
    Type: "AWS::KMS::Key"
    Properties:
      EnableKeyRotation: true
kms_key_with_single_statement.yml#L5
    Type: "AWS::KMS::Key"
    Properties:
      KeyPolicy:
        Version: "2012-10-17"
        Statement:
          Effect: "Allow"
iam.yml#L35
  #   Type: AWS::KMS::Key
  #   Properties:
  #     Description: A symmetric CMK Create for RDS
  #     KeyPolicy:
  #       Version: '2012-10-17'
  #       Id: key-default-ecs-01
cloud_trail_tests.yml#L30
      {"arn":"arn:aws:kms:us-west-2:888888888888:key/72c37aae-1000-4058-93d4-86374c0fe9a0","accountId":"888888888888","type":"AWS::KMS::Key"}
    ],
    "eventType":"AwsApiCall",
    "recipientAccountId":"777777777777",
    "sharedEventID":"238c190c-1a30-4756-8e08-19fc36ad1b9f"
  }
AWS-Customer-Master-Key-rotation-is-not-enabled.json#L6
   "rule":"$.Resources.*[?(@.Type=='AWS::KMS::Key')].Properties.EnableKeyRotation any null or $.Resources.*[?(@.Type=='AWS::KMS::Key')].Properties.EnableKeyRotation anyFalse",
   "id":"6ae8d0a5-4794-438c-aafa-200f94b45f1f",
   "enabled":true,
   "recommendation": {
      "name": "Recommended solution for enabling Customer Master Keys.",
      "description": "It is recommended that Customer Master Keys rotation is enabled. Please make sure your template has \"EnableKeyRotation\" attribute and it is set to \"true\"",
positive2.json#L4
      "Type": "AWS::KMS::Key",
      "Properties": {
        "Enabled": true,
        "KeyPolicy": {
          "Version": "2012-10-17",
          "Id": "key-default-1",
positive2.json#L4
      "Type": "AWS::KMS::Key",
      "Properties": {
        "Enabled": true,
        "KeyPolicy": {
          "Version": "2012-10-17",
          "Id": "key-default-1",
positive2.json#L4
      "Type": "AWS::KMS::Key",
      "Properties": {
        "Enabled": false,
        "KeyPolicy": {
          "Id": "key-default-1",
          "Statement": [
kms.json#L12
      "CloudTrailEvent": "{\"eventVersion\":\"1.05\",\"userIdentity\":{\"type\":\"IAMUser\",\"principalId\":\"AIDAXGJAWKEZ3D5NC2A3X\",\"arn\":\"arn:aws:iam::494526681395:user/hzhuang\",\"accountId\":\"494526681395\",\"accessKeyId\":\"ASIAXGJAWKEZ5R4FWDTG\",\"userName\":\"hzhuang\",\"sessionContext\":{\"sessionIssuer\":{},\"webIdFederationData\":{},\"attributes\":{\"mfaAuthenticated\":\"false\",\"creationDate\":\"2020-05-14T01:47:32Z\"}}},\"eventTime\":\"2020-05-14T01:47:46Z\",\"eventSource\":\"kms.amazonaws.com\",\"eventName\":\"GetKeyPolicy\",\"awsRegion\":\"ap-southeast-1\",\"sourceIPAddress\":\"202.66.38.130\",\"userAgent\":\"aws-internal/3 aws-sdk-java/1.11.742 Linux/4.9.184-0.1.ac.235.83.329.metal1.x86_64 OpenJDK_64-Bit_Server_VM/25.242-b08 java/1.8.0_242 vendor/Oracle_Corporation\",\"requestParameters\":{\"keyId\":\"aa5b2dc0-88ba-4e21-b339-82d8a18e9e6b\",\"policyName\":\"default\"},\"responseElements\":null,\"requestID\":\"dbd92b4e-b29e-493d-bd21-8fdd63806075\",\"eventID\":\"16731af3-a991-4b56-a7ad-348a1a2a73b6\",\"readOnly\":true,\"resources\":[{\"accountId\":\"494526681395\",\"type\":\"AWS::KMS::Key\",\"ARN\":\"arn:aws:kms:ap-southeast-1:494526681395:key/aa5b2dc0-88ba-4e21-b339-82d8a18e9e6b\"}],\"eventType\":\"AwsApiCall\",\"recipientAccountId\":\"494526681395\"}"
    },
    {
      "EventId": "5adb4de1-2822-451e-adb4-dd92bf6a84a5",
      "EventName": "ListAliases",
      "ReadOnly": "true",

Parameters

>> from AWS CloudFormation Documentation

Explanation in CloudFormation Registry

The AWS::KMS::Key resource specifies a symmetric or asymmetric KMS key in AWS Key Management Service (AWS KMS).

Note AWS KMS is replacing the term customer master key (CMK) with AWS KMS key and KMS key. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term.

You can use symmetric KMS keys to encrypt and decrypt small amounts of data, but they are more commonly used to generate data keys and data key pairs. You can also use symmetric KMS key to encrypt data stored in AWS services that are integrated with AWS KMS. For more information, see What is AWS Key Management Service? in the AWS Key Management Service Developer Guide.

You can use asymmetric KMS keys to encrypt and decrypt data or sign messages and verify signatures. To create an asymmetric key, you must specify an asymmetric KeySpec value and a KeyUsage value.

Important If you change the value of a Replacement property, such as KeyUsage or KeySpec, on an existing KMS key, the existing KMS key is scheduled for deletion and a new KMS key is created with the specified value. While scheduled for deletion, the existing KMS key becomes unusable. If you don't cancel the scheduled deletion of the existing KMS key outside of CloudFormation, all data encrypted under the existing KMS key becomes unrecoverable when the KMS key is deleted.

>> from AWS CloudFormation Documentation

The Other Related AWS KMS Resources

Frequently asked questions

What is AWS KMS Ciphertext?

AWS KMS Ciphertext is a resource for KMS of Amazon Web Service. Settings can be wrote in Terraform and CloudFormation.

Where can I find the example code for the AWS KMS Ciphertext?

For Terraform, the YAwasom/project, AtsushiKitano/assets and mrajani/learntf source code examples are useful. See the Terraform Example section for further details.

For CloudFormation, the MarkBiesheuvel/demo-templates, stelligent/cfn-model and stelligent/cfn-model source code examples are useful. See the CloudFormation Example section for further details.

security-icon

Automate config file reviews on your commits

Fix issues in your infrastructure as code with auto-generated patches.

Table of Contents