Data at rest encryption in Step Functions

Amazon Step Functions always encrypts your data at rest. Data in Step Functions is encrypted at rest using transparent server-side encryption. This helps reduce the operational burden and complexity involved in protecting sensitive data. With encryption at rest, you can build security-sensitive applications that meet encryption compliance and regulatory requirements

Encryption of data at rest by default helps reduce the operational overhead and complexity involved in protecting sensitive data. At the same time, you can build secure 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 Amazon 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 Amazon Step Functions state machines and activities. You can configure a symmetric Amazon 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 Amazon 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 more information on Amazon KMS, see What is Amazon Key Management Service?

Encrypting with a customer managed key

Step Functions decrypts payload data with your customer managed Amazon 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 Amazon KMS key. You can use the same key to consistently apply encryption across many Amazon 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 Amazon KMS keys, your user or role must have Amazon KMS permissions to DescribeKey and GenerateDataKey.

Step 1: Create Amazon KMS key

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

To create a symmetric customer managed key

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

Step 2: Set Amazon 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 more information, see Managing access to customer managed keys in the Amazon Key Management Service Developer Guide.

The following is an example Amazon 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 Amazon Key Management Service Developer Guide for more information about specifying permissions in a policy and troubleshooting key access.

Step 3: (Optional) Add key policy to encrypt CloudWatch logs

Step Functions is integrated with CloudWatch for logging and monitoring. You have the option to encrypt data sent to CloudWatch Logs. To use encrypted logging, you must provide access to the log delivery service in the state machine key policy to Amazon KMS actions. You can encrypt log groups using the state machine key, or you can choose another key specifically for the log group (for example, "Log Group Key").

To enable encrypted CloudWatch log integration for a state machine, you must add the following to your Amazon KMS key policy:

{
    "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"
                }
            }
        }
    ]
    }

You must also enable log service delivery for integrations with the following key policy:

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

Step 4: Create state machine

After you have created a key and set up the policy, you can use they 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 Amazon KMS key.

Step 5: Invoke state machine encrypted with your Amazon KMS key

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

To 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.

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 Amazon KMS keys, your user or role only needs Amazon 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 can not 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 Amazon 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.

Scope down Amazon 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 Amazon 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.

Amazon 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, Amazon 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 Amazon 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:region:123456789012:stateMachine:state_machine_name"}

"encryptionContext": {"aws:states:activityArn": "arn:aws:states:region:123456789012:activity:activity_name"}

The following example shows how to limit the use of a Amazon 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:aa-example-1:1234567890:key/a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa"
            ],
        "Condition": {
            "StringEquals": {
                "kms:EncryptionContext:aws:states:stateMachineArn": "arn:aws:states:aa-example-1:1234567890:stateMachine:MyStateMachine"
                }
            }
        }
    ]
}

Scoping with kms:ViaService

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

The following example policy uses the kms:ViaService condition to allow the Amazon 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::1234567890:role/ExampleRole"
            },
        "Action": [
            "kms:Decrypt",
            "kms:GenerateDataKey"
            ],
        "Resource": "*",
        "Condition": {
            "StringEquals": {
                "kms:ViaService": "states.ca-central-1.amazonaws.com"
                }
            }
        }
    ]
}

Required permissions for API callers

To call Step Functions API actions that return encrypted data, callers need Amazon KMS permissions. Alternatively, some API actions have an option (METADATA_ONLY) to return only metadata, removing the requirement for Amazon KMS permissions. Refer to the Step Functions API for more 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 Amazon KMS keys used by the state machine.

The following table shows the Amazon KMS permissions you need to provide Step Functions State Machine API callers. You can provide the permissions in the key policy or IAM policy for the role.

The following table shows the Amazon KMS permissions you need to provide Step Functions Activity API callers . You can provide the permissions in the key policy or IAM policy for the role.

Amazon CloudFormation resources for encryption configuration

Amazon 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 Amazon KMS key for server-side encryption.

Prerequisite: Before you can create a state machine with customer managed Amazon KMS keys, your user or role must have Amazon 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 Amazon CloudFormation template, use the following syntax:

JSON

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

YAML

KmsKeyId: String
KmsDataKeyReusePeriodSeconds: Integer
Type: String

Properties

Amazon 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 Amazon KMS customer managed key to encrypt your Step Functions resources, you can use CloudTrail to track requests that Step Functions sends to Amazon 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 Amazon CloudTrail.

The following examples are CloudTrail events for Decrypt, DescribeKey, and GenerateDataKey to monitor Amazon 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 Amazon KMS?

If the key is deleted or marked for deletion in Amazon 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 Amazon 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 Amazon KMS key is disabled in Amazon KMS?

If a Amazon KMS key is disabled in Amazon KMS, any related running executions will fail. New executions cannot be started. You can no longer decrypt the data encrypted under that disabled Amazon 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 Amazon KMS key.

Learn more

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