# Encrypting EventBridge connection authorization with AWS KMS keys Encrypting connections When you create or update a connection, you can specify authorization parameters for that connection. EventBridge then securely stores those parameters in a secret in AWS Secrets Manager. By default, EventBridge uses an AWS owned key to encrypt and decrypt this secret. You can specify that EventBridge use a customer managed key instead. ## AWS KMS key policy for connections Connection key policy The AWS KMS key policy must grant EventBridge the following permissions on your behalf: + `kms:DescribeKey` + `kms:GenerateDataKey` + `kms:Decrypt` The following policy example grants all AWS KMS permissions. ------ #### [ JSON ] **** ``` { "Id": "key-policy-example", "Version":"2012-10-17", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::012345678901:root" }, "Action": "kms:*", "Resource": "*" } ] } ``` ------ For EventBridge to use a customer managed key, you must add a resource tag to the key with a key of `EventBridgeApiDestinations` and a value of `true`. For more information on resource tags, see [Add tags to a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/add-tags.html) in the *AWS Key Management Service Developer Guide*. As a security best practice, we recommend you include condition keys in the key policy to helps ensure that EventBridge uses the KMS key only for the specified resource or account. For more information, see [Security considerations](eb-encryption-key-policy.md#eb-encryption-event-bus-confused-deputy). ``` "Condition": { "StringLike": { "kms:ViaService": "secretsmanager.*.amazonaws.com", "kms:EncryptionContext:SecretARN": [ "arn:aws:secretsmanager:*:*:secret:events!connection/*" ] }, "StringEquals": { "kms:ResourceTag/EventBridgeApiDestinations": "true" } } ``` ## Connection encryption context Encryption context An [encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) is a set of key–value pairs that contain arbitrary nonsecret data. When you include an encryption context in a request to encrypt data, AWS KMS cryptographically binds the encryption context to the encrypted data. To decrypt the data, you must pass in the same encryption context. You can also use the encryption context as a condition for authorization in policies and grants. If you use a customer managed key to protect your EventBridge resources, you can use the encryption context to identify use of the KMS key in audit records and logs. It also appears in plaintext in logs, such as [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) and [Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html). For connections, EventBridge uses the same encryption context in all AWS KMS cryptographic operations. The context includes a single key–value pair, which contains the secret ARN. ``` "encryptionContext": { "kms:EncryptionContext:SecretARN": "secret-arn" } ``` ## Using cross-account or cross-Region customer managed keys for connections Cross-account or Region keys You can allow users or roles in a different AWS account to use a KMS key in your account. Cross-account access requires permission in the key policy of the KMS key and in an IAM policy in the external user's account. To use a customer managed key from another account, the account with the customer managed key must include the following policy: ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::account:role/AmazonEventBridgeApiDestinationsInternalServiceRolePolicy" }, "Action": [ "kms:Decrypt", "kms:DescribeKey" ], "Resource": "*" } ``` For more information, see [ Allowing users in other accounts to use a KMS key ](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html) in the *AWS Key Management Service Developer Guide*. ## Revoking customer managed key access to connections Revoking AWS KMS key access Be aware that when you revoke a customer managed key--through disabling, deleting, or rotating the key, or updating the key policy--EventBridge may have cached the key value, and so that key may still retain access to a connection's secret for a short period of time. To immediately revoke customer managed key access to a connection's secret, de-authorize or delete the connection. For more information, see [De-authorizing connections](eb-target-connection-deauthorize.md) and [Deleting connections](eb-target-connection-delete.md). ## Connection de-authorization due to customer managed key errors Customer managed key errors EventBridge de-authorizes a connection if it encounters the following errors when attempting to encrypt or decrypt the connection's secret: + The customer managed key has been deleted. + The customer managed key has been disabled. + The connection does not have the necessary permissions to access the customer managed key. For more information, see [De-authorizing connections](eb-target-connection-deauthorize.md). # Configuring encryption on connections Configuring connection encryption You can specify the KMS key for EventBridge to use when you create or update a connection. ## Specifying AWS KMS keys when creating connections Specifying AWS KMS keys Choosing the AWS KMS key used for encryption is optional when creating a connection. By default, EventBridge uses an AWS owned key. **To specify a customer managed key for encryption when creating a connection (console)** + Follow these instructions: [Creating connections](eb-target-connection-create.md). **To specify a customer managed key for encryption when creating a connection (CLI)** + When calling `[create-connection](https://docs.aws.amazon.com/cli/latest/reference/events/create-connection.html)`, use the `kms-key-identifier` option to specify the customer managed key for EventBridge to use for encryption of the connection's secret. ## Updating AWS KMS keys for connections Updating AWS KMS keys You can update the KMS key being used for encrypting an existing connection. This includes: + Changing from the default AWS owned key to a customer managed key. + Changing from a customer managed key to the default AWS owned key. + Changing from one customer managed key to another. When you update a connection to use a different KMS key , EventBridge decrypts the connection's secret and then encrypts it using the new key. Make sure the KMS key you specify has the necessary permissions. For more information, see [Connection key policy](encryption-connections.md#encryption-connections-key-policy). **To update the KMS key used for encryption on a connection (console)** 1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/). 1. In the navigation pane, choose **Integration**, and then choose **Connections**. 1. Choose the connection you want to update. 1. On the connection details page, under **Encryption**, choose the KMS key for EventBridge to use when encrypting the connection's secret: + Choose **Use AWS owned key** for EventBridge to encrypt the secret using an AWS owned key. This AWS owned key is a KMS key that EventBridge owns and manages for use in multiple AWS accounts. In general, unless you are required to audit or control the encryption key that protects your resources, an AWS owned key is a good choice. This is the default. + Choose **Choose a different AWS KMS key (advanced)** for EventBridge to encrypt the secret using the customer managed key that you specify or create. Customer managed keys are KMS keys in your AWS account that you create, own, and manage. You have full control over these KMS keys. 1. Specify an existing customer managed key, or choose **Create a new KMS key**. Make sure the KMS key you specify has the necessary permissions. For more information, see [Connection key policy](encryption-connections.md#encryption-connections-key-policy). EventBridge displays the key status and any key aliases that have been associated with the specified customer managed key. **To update the KMS key used for encryption on a connection (CLI)** + When calling `[update-connection](https://docs.aws.amazon.com/cli/latest/reference/events/update-connection.html)`, use the `kms-key-identifier` option to specify the customer managed key for EventBridge to use for encrypting the connection secret.