AWS KMS encryption for AWS Systems Manager Parameter Store SecureString parameters
With AWS Systems Manager Parameter Store, you can create SecureString parameters, which are parameters that have a plaintext
parameter name and an encrypted parameter value. Parameter Store uses AWS KMS to encrypt and
decrypt the parameter values of SecureString
parameters.
With Parameter Store, you can create, store, and manage data as parameters with values. You can create a parameter in Parameter Store and use it in multiple applications and services subject to policies and permissions that you design. When you need to change a parameter value, you change one instance, rather than managing error-prone changes to numerous sources. Parameter Store supports a hierarchical structure for parameter names, so you can qualify a parameter for specific uses.
To manage sensitive data, you can create SecureString
parameters.
Parameter Store uses AWS KMS keys to encrypt the parameter values of
SecureString
parameters when you create or change them. It also
uses KMS keys to decrypt the parameter values when you access them. You can use
the AWS managed key that Parameter Store creates for your account or specify
your own customer managed key.
Important
Parameter Store supports only symmetric KMS keys. You cannot use an asymmetric KMS key to encrypt your parameters. For help determining whether a KMS key is symmetric or asymmetric, see Identify different key types in the AWS Key Management Service Developer Guide.
Parameter Store supports two tiers of SecureString
parameters: standard and advanced. Standard parameters, which cannot exceed 4096 bytes, are
encrypted and decrypted directly under the KMS key that you specify. To encrypt
and decrypt advanced SecureString
parameters, Parameter Store uses envelope
encryption with the AWS Encryption SDK. You can
convert a standard SecureString
parameter to an advanced parameter, but
you cannot convert an advanced parameter to a standard one. For more information
about the difference between standard and advanced SecureString
parameters, see Managing parameter
tiers.
Topics
Protecting standard SecureString parameters
Parameter Store does not perform any cryptographic operations. Instead, it relies on
AWS KMS to encrypt and decrypt SecureString
parameter values. When
you create or change a standard SecureString
parameter value,
Parameter Store calls the AWS KMS Encrypt operation. This operation uses a symmetric encryption
KMS key directly to encrypt the parameter value instead of using the KMS key
to generate a data key.
You can select the KMS key that Parameter Store uses to encrypt the parameter
value. If you do not specify a KMS key, Parameter Store uses the AWS managed key
that Systems Manager automatically creates in your account. This KMS key has the
aws/ssm
alias.
To view the default aws/ssm
KMS key for your account, use the
DescribeKey operation
in the AWS KMS API. The following example uses the describe-key
command in the AWS Command Line Interface (AWS CLI) with the aws/ssm
alias
name.
aws kms describe-key \ --key-id alias/aws/ssm
To create a standard SecureString
parameter, use the PutParameter operation in
the Systems Manager API. Omit the Tier
parameter or specify a value of
Standard
, which is the default. Include a Type
parameter with a value of SecureString
. To specify a KMS key, use
the KeyId
parameter. The default is the AWS managed key for your
account, aws/ssm
.
Parameter Store then calls the AWS KMS Encrypt
operation with the
KMS key and the plaintext parameter value. AWS KMS returns the encrypted
parameter value, which Parameter Store stores with the parameter name.
The following example uses the Systems Manager put-parameter command and
its --type
parameter in the AWS CLI to create a
SecureString
parameter. Because the command omits the optional
--tier
and --key-id
parameters, Parameter Store creates a
standard SecureString
parameter and encrypts it under the
AWS managed key.
aws ssm put-parameter \ --name MyParameter \ --value "secret_value" \ --type SecureString
The following similar example uses the --key-id
parameter to
specify a customer managed key. The example uses a KMS key ID to identify the
KMS key, but you can use any valid KMS key identifier. Because the command
omits the Tier
parameter (--tier
), Parameter Store creates a
standard SecureString
parameter, not an advanced one.
aws ssm put-parameter \ --name param1 \ --value "secret" \ --type SecureString \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
When you get a SecureString
parameter from Parameter Store, its value is
encrypted. To get a parameter, use the GetParameter operation in
the Systems Manager API.
The following example uses the Systems Manager get-parameter command in
the AWS CLI to get the MyParameter
parameter from Parameter Store without
decrypting its value.
aws ssm get-parameter --name MyParameter
{ "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg" } }
To decrypt the parameter value before returning it, set the
WithDecryption
parameter of GetParameter
to
true
. When you use WithDecryption
, Parameter Store calls
the AWS KMS Decrypt operation
on your behalf to decrypt the parameter value. As a result, the
GetParameter
request returns the parameter with a plaintext
parameter value, as shown in the following example.
aws ssm get-parameter \ --name MyParameter \ --with-decryption
{ "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "secret_value" } }
The following workflow shows how Parameter Store uses a KMS key to encrypt and
decrypt a standard SecureString
parameter.
Encrypt a standard parameter
-
When you use
PutParameter
to create aSecureString
parameter, Parameter Store sends anEncrypt
request to AWS KMS. That request includes the plaintext parameter value, the KMS key that you chose, and the Parameter Store encryption context. During transmission to AWS KMS, the plaintext value in theSecureString
parameter is protected by Transport Layer Security (TLS). -
AWS KMS encrypts the parameter value with the specified KMS key and encryption context. It returns the ciphertext to Parameter Store, which stores the parameter name and its encrypted value.
Decrypt a standard parameter
-
When you include the
WithDecryption
parameter in aGetParameter
request, Parameter Store sends aDecrypt
request to AWS KMS with the encryptedSecureString
parameter value and the Parameter Store encryption context. -
AWS KMS uses the same KMS key and the supplied encryption context to decrypt the encrypted value. It returns the plaintext (decrypted) parameter value to Parameter Store. During transmission, the plaintext data is protected by TLS.
-
Parameter Store returns the plaintext parameter value to you in the
GetParameter
response.
Protecting advanced SecureString parameters
When you use PutParameter
to create an advanced
SecureString
parameter, Parameter Store uses envelope
encryption with the AWS Encryption SDK and a symmetric encryption
AWS KMS key to protect the parameter value. Each advanced parameter value is
encrypted under a unique data key, and the data key is encrypted under a
KMS key. You can use the AWS managed key for the account (aws/ssm
) or any
customer managed key.
The AWS Encryption SDK is an open-source, client-side library that helps you to encrypt and decrypt data using industry standards and best practices. It's supported on multiple platforms and in multiple programming languages, including a command-line interface. You can view the source code and contribute to its development in GitHub.
For each SecureString
parameter value, Parameter Store calls the
AWS Encryption SDK to encrypt the parameter value using a unique data key that AWS KMS
generates (GenerateDataKey). The AWS Encryption SDK returns to Parameter Store an encrypted message
that includes the encrypted parameter value and an encrypted copy of the unique
data key. Parameter Store stores the entire encrypted message in the
SecureString
parameter value. Then, when you get an advanced
SecureString
parameter value, Parameter Store uses the AWS Encryption SDK to
decrypt the parameter value. This requires a call to AWS KMS to decrypt the
encrypted data key.
To create an advanced SecureString
parameter, use the PutParameter operation in
the Systems Manager API. Set the value of Tier
parameter to
Advanced
. Include a Type
parameter with a value of
SecureString
. To specify a KMS key, use the
KeyId
parameter. The default is the AWS managed key for your
account, aws/ssm
.
aws ssm put-parameter \ --name MyParameter \ --value "secret_value" \ --type SecureString \ --tier Advanced
The following similar example uses the --key-id
parameter to
specify a customer managed key. The example uses the Amazon Resource Name (ARN) of the
KMS key, but you can use any valid KMS key identifier.
aws ssm put-parameter \ --name MyParameter \ --value "secret_value" \ --type SecureString \ --tier Advanced \ --key-id arn:aws:kms:us-east-2:987654321098:key/1234abcd-12ab-34cd-56ef-1234567890ab
When you get a SecureString
parameter from Parameter Store, its value is
the encrypted message that the AWS Encryption SDK returned. To get a parameter, use the
GetParameter
operation in the Systems Manager API.
The following example uses the Systems Manager GetParameter
operation to
get the MyParameter
parameter from Parameter Store without decrypting its
value.
aws ssm get-parameter --name MyParameter
{ "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg" } }
To decrypt the parameter value before returning it, set the
WithDecryption
parameter of GetParameter
to
true
. When you use WithDecryption
, Parameter Store calls
the AWS KMS Decrypt operation
on your behalf to decrypt the parameter value. As a result, the
GetParameter
request returns the parameter with a plaintext
parameter value, as shown in the following example.
aws ssm get-parameter \ --name MyParameter \ --with-decryption
{ "Parameter": { "Type": "SecureString", "Name": "MyParameter", "Value": "secret_value" } }
You cannot convert an advanced SecureString
parameter to a
standard one, but you can convert a standard SecureString
to an
advanced one. To convert a standard SecureString
parameter to an
advanced SecureString
, use the PutParameter
operation
with the Overwrite
parameter. The Type
must be
SecureString
and the Tier
value must be
Advanced
. The KeyId
parameter, which identifies a
customer managed key, is optional. If you omit it, Parameter Store uses the AWS managed key for
the account. You can specify any KMS key that the principal has permission to
use, even if you used a different KMS key to encrypt the standard
parameter.
When you use the Overwrite
parameter, Parameter Store uses the
AWS Encryption SDK to encrypt the parameter value. Then it stores the newly encrypted
message in Parameter Store.
aws ssm put-parameter \ --name myStdParameter \ --value "secret_value" \ --type SecureString \ --tier Advanced \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --overwrite
The following workflow shows how Parameter Store uses a KMS key to encrypt and
decrypt an advanced SecureString
parameter.
Encrypt an advanced parameter
-
When you use
PutParameter
to create an advancedSecureString
parameter, Parameter Store uses the AWS Encryption SDK and AWS KMS to encrypt the parameter value. Parameter Store calls the AWS Encryption SDK with the parameter value, the KMS key that you specified, and the Parameter Store encryption context. -
The AWS Encryption SDK sends a GenerateDataKey request to AWS KMS with the identifier of the KMS key that you specified and the Parameter Store encryption context. AWS KMS returns two copies of the unique data key: one in plaintext and one encrypted under the KMS key. (The encryption context is used when encrypting the data key.)
-
The AWS Encryption SDK uses the plaintext data key to encrypt the parameter value. It returns an encrypted message that includes the encrypted parameter value, the encrypted data key, and other data, including the Parameter Store encryption context.
-
Parameter Store stores the encrypted message as the parameter value.
Decrypt an advanced parameter
-
You can include the
WithDecryption
parameter in aGetParameter
request to get an advancedSecureString
parameter. When you do, Parameter Store passes the encrypted message from the parameter value to a decryption method of the AWS Encryption SDK. -
The AWS Encryption SDK calls the AWS KMS Decrypt operation. It passes in the encrypted data key and the Parameter Store encryption context from the encrypted message.
-
AWS KMS uses the KMS key and the Parameter Store encryption context to decrypt the encrypted data key. Then it returns the plaintext (decrypted) data key to the AWS Encryption SDK.
-
The AWS Encryption SDK uses the plaintext data key to decrypt the parameter value. It returns the plaintext parameter value to Parameter Store.
-
Parameter Store verifies the encryption context and returns the plaintext parameter value to you in the
GetParameter
response.
Setting permissions to encrypt and decrypt parameter values
To encrypt a standard SecureString
parameter value, the user
needs kms:Encrypt
permission. To encrypt an advanced
SecureString
parameter value, the user needs
kms:GenerateDataKey
permission. To decrypt either type of
SecureString
parameter value, the user needs
kms:Decrypt
permission.
You can use AWS Identity and Access Management (IAM) policies to allow or deny permission for a user
to call the Systems Manager PutParameter
and GetParameter
operations.
If you are using customer managed keys to encrypt your SecureString
parameter values, you can use IAM policies and key policies to manage encrypt
and decrypt permissions. However, you cannot establish access control policies
for the default aws/ssm
KMS key. For detailed information about
controlling access to customer managed keys, see KMS key access and
permissions in the AWS Key Management Service Developer
Guide.
The following example shows an IAM policy designed for standard
SecureString
parameters. It allows the user to call the Systems Manager
PutParameter
operation on all parameters in the
FinancialParameters
path. The policy also allows the user to
call the AWS KMS Encrypt
operation on an example customer managed key.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:PutParameter" ], "Resource": "arn:aws:ssm:us-east-2:111122223333:parameter/FinancialParameters/*" }, { "Effect": "Allow", "Action": [ "kms:Encrypt" ], "Resource": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ] }
The next example shows an IAM policy that is designed for advanced
SecureString
parameters. It allows the user to call the Systems Manager
PutParameter
operation on all parameters in the
ReservedParameters
path. The policy also allows the user to
call the AWS KMS GenerateDataKey
operation on an example
customer managed key.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:PutParameter" ], "Resource": "arn:aws:ssm:us-east-2:111122223333:parameter/ReservedParameters/*" }, { "Effect": "Allow", "Action": [ "kms:GenerateDataKey" ], "Resource": "arn:aws:kms:us-east-2:987654321098:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ] }
The final example also shows an IAM policy that can be used for standard or
advanced SecureString
parameters. It allows the user to call the
Systems Manager GetParameter
operations (and related operations) on all
parameters in the ITParameters
path. The policy also allows the
user to call the AWS KMS Decrypt
operation on an example
customer managed key.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameter*" ], "Resource": "arn:aws:ssm:us-east-2:111122223333:parameter/ITParameters/*" }, { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } ] }
Parameter Store 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.
You can also use the encryption context to identify a cryptographic operation in audit records and logs. The encryption context appears in plaintext in logs, such as AWS CloudTrail logs.
The AWS Encryption SDK also takes an encryption context, although it handles it differently. Parameter Store supplies the encryption context to the encryption method. The AWS Encryption SDK cryptographically binds the encryption context to the encrypted data. It also includes the encryption context in plain text in the header of the encrypted message that it returns. However, unlike AWS KMS, the AWS Encryption SDK decryption methods do not take an encryption context as input. Instead, when it decrypts data, the AWS Encryption SDK gets the encryption context from the encrypted message. Parameter Store verifies that the encryption context includes the value that it expects before returning the plaintext parameter value to you.
Parameter Store uses the following encryption context in its cryptographic operations:
-
Key:
PARAMETER_ARN
-
Value: The Amazon Resource Name (ARN) of the parameter that is being encrypted.
The format of the encryption context is as follows:
"PARAMETER_ARN":"arn:aws:ssm:
region-id
:account-id
:parameter/parameter-name
"
For example, Parameter Store includes this encryption context in calls to encrypt and
decrypt the MyParameter
parameter in an example AWS account and
region.
"PARAMETER_ARN":"arn:aws:ssm:us-east-2:111122223333:parameter/MyParameter"
If the parameter is in a Parameter Store hierarchical path, the path and name are
included in the encryption context. For example, this encryption context is used
when encrypting and decrypting the MyParameter
parameter in the
/ReadableParameters
path in an example AWS account and
region.
"PARAMETER_ARN":"arn:aws:ssm:us-east-2:111122223333:parameter/ReadableParameters/MyParameter"
You can decrypt an encrypted SecureString
parameter value by
calling the AWS KMS Decrypt
operation with the correct encryption
context and the encrypted parameter value that the Systems Manager
GetParameter
operation returns. However, we encourage you to
decrypt Parameter Store parameter values by using the GetParameter
operation with the WithDecryption
parameter.
You can also include the encryption context in an IAM policy. For example, you can permit a user to decrypt only one particular parameter value or set of parameter values.
The following example IAM policy statement allows the user to the get value
of the MyParameter
parameter and to decrypt its value using the
specified KMS key. However the permissions apply only when the encryption
context matches specified string. These permissions do not apply to any other
parameter or KMS key, and the call to GetParameter
fails if the
encryption context does not match the string.
Before using a policy statement like this one, replace the
example ARNs
with valid values.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameter*" ], "Resource": "
arn:aws:ssm:us-east-2:111122223333:parameter/MyParameter
" }, { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-2:987654321098:key/1234abcd-12ab-34cd-56ef-1234567890ab
", "Condition": { "StringEquals": { "kms:EncryptionContext:PARAMETER_ARN":"arn:aws:ssm:us-east-2:111122223333:parameter/MyParameter
" } } } ] }
Troubleshooting KMS key issues in Parameter Store
To perform any operation on a SecureString
parameter, Parameter Store
must be able to use the AWS KMS KMS key that you specify for your intended
operation. Most of the Parameter Store failures related to KMS keys are caused by the
following problems:
-
The credentials that an application is using do not have permission to perform the specified action on the KMS key.
To fix this error, run the application with different credentials or revise the IAM or key policy that is preventing the operation. For help with AWS KMS IAM and key policies, see KMS key access and permissions in the AWS Key Management Service Developer Guide.
-
The KMS key is not found.
This typically happens when you use an incorrect identifier for the KMS key. Find the correct identifiers for the KMS key and try the command again.
-
The KMS key is not enabled. When this occurs, Parameter Store returns an
InvalidKeyId
exception with a detailed error message from AWS KMS. If the KMS key state isDisabled
, enable it. If it isPending Import
, complete the import procedure. If the key state isPending Deletion
, cancel the key deletion or use a different KMS key.To find the key state of a KMS key, use the DescribeKey operation.