Secret encryption and decryption in AWS Secrets Manager
Secrets Manager uses envelope encryption with AWS KMS keys and data keys to protect each secret value. Whenever the secret value in a secret changes, Secrets Manager requests a new data key from AWS KMS to protect it. The data key is encrypted under a KMS key and stored in the metadata of the secret. To decrypt the secret, Secrets Manager first decrypts the encrypted data key using the KMS key in AWS KMS.
Secrets Manager does not use the KMS key to encrypt the secret value directly. Instead, it uses the KMS key to generate and encrypt a 256-bit Advanced Encryption Standard (AES) symmetric data key, and uses the data key to encrypt the secret value. Secrets Manager uses the plaintext data key to encrypt the secret value outside of AWS KMS, and then removes it from memory. It stores the encrypted copy of the data key in the metadata of the secret.
Topics
Choosing a AWS KMS key
When you create a secret, you can choose any symmetric encryption customer managed key in the
AWS account and Region, or you can use the AWS managed key for Secrets Manager
(aws/secretsmanager
). If you choose the AWS managed key aws/secretsmanager
and it doesn't already exist yet, Secrets Manager creates it and associates it with the secret. You can use the same KMS key or
different KMS keys for each secret in your account. You might want to use different KMS keys
to set custom permissions on the keys for a group of secrets, or if you want to audit
particular operations for those keys. Secrets Manager supports only symmetric
encryption KMS keys. If you use a KMS key in an external key store, cryptographic operations on the KMS key might take longer and be less reliable and durable because the request has to travel outside of AWS.
For information about changing the encryption key for a secret, see Change the encryption key for an AWS Secrets Manager secret.
When you change the encryption key, Secrets Manager re-encrypts AWSCURRENT
, AWSPENDING
, and AWSPREVIOUS
versions with the new key. To avoid locking you out of the secret, Secrets Manager keeps all existing versions encrypted with the previous key. That means you can decrypt AWSCURRENT
, AWSPENDING
, and AWSPREVIOUS
versions with the previous key or the new key. If you don't have kms:Decrypt
permission to the previous key, when you change the encryption key, Secrets Manager can't decrypt the secret versions to re-encrypt them. In this case, the existing versions are not re-encrypted.
To make it so AWSCURRENT
can only be decrypted by the new encryption key, create a new version of the secret with the new key. Then to be able to decrypt the AWSCURRENT
secret version, you must have permission to the new key.
You can deny permission to the AWS managed key aws/secretsmanager
and require secrets are encrypted with a customer managed key. For more information, see Example: Deny a specific AWS KMS key to encrypt secrets.
To find the KMS key associated with a secret, view the secret in the console or call
ListSecrets or DescribeSecret. When the secret is
associated with the AWS managed key for Secrets Manager (aws/secretsmanager
), these
operations do not return a KMS key identifier.
What is encrypted?
Secrets Manager encrypts the secret value, but it does not encrypt the following:
-
Secret name and description
-
Rotation settings
-
ARN of the KMS key associated with the secret
-
Any attached AWS tags
Encryption and decryption processes
To encrypt the secret value in a secret, Secrets Manager uses the following process.
-
Secrets Manager calls the AWS KMS GenerateDataKey operation with the ID of the KMS key for the secret and a request for a 256-bit AES symmetric key. AWS KMS returns a plaintext data key and a copy of that data key encrypted under the KMS key.
-
Secrets Manager uses the plaintext data key and the Advanced Encryption Standard (AES) algorithm to encrypt the secret value outside of AWS KMS. It removes the plaintext key from memory as soon as possible after using it.
-
Secrets Manager stores the encrypted data key in the metadata of the secret so it is available to decrypt the secret value. However, none of the Secrets Manager APIs return the encrypted secret or the encrypted data key.
To decrypt an encrypted secret value:
-
Secrets Manager calls the AWS KMS Decrypt operation and passes in the encrypted data key.
-
AWS KMS uses the KMS key for the secret to decrypt the data key. It returns the plaintext data key.
-
Secrets Manager uses the plaintext data key to decrypt the secret value. Then it removes the data key from memory as soon as possible.
Permissions for the KMS key
When Secrets Manager uses a KMS key in cryptographic operations, it acts on behalf of the user who is accessing or updating the secret value. You can grant permissions in an IAM policy or a key policy. The following Secrets Manager operations require AWS KMS permissions.
To allow the KMS key to be used only for requests that originate in Secrets Manager, in the permissions policy, you can use
the kms:ViaService condition key with the
secretsmanager.
value.<Region>
.amazonaws.com
You can also use the keys or values in the encryption context as a condition for using the KMS key for cryptographic operations. For example, you can use a string condition operator in an IAM or key policy document, or use a grant constraint in a grant. KMS key grant propagation can take up to five minutes. For more information, see CreateGrant.
How Secrets Manager uses your KMS key
Secrets Manager calls the following AWS KMS operations with your KMS key.
- GenerateDataKey
-
Secrets Manager calls the AWS KMS GenerateDataKey operation in response to the following Secrets Manager operations.
-
CreateSecret – If the new secret includes a secret value, Secrets Manager requests a new data key to encrypt it.
-
PutSecretValue – Secrets Manager requests a new data key to encrypt the specified secret value.
-
ReplicateSecretToRegions – To encrypt the replicated secret, Secrets Manager requests a data key for the KMS key in the replica Region.
-
UpdateSecret – If you change the secret value or the KMS key, Secrets Manager requests a new data key to encrypt the new secret value.
The RotateSecret operation does not call
GenerateDataKey
, because it does not change the secret value. However, ifRotateSecret
invokes a Lambda rotation function that changes the secret value, its call to thePutSecretValue
operation triggers aGenerateDataKey
request. -
- Decrypt
-
Secrets Manager calls the Decrypt operation in response to the following Secrets Manager operations.
-
GetSecretValue and BatchGetSecretValue – Secrets Manager decrypts the secret value before returning it to the caller. To decrypt an encrypted secret value, Secrets Manager calls the AWS KMS Decrypt operation to decrypt the encrypted data key in the secret. Then, it uses the plaintext data key to decrypt the encrypted secret value. For batch commands, Secrets Manager can reuse the decrypted key, so not all calls result in a
Decrypt
request. -
PutSecretValue and UpdateSecret – Most
PutSecretValue
andUpdateSecret
requests do not trigger aDecrypt
operation. However, when aPutSecretValue
orUpdateSecret
request attempts to change the secret value in an existing version of a secret, Secrets Manager decrypts the existing secret value and compares it to the secret value in the request to confirm that they are the same. This action ensures the that Secrets Manager operations are idempotent. To decrypt an encrypted secret value, Secrets Manager calls the AWS KMS Decrypt operation to decrypt the encrypted data key in the secret. Then, it uses the plaintext data key to decrypt the encrypted secret value. -
ReplicateSecretToRegions – Secrets Manager first decrypts the secret value in the primary Region before re-encrypting the secret value with the KMS key in the replica Region.
-
- Encrypt
-
Secrets Manager calls the Encrypt operation in response to the following Secrets Manager operations:
-
UpdateSecret – If you change the KMS key, Secrets Manager re-encrypts the data key that protects the
AWSCURRENT
,AWSPREVIOUS
, andAWSPENDING
secret versions with the new key. -
ReplicateSecretToRegions – Secrets Manager re-encrypts the data key during replication using the KMS key in the replica Region.
-
- DescribeKey
-
Secrets Manager calls the DescribeKey operation to determine whether to list the KMS key when you create or edit a secret in the Secrets Manager console.
- Validating access to the KMS key
-
When you establish or change the KMS key that is associated with secret, Secrets Manager calls the
GenerateDataKey
andDecrypt
operations with the specified KMS key. These calls confirm that the caller has permission to use the KMS key for these operation. Secrets Manager discards the results of these operations; it does not use them in any cryptographic operation.You can identify these validation calls because the value of the
SecretVersionId
key encryption context in these requests isRequestToValidateKeyAccess
.Note
In the past, Secrets Manager validation calls did not include an encryption context. You might find calls with no encryption context in older AWS CloudTrail logs.
Key policy of the AWS managed key
(aws/secretsmanager
)
The key policy for the AWS managed key for Secrets Manager (aws/secretsmanager
)
gives users permission to use the KMS key for specified operations only when Secrets Manager makes
the request on the user's behalf. The key policy does not allow any user to use the
KMS key directly.
This key policy, like the policies of all AWS managed keys, is established by the service. You cannot change the key policy, but you can view it at any time. For details, see Viewing a key policy.
The policy statements in the key policy have the following effect:
-
Allow users in the account to use the KMS key for cryptographic operations only when the request comes from Secrets Manager on their behalf. The
kms:ViaService
condition key enforces this restriction. -
Allows the AWS account to create IAM policies that allow users to view KMS key properties and revoke grants.
-
Although Secrets Manager does not use grants to gain access to the KMS key, the policy also allows Secrets Manager to create grants for the KMS key on the user's behalf and allows the account to revoke any grant that allows Secrets Manager to use the KMS key. These are standard elements of policy document for an AWS managed key.
The following is a key policy for an example AWS managed key for Secrets Manager.
{ "Id": "auto-secretsmanager-2", "Version": "2012-10-17", "Statement": [ { "Sid": "Allow access through AWS Secrets Manager for all principals in the account that are authorized to use AWS Secrets Manager", "Effect": "Allow", "Principal": { "AWS": [ "*" ] }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:CreateGrant", "kms:DescribeKey" ], "Resource": "*", "Condition": { "StringEquals": { "kms:CallerAccount": "111122223333", "kms:ViaService": "secretsmanager.us-west-2.amazonaws.com" } } }, { "Sid": "Allow access through AWS Secrets Manager for all principals in the account that are authorized to use AWS Secrets Manager", "Effect": "Allow", "Principal": { "AWS": [ "*" ] }, "Action": "kms:GenerateDataKey*", "Resource": "*", "Condition": { "StringEquals": { "kms:CallerAccount": "111122223333" }, "StringLike": { "kms:ViaService": "secretsmanager.us-west-2.amazonaws.com" } } }, { "Sid": "Allow direct access to key metadata to the account", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:root" ] }, "Action": [ "kms:Describe*", "kms:Get*", "kms:List*", "kms:RevokeGrant" ], "Resource": "*" } ] }
Secrets Manager encryption context
An encryption 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.
In its GenerateDataKey and Decrypt requests to AWS KMS, Secrets Manager uses an encryption context with two name–value pairs that identify the secret and its version, as shown in the following example. The names do not vary, but combined encryption context values will be different for each secret value.
"encryptionContext": { "SecretARN": "arn:aws:secretsmanager:us-east-2:111122223333:secret:test-secret-a1b2c3", "SecretVersionId": "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1" }
You can use the encryption context to identify these cryptographic operation in audit records and logs, such as AWS CloudTrail and Amazon CloudWatch Logs, and as a condition for authorization in policies and grants.
The Secrets Manager encryption context consists of two name-value pairs.
-
SecretARN – The first name–value pair identifies the secret. The key is
SecretARN
. The value is the Amazon Resource Name (ARN) of the secret."SecretARN": "
ARN of an Secrets Manager secret
"For example, if the ARN of the secret is
arn:aws:secretsmanager:us-east-2:111122223333:secret:test-secret-a1b2c3
, the encryption context would include the following pair."SecretARN": "arn:aws:secretsmanager:us-east-2:111122223333:secret:test-secret-a1b2c3"
-
SecretVersionId – The second name–value pair identifies the version of the secret. The key is
SecretVersionId
. The value is the version ID."SecretVersionId": "
<version-id>
"For example, if the version ID of the secret is
EXAMPLE1-90ab-cdef-fedc-ba987SECRET1
, the encryption context would include the following pair."SecretVersionId": "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1"
When you establish or change the KMS key for a secret, Secrets Manager sends GenerateDataKey and Decrypt requests to AWS KMS to validate that the caller has permission to use the KMS key for these operations. It discards the responses; it does not use them on the secret value.
In these validation requests, the value of the SecretARN
is the actual ARN of
the secret, but the SecretVersionId
value is
RequestToValidateKeyAccess
, as shown in the following example encryption
context. This special value helps you to identify validation requests in logs and audit
trails.
"encryptionContext": { "SecretARN": "arn:aws:secretsmanager:us-east-2:111122223333:secret:test-secret-a1b2c3", "SecretVersionId": "RequestToValidateKeyAccess" }
Note
In the past, Secrets Manager validation requests did not include an encryption context. You might find calls with no encryption context in older AWS CloudTrail logs.
Monitor Secrets Manager interaction with AWS KMS
You can use AWS CloudTrail and Amazon CloudWatch Logs to track the requests that Secrets Manager sends to AWS KMS on your behalf. For information about monitoring the use of secrets, see Monitor AWS Secrets Manager secrets.
- GenerateDataKey
-
When you create or change the secret value in a secret, Secrets Manager sends a GenerateDataKey request to AWS KMS that specifies the KMS key for the secret.
The event that records the
GenerateDataKey
operation is similar to the following example event. The request is invoked bysecretsmanager.amazonaws.com
. The parameters include the Amazon Resource Name (ARN) of the KMS key for the secret, a key specifier that requires a 256-bit key, and the encryption context that identifies the secret and version.{ "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "AROAIGDTESTANDEXAMPLE:user01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/user01", "accountId": "111122223333", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "2018-05-31T23:23:41Z" } }, "invokedBy": "secretsmanager.amazonaws.com" }, "eventTime": "2018-05-31T23:23:41Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateDataKey", "awsRegion": "us-east-2", "sourceIPAddress": "secretsmanager.amazonaws.com", "userAgent": "secretsmanager.amazonaws.com", "requestParameters": { "keyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "keySpec": "AES_256", "encryptionContext": { "SecretARN": "arn:aws:secretsmanager:us-east-2:111122223333:secret:test-secret-a1b2c3", "SecretVersionId": "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1" } }, "responseElements": null, "requestID": "a7d4dd6f-6529-11e8-9881-67744a270888", "eventID": "af7476b6-62d7-42c2-bc02-5ce86c21ed36", "readOnly": true, "resources": [ { "ARN": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "accountId": "111122223333", "type": "AWS::KMS::Key" } ], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" }
- Decrypt
-
When you get or change the secret value of a secret, Secrets Manager sends a Decrypt request to AWS KMS to decrypt the encrypted data key. For batch commands, Secrets Manager can reuse the decrypted key, so not all calls result in a
Decrypt
request.The event that records the
Decrypt
operation is similar to the following example event. The user is the principal in your AWS account who is accessing the table. The parameters include the encrypted table key (as a ciphertext blob) and the encryption context that identifies the table and the AWS account. AWS KMS derives the ID of the KMS key from the ciphertext.{ "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "AROAIGDTESTANDEXAMPLE:user01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/user01", "accountId": "111122223333", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "2018-05-31T23:36:09Z" } }, "invokedBy": "secretsmanager.amazonaws.com" }, "eventTime": "2018-05-31T23:36:09Z", "eventSource": "kms.amazonaws.com", "eventName": "Decrypt", "awsRegion": "us-east-2", "sourceIPAddress": "secretsmanager.amazonaws.com", "userAgent": "secretsmanager.amazonaws.com", "requestParameters": { "encryptionContext": { "SecretARN": "arn:aws:secretsmanager:us-east-2:111122223333:secret:test-secret-a1b2c3", "SecretVersionId": "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1" } }, "responseElements": null, "requestID": "658c6a08-652b-11e8-a6d4-ffee2046048a", "eventID": "f333ec5c-7fc1-46b1-b985-cbda13719611", "readOnly": true, "resources": [ { "ARN": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "accountId": "111122223333", "type": "AWS::KMS::Key" } ], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" }
- Encrypt
-
When you change the KMS key associated with a secret, Secrets Manager sends an Encrypt request to AWS KMS to re-encrypt the
AWSCURRENT
,AWSPREVIOUS
, andAWSPENDING
secret versions with the new key. When you replicate a secret to another Region, Secrets Manager also sends an Encrypt request to AWS KMS.The event that records the
Encrypt
operation is similar to the following example event. The user is the principal in your AWS account who is accessing the table.{ "eventVersion": "1.08", "userIdentity": { "type": "IAMUser", "principalId": "AROAIGDTESTANDEXAMPLE:user01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/user01", "accountId": "111122223333", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "sessionContext": { "attributes": { "creationDate": "2023-06-09T18:11:34Z", "mfaAuthenticated": "false" } }, "invokedBy": "secretsmanager.amazonaws.com" }, "eventTime": "2023-06-09T18:11:34Z", "eventSource": "kms.amazonaws.com", "eventName": "Encrypt", "awsRegion": "us-east-2", "sourceIPAddress": "secretsmanager.amazonaws.com", "userAgent": "secretsmanager.amazonaws.com", "requestParameters": { "keyId": "arn:aws:kms:us-east-2:111122223333:key/EXAMPLE1-f1c8-4dce-8777-aa071ddefdcc", "encryptionAlgorithm": "SYMMETRIC_DEFAULT", "encryptionContext": { "SecretARN": "arn:aws:secretsmanager:us-east-2:111122223333:secret:ChangeKeyTest-5yKnKS", "SecretVersionId": "EXAMPLE1-5c55-4d7c-9277-1b79a5e8bc50" } }, "responseElements": null, "requestID": "129bd54c-1975-4c00-9b03-f79f90e61d60", "eventID": "f7d9ff39-15ab-47d8-b94c-56586de4ab68", "readOnly": true, "resources": [ { "accountId": "AWS Internal", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/EXAMPLE1-f1c8-4dce-8777-aa071ddefdcc" } ], "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "111122223333", "eventCategory": "Management" }