Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon KMS encryption for Amazon Systems Manager Parameter Store SecureString parameters

With Amazon 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 Amazon 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 Amazon 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 Amazon managed key that Parameter Store creates for your account or specify your own customer managed key.

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 Amazon 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.

Protecting standard SecureString parameters

Parameter Store does not perform any cryptographic operations. Instead, it relies on Amazon KMS to encrypt and decrypt SecureString parameter values. When you create or change a standard SecureString parameter value, Parameter Store calls the Amazon 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 Amazon 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 Amazon KMS API. The following example uses the describe-key command in the Amazon Command Line Interface (Amazon 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 Amazon managed key for your account, aws/ssm.

Parameter Store then calls the Amazon KMS Encrypt operation with the KMS key and the plaintext parameter value. Amazon 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 Amazon 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 Amazon 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 Amazon 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 Amazon 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

Decrypt a standard parameter

Protecting advanced SecureString parameters

When you use PutParameter to create an advanced SecureString parameter, Parameter Store uses envelope encryption with the Amazon Encryption SDK and a symmetric encryption Amazon 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 Amazon managed key for the account (aws/ssm) or any customer managed key.

The Amazon 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 Amazon Encryption SDK to encrypt the parameter value using a unique data key that Amazon KMS generates (GenerateDataKey). The Amazon 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 Amazon Encryption SDK to decrypt the parameter value. This requires a call to Amazon 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 Amazon 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 Amazon 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 Amazon 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 Amazon 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 Amazon 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

Decrypt an advanced parameter

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 Amazon 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 Amazon 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 Amazon 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 Amazon 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 Amazon 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, Amazon 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 Amazon CloudTrail logs.

The Amazon Encryption SDK also takes an encryption context, although it handles it differently. Parameter Store supplies the encryption context to the encryption method. The Amazon 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 Amazon KMS, the Amazon Encryption SDK decryption methods do not take an encryption context as input. Instead, when it decrypts data, the Amazon 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:

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 Amazon Web Services 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 Amazon Web Services 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 Amazon 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 Amazon 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: