View a markdown version of this page

Configuration bundle encryption - Amazon Bedrock AgentCore
How it worksMonitoring KMS usage for configuration bundlesBehavior when a key becomes unavailable

Configuration bundle encryption

When you specify a kmsKeyArn on a configuration bundle, the service encrypts the component configurations (system prompts, tool descriptions, and other configuration content) using envelope encryption. All other bundle metadata (name, description, version IDs, timestamps) remains encrypted with the AWS owned key.

How it works

Configuration bundle encryption uses envelope encryption with caller credentials. When you create or update a bundle with a kmsKeyArn, the service uses your credentials (via Forward Access Sessions) to generate a data encryption key (DEK) from KMS. The service encrypts the component configurations locally using AES-GCM with that DEK, then stores the encrypted DEK alongside the bundle. When you retrieve the bundle, the service decrypts the DEK using your credentials and decrypts the components.

The caller must have kms:GenerateDataKey, kms:Decrypt, and kms:DescribeKey permissions on the key.

AgentCore optimizations supports only symmetric encryption KMS keys. The KMS key must be in the same AWS Region as the configuration bundle.

Configuring permissions to use a customer managed KMS key

The following key policy provides the minimum permissions required for configuration bundle encryption. The policy has two statements:

  • AllowCallerAccess – Allows the IAM user or role to validate the key via DescribeKey.

  • AllowCallerCryptoOps – Allows the IAM user or role to generate data keys and decrypt, scoped by encryption context.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*"
        }
      }
    }
  ]
}

The policy contains the following statements:

  • AllowCallerAccess – Grants the IAM role kms:DescribeKey permission for key validation at bundle creation or update time. Replace 111122223333 with your account ID and MyConfigBundleRole with the IAM role or user that manages configuration bundles.

  • AllowCallerCryptoOps – Grants the IAM role kms:GenerateDataKey and kms:Decrypt permissions, scoped by the aws:bedrock-agentcore:configurationBundleArn encryption context. Replace 111122223333, MyConfigBundleRole, and us-east-1 with your values. To allow access to all configuration bundles in your account, use a wildcard with StringLike: arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*.

Scoping down access to the customer managed KMS key

You can use the encryption context to scope down access to the customer managed key. AgentCore optimizations includes the following encryption context in all KMS operations:

{
  "aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/bundle-id"
}

You can use this encryption context in key policy conditions to restrict KMS operations to specific configuration bundles, as shown in the AllowCallerCryptoOps statement in the example key policy above.

Creating a configuration bundle with a customer managed KMS key

To encrypt a configuration bundle, specify the kmsKeyArn parameter when calling CreateConfigurationBundle.

Example
AWS CLI
aws bedrock-agentcore-control create-configuration-bundle \
  --bundle-name "MyEncryptedBundle" \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --components '{
    "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent": {
      "configuration": {
        "systemPrompt": "You are a helpful assistant.",
        "modelId": "anthropic.claude-3-sonnet"
      }
    }
  }'
Python (Boto3)
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_configuration_bundle(
    bundleName='MyEncryptedBundle',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    components={
        'arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent': {
            'configuration': {
                'systemPrompt': 'You are a helpful assistant.',
                'modelId': 'anthropic.claude-3-sonnet'
            }
        }
    }
)

print(f"Bundle ID: {response['bundleId']}")

Changing encryption configuration on an existing bundle

You can change the encryption configuration on an existing bundle using UpdateConfigurationBundle:

  • Add encryption – Specify a kmsKeyArn on a bundle that was created without one. The service generates a new DEK and encrypts the component configurations.

  • Rotate key – Specify a different kmsKeyArn. The service re-wraps the existing DEK from the old key to the new key using kms:ReEncrypt. The caller must have permissions on both keys. If the old key is unavailable (disabled, deleted, or missing permissions), the update will fail.

Note

You cannot remove customer managed key encryption from a configuration bundle once it has been added.

Monitoring KMS usage for configuration bundles

The following CloudTrail event names appear for configuration bundle KMS operations:

  • GenerateDataKey – When creating a bundle with a customer managed key, or adding encryption to an existing bundle. The encryptionContext field contains aws:bedrock-agentcore:configurationBundleArn.

  • Decrypt – When retrieving bundle content (GetConfigurationBundle, GetConfigurationBundleVersion) or when updating an encrypted bundle.

  • ReEncrypt – When rotating the KMS key on an existing bundle via UpdateConfigurationBundle.

  • DescribeKey – When validating the key at bundle creation or update time.

Behavior when a key becomes unavailable

If you disable or delete the customer managed KMS key used by a configuration bundle:

  • CreateConfigurationBundle – Fails at validation with ValidationException.

  • UpdateConfigurationBundle – Fails because the service cannot decrypt the existing DEK to re-encrypt new components. Key rotation also fails because the old key is unavailable for re-wrapping.

  • GetConfigurationBundle / GetConfigurationBundleVersion – Fails because the service cannot decrypt the DEK or the component configurations.

  • ListConfigurationBundles / ListConfigurationBundleVersions – Succeeds because listing returns metadata only and does not require KMS operations.

  • DeleteConfigurationBundle – Succeeds because deletion does not require decrypting bundle data.

To restore access, re-enable the key or update the key policy to grant the required permissions.