Encryption at rest for Replay Session

Replay Session encrypts your recordings at rest by default. While a session is recorded and processed, Replay Session holds the screen frames, their metadata, and the finished artifacts that are waiting for delivery in storage that AWS owns. By default, this content is encrypted at rest with Amazon S3 managed keys (SSE-S3). You don't need to take any action.

Optionally, you can provide a customer managed AWS Key Management Service (AWS KMS) key. When you do, Replay Session uses the AWS Encryption SDK to encrypt each frame, metadata object, tool response record, and artifact checkpoint under your key before it stores the object. You create, own, and manage the customer managed key, and you have full control over it. For more information, see AWS KMS concepts in the AWS Key Management Service Developer Guide.

AWS KMS charges apply for customer managed keys. For more information, see AWS KMS pricing.

How Replay Session uses a customer managed key

Replay Session uses your customer managed key to encrypt the following content while a session is recorded and processed:

• Screen frames. The frames captured during the session.

• Frame metadata. The per-action metadata for each frame.

• Tool responses. The result that each tool call returns.

• Artifact checkpoints. The transcript, session video, and HTML report that Replay Session produces after the session, while they wait for delivery.

The customer managed key protects only this content in AWS-owned storage. It isn't used for the artifacts that Replay Session delivers to your bucket. For those artifacts, see Encrypting delivered artifacts in your bucket.

Principals that use the key

Every AWS KMS request that Replay Session makes runs as your own identity, with your own permissions. Two of your principals are involved:

• The principal that configures the stack. The IAM identity that calls CreateStack or UpdateStack. It validates the key when you set or change it.

• The principal that uses the stack. The IAM identity that starts the agent session, which is the identity that your agent uses to connect to the Model Context Protocol (MCP) service. It makes every other AWS KMS request. This principal isn't necessarily the person whose screen activity is recorded.

Replay Session doesn't use grants, service roles, service-linked roles, or roles that you provide, and you don't add a service principal to your key policy.

AWS KMS operations

Replay Session makes the following AWS KMS requests with your customer managed key. Each request arrives through one of two services, which you can use as the value of the kms:ViaService condition key:

• Stack configurer requests come from the principal that configures the stack, through appstream.region.amazonaws.com.

• Stack user requests come from the principal that uses the stack, through agentaccess-mcp.region.amazonaws.com.

AWS KMS requests that Replay Session makes

Operation	When	Caller	Purpose
DescribeKey	When you call CreateStack or UpdateStack with KmsKeyArn	Stack configurer	Validate the key
Decrypt	Once per session, at the first recorded action	Stack user	Confirm at the start of the session that processing will be able to decrypt the recording. No data is decrypted.
GenerateDataKey	During the session, three times for each action: once for the frame, once for the metadata object, and once for the tool response record	Stack user	Encrypt each object before it is stored
Decrypt	After the session, three times for each action: once for the frame, once for the metadata object, and once for the tool response record	Stack user	Read the recording for processing
GenerateDataKey	After the session, at least three times per session	Stack user	Encrypt the transcript, video, and report checkpoints
Decrypt	After the session, once for each object, only if processing fails	Stack user	Deliver the raw frames, metadata, tool response records, and any completed artifact checkpoints to your bucket instead of the finished artifacts, so that no captured evidence is lost

Replay Session never calls Encrypt, ReEncrypt*, or CreateGrant. Replay Session doesn't cache data keys, so if you disable the key or remove access to it, the change takes effect at the next request.

AWS KMS requests continue for a few minutes after a session ends, while the recording is processed. As a result, you can see Decrypt and GenerateDataKey events in CloudTrail after the agent has disconnected.

Request quotas and using a dedicated key

Each recorded action makes three GenerateDataKey requests during the session and three Decrypt requests after it: one each for the frame, the metadata object, and the tool response record. These requests count toward the AWS KMS request quotas for your AWS account, which all keys in the account and Region share. For more information, see Request quotas in the AWS Key Management Service Developer Guide.

We recommend that you use a dedicated key for Replay Session. That way, key policy changes that you make for other workloads can't stop Replay Session from recording.

When the key becomes unavailable

If you disable the key, schedule it for deletion, or change its policy so that Replay Session can no longer use it, the following happens:

• During a session. The next frame capture fails, and the agent's action fails with it. Every later action in that session also fails, because Replay Session doesn't let an agent act without recording the action. Changes to the key or its policy therefore control whether agents can act on stacks that use the key.

• After a session. If the key becomes unavailable before processing finishes, the recording can't be processed or delivered, and it can't be recovered.

The principal that uses the stack must keep the kms:Decrypt and kms:GenerateDataKey permissions on the key, and the s3:PutObject permission on the destination bucket, for the whole session and until processing finishes. Keep the key enabled, and keep its permissions in place, until every session that used it has finished processing.

Encrypting delivered artifacts in your bucket

Replay Session writes the delivered artifacts to your Amazon S3 bucket as the principal that uses the stack. The artifacts are encrypted with the default encryption of the bucket, which can be SSE-S3. The customer managed key that you set for Replay Session isn't used for these artifacts.

To encrypt the delivered artifacts with your own key, do the following:

1. Set SSE-KMS with an Amazon S3 Bucket Key as the default encryption for the bucket. For more information, see Setting default server-side encryption behavior for Amazon S3 buckets and Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys in the Amazon S3 User Guide.

2. Give the principal that uses the stack the following permissions on the bucket's KMS key, through Amazon S3:

   • kms:GenerateDataKey, to write each artifact.

   • kms:Decrypt, to write artifacts larger than 8 MB. Larger artifacts are uploaded in multiple parts, and multipart uploads to an SSE-KMS bucket require kms:Decrypt.

Configuring a customer managed key for Replay Session

Replay Session supports a symmetric encryption KMS key that is enabled and is in the same Region as the stack. Keys in custom key stores and external key stores are supported. You can choose a Multi-Region key. The primary key or replica key that you choose must be in the same Region as the stack. Replay Session doesn't support the multi-Region features of the key.

To encrypt Replay Session recordings with a customer managed key

1. Create a symmetric encryption KMS key in the same Region as the stack, or choose an existing one. For more information, see Create a symmetric encryption KMS key in the AWS Key Management Service Developer Guide.

2. Add key policy statements that allow the principal that uses the stack to encrypt and read recordings, and allow the principal that configures the stack to validate the key. For details, see Permissions for the customer managed key.

3. Attach IAM policies to both principals.

4. Set KmsKeyArn in the AgentAccessConfig when you call CreateStack or UpdateStack. For details, see Setting the key on a stack.

5. Verify in CloudTrail that the expected DescribeKey, GenerateDataKey, and Decrypt events appear. For details, see Monitoring Replay Session interaction with AWS KMS.

Permissions for the customer managed key

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. For more information, see KMS key access and permissions in the AWS Key Management Service Developer Guide.

Which policies you need depends on where the key is:

• If the key is in the same account as the stack, and its key policy includes the default statement that allows IAM policies to grant access to the key, the IAM policies in this section are enough.

• If the key is in another account, or its key policy doesn't allow IAM policies to grant access, also add the key policy statements in this section.

Key policy statements

The following example statements give the principal that uses the stack (ReplaySessionUserRole) and the principal that configures the stack (ReplaySessionAdminRole) the permissions they need. Add these statements to your existing key policy. Don't replace the existing statements.

{
    "Sid": "AllowAgentAccessDirectKMS",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111122223333:role/ReplaySessionUserRole" },
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:ViaService": "agentaccess-mcp.us-east-1.amazonaws.com"
        },
        "StringLike": {
            "kms:EncryptionContext:aws:agentaccess-mcp:session_id": "*"
        }
    }
},
{
    "Sid": "AllowAppstreamToDescribeKey",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111122223333:role/ReplaySessionAdminRole" },
    "Action": "kms:DescribeKey",
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:ViaService": "appstream.us-east-1.amazonaws.com"
        }
    }
}

• AllowAgentAccessDirectKMS lets the principal that uses the stack encrypt and read the recording. The kms:ViaService condition limits these operations to requests that come through Replay Session. The kms:EncryptionContext condition requires the session encryption context to be present, with any value, because the value is a session ID that is assigned when the session starts.

• AllowAppstreamToDescribeKey lets the principal that configures the stack validate the key when it creates or updates the stack. This statement has no encryption context condition, because DescribeKey doesn't take an encryption context.

Because each statement names a specific role as its principal, you don't need a kms:CallerAccount condition. If more than one role starts sessions or configures the stack, list each role in the matching statement.

IAM policy for the principal that uses the stack

Attach the following statement to the IAM identity that your agent uses to start sessions.

{
    "Sid": "AllowReplaySessionFrameEncryption",
    "Effect": "Allow",
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "Condition": {
        "StringEquals": {
            "kms:ViaService": "agentaccess-mcp.us-east-1.amazonaws.com"
        }
    }
}

IAM policy for the principal that configures the stack

Attach the following statements to the IAM identity that calls CreateStack or UpdateStack.

{
    "Sid": "AllowReplaySessionKeyValidation",
    "Effect": "Allow",
    "Action": "kms:DescribeKey",
    "Resource": "arn:*:kms:*:*:key/*"
},
{
    "Sid": "AllowReplaySessionConsoleKeyListing",
    "Effect": "Allow",
    "Action": "kms:ListAliases",
    "Resource": "*"
}

These statements don't include a kms:ViaService condition, because the console lists your keys with kms:ListAliases and validates the key that you select with kms:DescribeKey directly, without a kms:ViaService value. If you configure stacks only through the API, you can remove the AllowReplaySessionConsoleKeyListing statement, limit Resource to your key, and add a kms:ViaService condition with the value appstream.region.amazonaws.com.

For more information, see Specifying KMS keys in IAM policy statements and Troubleshooting key access in the AWS Key Management Service Developer Guide.

Using a key in another account

To use a key in another account, configure the stack through the API. Both the key policy and the IAM policy of the principal that configures the stack must allow kms:DescribeKey.

Setting the key on a stack

Set the key with the KmsKeyArn field in the AgentAccessConfig of the CreateStack and UpdateStack API operations. You can set KmsKeyArn whether or not ReplaySessionEnabled is true.

KmsKeyArn accepts a key ARN only. If you provide an alias ARN, an alias name, or a key ID, the request is rejected before Replay Session contacts AWS KMS.

When KmsKeyArn is present, the service calls DescribeKey as the principal that makes the request, to confirm that the key exists, is enabled, is a symmetric encryption KMS key, and is in the same Region as the stack.

The following example adds a customer managed key to an existing stack:

aws appstream update-stack \
    --name your-stack-name \
    --agent-access-config '{
        "S3BucketArn": "arn:aws:s3:::amzn-s3-demo-bucket",
        "ReplaySessionEnabled": true,
        "KmsKeyArn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    }'

Changing the key

To change the key, call UpdateStack with a new KmsKeyArn. The service validates the new key the same way that it validates a key when you create a stack. Configuration is fixed for each session, so sessions that are already running keep the key that they started with, and new sessions use the new key. Replay Session doesn't re-encrypt content.

Content recorded under the previous key stays encrypted under that key. Keep the previous key enabled, and keep its key policy and IAM permissions in place, until every session that started under it has finished processing.

Scoping down access to the key

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. The encryption context also appears in CloudTrail logs, so you can use it to identify how your key is being used.

Every GenerateDataKey and Decrypt request that Replay Session makes includes the following encryption context pair. The key is aws:agentaccess-mcp:session_id, and the value is the ID of the session being recorded.

"encryptionContext": {
    "aws:agentaccess-mcp:session_id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

The aws: prefix is part of the literal name of the encryption context key. It isn't a global IAM condition key.

Requests made through the AWS Encryption SDK, which are all requests except the Decrypt request at the start of the session, also include an aws-crypto-public-key encryption context pair that the AWS Encryption SDK adds.

When you write your own encryption context conditions, require the aws:agentaccess-mcp:session_id key and allow the aws-crypto-public-key key. Session IDs are assigned when each session starts, and every session on the stack uses the same key, so you can't name a specific session ID in a policy. Instead, require that the session ID key is present, as the AllowAgentAccessDirectKMS statement does with "StringLike": { "kms:EncryptionContext:aws:agentaccess-mcp:session_id": "*" }. Don't use a condition that requires the encryption context to contain only the session ID pair, or requests that the AWS Encryption SDK makes are denied.

kms:ViaService

The kms:ViaService condition key limits use of the key to requests that come from a specific AWS service. Replay Session uses the following values:

• agentaccess-mcp.region.amazonaws.com for GenerateDataKey and Decrypt requests made to record, process, and deliver the recording.

• appstream.region.amazonaws.com for DescribeKey requests made to validate the key.

Confused deputy protection

The aws:SourceArn and aws:SourceAccount condition keys don't apply to Replay Session. Every AWS KMS request runs as your own identity, and Replay Session doesn't use a service role, so there is no cross-service request for these keys to constrain. The key policy scopes access by naming the two roles.

Monitoring Replay Session interaction with AWS KMS

When you use a customer managed key with Replay Session, you can use CloudTrail to track the requests that Replay Session sends to AWS KMS. For more information, see Logging AWS KMS API calls with AWS CloudTrail in the AWS Key Management Service Developer Guide.

Look for the following events:

• DescribeKey, made by the principal that configures the stack when the stack is created or updated, with the kms:ViaService value appstream.region.amazonaws.com.

• GenerateDataKey and Decrypt, made by the principal that uses the stack, with the kms:ViaService value agentaccess-mcp.region.amazonaws.com and the aws:agentaccess-mcp:session_id encryption context. These events continue for a few minutes after the agent disconnects.

Events appear in the trail of the account that makes the request. For a key in another account, the events also appear in the account that owns the key.