Data at rest encryption in Step Functions

AWS Step Functions always encrypts your data at rest using transparent server-side encryption. Encryption of data at rest by default reduces the operational overhead and complexity involved in protecting sensitive data. You can build security-sensitive applications that meet strict encryption compliance and regulatory requirements.

Although you can't disable this layer of encryption or select an alternate encryption type, you can add a second layer of encryption over the existing AWS owned encryption keys by choosing a customer managed key when you create your state machine and activity resources:

You can encrypt your data using a customer-managed key for AWS Step Functions state machines and activities. You can configure a symmetric AWS KMS key and data key reuse period when creating or updating a State Machine, and when creating an Activity. The execution history and state machine definition will be encrypted with the key applied to the State Machine. Activity inputs will be encrypted with the key applied to the Activity.

With customer managed AWS KMS keys, you can secure customer data that includes protected health information (PHI) from unauthorized access. Step Functions is integrated with CloudTrail, so you can view and audit the most recent events in the CloudTrail console in the event history.

For information on AWS KMS, see What is AWS Key Management Service?

Encrypting with a customer managed key

Step Functions decrypts payload data with your customer managed AWS KMS key before passing it to another service to perform a task. The data is encrypted in transit using Transport Layer Security (TLS).

When data is returned from an integrated service, Step Functions encrypts the data with your customer managed AWS KMS key. You can use the same key to consistently apply encryption across many AWS services.

You can use a customer managed key with the following resources:

You can specify the data key by entering a KMS key ID, which Step Functions uses to encrypt your data.

Create a State Machine with a customer managed key

Prerequisite: Before you can create a state machine with customer managed AWS KMS keys, your user or role must have AWS KMS permissions to DescribeKey and GenerateDataKey.

You can perform the following steps in the AWS console, through the API, or by provisioning infrastructure through AWS CloudFormation resources. (CloudFormation examples are presented later in this guide.)

Step 1: Create AWS KMS key

You can create a symmetric customer managed key with the AWS KMS console or AWS KMS APIs.

To create a symmetric customer managed key

Follow the steps for Creating symmetric customer managed key in the AWS Key Management Service Developer Guide.

Step 2: Set AWS KMS key policy

Key policies control access to your customer managed key. Every customer managed key must have exactly one key policy, which contains statements that determine who can use the key and how they can use it. When you create your customer managed key, you can specify a key policy. For information, see Managing access to customer managed keys in the AWS Key Management Service Developer Guide.

The following is an example AWS KMS key policy from console, without Key administrators or Key users:

{
  "Version": "2012-10-17",
  "Id": "key-consolepolicy-1",
  "Statement": [
    {
      "Sid": "Enable IAM User Permissions for the key",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:root"
      },
      "Action": "kms:*",
      "Resource": "*"
    }
  ]
}

See the AWS Key Management Service Developer Guide for information about specifying permissions in a policy and troubleshooting key access.

Step 3: Add key policy to encrypt CloudWatch logs

Step Functions is integrated with CloudWatch for logging and monitoring. When you enable server-side encryption for your state machine using your own KMS key and enable CloudWatch Log integration, you must allow delivery.logs.amazonaws.com to do kms:Decrypt action from your AWS KMS key policy:

{
  "Sid": "Enable log service delivery for integrations",
  "Effect": "Allow",
  "Principal": {
    "Service": "delivery.logs.amazonaws.com"
  },
  "Action": "kms:Decrypt",
  "Resource": "*"
}

If you enable state machine encryption with a AWS KMS key, and your state machine has CloudWatch Logs integration enabled, the state machine's execution role needs the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowKMSPermissionForCloudWatchLogGroup",
      "Effect": "Allow",
      "Action": "kms:GenerateDataKey",
      "Resource": "arn:aws:kms:region:accountId:key/keyId",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:SourceArn": "arn:aws:logs:region:accountId:*"
        }
      }
    }
  ]
}

Step 4: Encrypt CloudWatch Log Group (Optional)

You can enable encryption of the logs in a CloudWatch Log Group using your own AWS KMS key. To do that, you must also add the following policy to that AWS KMS key.

{
  "Id": "key-consolepolicy-logging",
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Enable log service for a single log group",
      "Effect": "Allow",
      "Principal": {
        "Service": "logs.region.amazonaws.com"
      },
      "Action": [
        "kms:Encrypt*",
        "kms:Decrypt*",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:Describe*"
      ],
      "Resource": "*",
      "Condition": {
        "ArnEquals": {
          "kms:EncryptionContext:aws:logs:arn": "arn:aws:logs:region:account-id:log-group:log-group-name"
        }
      }
    }
  ]
}

Step 5: Create state machine

After you have created a key and set up the policy, you can use the key to create a new state machine.

When creating the state machine, choose Additional configuration, then choose to encrypt with customer managed key. You can then select your key and set the data key reuse period from 1 min to 15 minutes.

Optionally, you can enable logging by setting a log level and choosing to encrypt the log group with your AWS KMS key.

To successfully start an execution for Standard workflows and Asynchronous Express workflows with customer managed keys, your execution role requires kms:Decrypt and kms:GenerateDataKey permissions. The execution role for Synchronous Express execution requires kms:Decrypt. When you create a state machine in the console and choose Create a new role, these permissions are automatically included for you.

The following is an example execution role policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowKMSPermissionsForStepFunctionsWorkflowExecutions",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": [
        "arn:aws:kms:us-east-1:123456789012:key/keyId"
      ],
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:aws:states:stateMachineArn": [
            "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName"
          ]
        }
      }
    }
  ]
}

Step 6: Invoke state machine encrypted with your AWS KMS key

You can invoke your encrypted state machine as you normally would, and your data will be encrypted with your customer managed key.

Create an Activity with a customer managed key

Creating an Step Functions Activity with a customer managed key is similar to creating a state machine with a customer managed key. Before you can create a activity with customer managed AWS KMS keys, your user or role only needs AWS KMS permissions to DescribeKey. During creation of the Activity, you choose the key and set the encryption configuration parameters.

Note that Step Functions Activity resources remain immutable. You cannot update the encryptionConfiguration for an activity ARN of an existing activity; you must create a new Activity resource. Callers to the Activity API endpoints must have kms:DescribeKey permissions to successfully create an activity with a AWS KMS key.

When customer managed key encryption is enabled on an Activity Task, the state machine execution role will require kms:GenerateDataKey and kms:Decrypt permission for the activity key. If you are creating this state machine from the Step Functions console, the auto role creation feature will add these permissions.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowKMSPermissionsForStepFunctionsActivities",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": [
        "arn:aws:kms:us-east-1:123456789012:key/keyId"
      ],
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:aws:states:activityArn": [
            "arn:aws:states:us-east-1:123456789012:activity:activityName"
          ]
        }
      }
    }
  ]
}

Scope down AWS KMS permission policies with conditions

You can use the encryption context in key policies and IAM policies as conditions to control access to your symmetric customer managed key. To limit the use of a AWS KMS key to requests from Step Functions on behalf of a specific role, you can use the kms:ViaService condition.

Scoping with encryption context

An encryption context is an optional set of key-value pairs that contain additional contextual information about the data.

AWS KMS uses the encryption context as additional authenticated data to support authenticated encryption. When you include an encryption context in a request to encrypt data, AWS KMS binds the encryption context to the encrypted data. To decrypt data, you include the same encryption context in the request.

Step Functions provides an encryption context in AWS KMS cryptographic operations, where the key is aws:states:stateMachineArn for State Machines or aws:states:activityArn for Activities, and the value is the resource Amazon Resource Name (ARN).

"encryptionContext": {"aws:states:stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName"}

"encryptionContext": {"aws:states:activityArn": "arn:aws:states:us-east-1:123456789012:activity:activityName"}

The following example shows how to limit the use of a AWS KMS key for execution roles to specific state machines with kms:EncryptionContext and the aws:states:stateMachineArn context key:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Allow KMS Permissions for StepFunctionsWorkflowExecutions",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": [
        "arn:aws:kms:us-east-1:123456789012:key/keyId"
      ],
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:aws:states:stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName"
        }
      }
    }
  ]
}

Scoping with kms:ViaService

The kms:ViaService condition key limits use of an AWS Key Management Service key to requests from specified AWS services.

The following example policy uses the kms:ViaService condition to allow the AWS KMS key to be used for specific actions only when the request originates from Step Functions in the ca-central-1 region, acting on behalf of the ExampleRole:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Allow access for Key Administrators in a region",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
      },
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "states.us-east-1.amazonaws.com"
        }
      }
    }
  ]
}

Required permissions for API callers

To call Step Functions API actions that return encrypted data, callers need AWS KMS permissions. Alternatively, some API actions have an option (METADATA_ONLY) to return only metadata, removing the requirement for AWS KMS permissions. Refer to the Step Functions API for information.

For an execution to successfully complete when using customer managed key encryption, the execution role needs to be granted kms:GenerateDataKey and kms:Decrypt permissions for AWS KMS keys used by the state machine.

The following table shows the AWS KMS permissions you need to provide to Step Functions API callers for the APIs using a State Machine's AWS KMS key. You can provide the permissions to the key policy or IAM policy for the role.

The following table shows the AWS KMS permissions you need to provide to Step Functions API callers for the APIs using an Activity's AWS KMS key. You can provide the permissions in the key policy or IAM policy for the role.

AWS CloudFormation resources for encryption configuration

AWS CloudFormation resource types for Step Functions can provision state machine and activity resources with encryption configurations.

By default, Step Functions provides transparent server-side encryption. Both AWS::StepFunctions::Activity and AWS::StepFunctions::StateMachine accept an optional EncryptionConfiguration property which can configure a customer managed AWS KMS key for server-side encryption.

Prerequisite: Before you can create a state machine with customer managed AWS KMS keys, your user or role must have AWS KMS permissions to DescribeKey and GenerateDataKey.

Updates to StateMachine requires No interruption. Updates to Activity resources requires: Replacement.

To declare an EncryptionConfiguration property in your AWS CloudFormation template, use the following syntax:

JSON

{
  "KmsKeyId" : String,
  "KmsDataKeyReusePeriodSeconds" : Integer,
  "Type" : String
}

YAML

KmsKeyId: String
KmsDataKeyReusePeriodSeconds: Integer
Type: String

Properties

AWS CloudFormation examples

Example: StateMachine with customer managed key

AWSTemplateFormatVersion: '2010-09-09'
Description: An example template for a Step Functions State Machine.
Resources:
  MyStateMachine:
    Type: AWS::StepFunctions::StateMachine
    Properties:
      StateMachineName: HelloWorld-StateMachine
      Definition:
        StartAt: PassState
        States:
          PassState:
            Type: Pass
            End: true
      RoleArn: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/example"
      EncryptionConfiguration:
        KmsKeyId: !Ref MyKmsKey
        KmsDataKeyReusePeriodSeconds: 100
        Type: CUSTOMER_MANAGED_KMS_KEY

  MyKmsKey:
    Type: AWS::KMS::Key
    Properties:
      Description: Symmetric KMS key used for encryption/decryption

Example: Activity with customer managed key

AWSTemplateFormatVersion: '2010-09-09'
Description: An example template for a Step Functions Activity.
Resources:
  Activity:
    Type: AWS::StepFunctions::Activity
    Properties:
      Name: ActivityWithKmsEncryption
      EncryptionConfiguration:
        KmsKeyId: !Ref MyKmsKey
        KmsDataKeyReusePeriodSeconds: 100
        Type: CUSTOMER_MANAGED_KMS_KEY

  MyKmsKey:
    Type: AWS::KMS::Key
    Properties:
      Description: Symmetric KMS key used for encryption/decryption
                    

Updating encryption for an Activity requires creating a new resource

Activity configuration is immutable, and resource names must be unique. To set customer managed keys for encryption, you must create a new Activity. If you attempt to change the configuration in your CFN template for an existing activity, you will receive an ActivityAlreadyExists exception.

To update your activity to include customer managed keys, set a new activity name within your CFN template. The following shows an example that creates a new activity with a customer managed key configuration:

Existing activity definition

AWSTemplateFormatVersion: '2010-09-09'
  Description: An example template for a new Step Functions Activity.
  Resources:
    Activity:
    Type: AWS::StepFunctions::Activity
    Properties:
      Name: ActivityName
      EncryptionConfiguration:
        Type: AWS_OWNED_KEY

New activity definition

AWSTemplateFormatVersion: '2010-09-09'
  Description: An example template for a Step Functions Activity.
  Resources:
    Activity:
      Type: AWS::StepFunctions::Activity
      Properties:
        Name: ActivityWithKmsEncryption
        EncryptionConfiguration:
          KmsKeyId: !Ref MyKmsKey
          KmsDataKeyReusePeriodSeconds: 100
          Type: CUSTOMER_MANAGED_KMS_KEY

    MyKmsKey:
      Type: AWS::KMS::Key
      Properties:
        Description: Symmetric KMS key used for encryption/decryption

Monitoring your encryption key usage

When you use an AWS KMS customer managed key to encrypt your Step Functions resources, you can use CloudTrail to track requests that Step Functions sends to AWS KMS.

You can also use the encryption context in audit records and logs to identify how the customer managed key is being used. The encryption context also appears in logs generated by AWS CloudTrail.

The following examples are CloudTrail events for Decrypt, DescribeKey, and GenerateDataKey to monitor AWS KMS operations called by Step Functions to access data encrypted by your customer managed key:

FAQs

What happens if my key is marked for deletion or deleted in AWS KMS?

If the key is deleted or marked for deletion in AWS KMS, any related running executions will fail. New executions cannot be started until you remove or change the key associated with the workflow. After a AWS KMS key is deleted, all encrypted data associated with the workflow execution will remain encrypted and can no longer be decrypted, making the data unrecoverable.

What happens if a AWS KMS key is disabled in AWS KMS?

If a AWS KMS key is disabled in AWS KMS, any related running executions will fail. New executions cannot be started. You can no longer decrypt the data encrypted under that disabled AWS KMS key until it is re-enabled.

What happens to Execution Status change events sent to EventBridge?

Execution Input, Output, Error, and Cause will not be included for execution status change events for workflows that are encrypted using your customer managed AWS KMS key.

Learn more

For information about data encryption at rest, see AWS Key Management Service concepts and security best practices for AWS Key Management Service in the AWS Key Management Service Developer Guide.