View a markdown version of this page

Understanding parameter types - Amazon Systems Manager
Parameter type: StringParameter type: StringListParameter type: SecureString
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).

Understanding parameter types

A parameter is any piece of data stored in Parameter Store, such as a block of text, a list of names, an AMI ID, a license key, and so on. You can centrally and securely reference this data in your scripts, commands, and SSM documents.

When you reference a parameter, you specify the parameter name using the following convention.

{{ssm:parameter-name}}

Note

Parameters can't be referenced or nested in the values of other parameters. You can't include {{}} or {{ssm:parameter-name}} in a parameter value.

Parameter Store provides support for three types of parameters: String, StringList, and SecureString.

With one exception, when you create or update a parameter, you enter the parameter value as plaintext, and Parameter Store performs no validation on the text you enter. For String parameters, however, you can specify the data type as aws:ec2:image, and Parameter Store validates that the value you enter is the proper format for an Amazon EC2 AMI; for example: ami-12345abcdeEXAMPLE.

Parameter type: String

By default, the value of a String parameter consists of any block of text you enter. For example:

  • abc123

  • Example Corp

  • <img src="images/bannerImage1.png"/>

Parameter type: StringList

The values of StringList parameters contain a comma-separated list of values, as shown in the following examples.

Monday,Wednesday,Friday

CSV,TSV,CLF,ELF,JSON

Parameter type: SecureString

The value of a SecureString parameter is any sensitive data that needs to be stored and referenced in a secure manner. If you have data that you don't want users to alter or reference in plaintext, such as lightweight secrets or license keys, create those parameters using the SecureString data type.

We recommend using SecureString parameters for the following scenarios:

  • You want to use data/parameters across Amazon Web Services services without exposing the values as plaintext in commands, functions, agent logs, or CloudTrail logs.

  • You want to control who has access to sensitive data.

  • You want to be able to audit when sensitive data is accessed (CloudTrail).

  • You want to encrypt your sensitive data, and you want to bring your own encryption keys to manage access.

You can use the SecureString parameter type for textual data that you want to encrypt, such as lightweight secrets that don't require rotation, confidential configuration data, or any other types of data that you want to protect. SecureString data is encrypted and decrypted using an Amazon KMS key. You can use either a default KMS key provided by Amazon or create and use your own Amazon KMS key. (Use your own Amazon KMS key if you want to restrict user access to SecureString parameters. For more information, see IAM permissions for using Amazon default keys and customer managed keys.)

Important

Note the following important information.

  • If you manage credentials that require automatic rotation, cross-account access, or fine-grained audit logging, we recommend using Amazon Secrets Manager. Secrets Manager is purpose-built for managing secrets such as database credentials, API keys, and supported third-party software-vended secrets. For more information, see What is Amazon Secrets Manager? in the Amazon Secrets Manager User Guide.

  • Don't store sensitive data in a String or StringList parameter. For all sensitive data that must remain encrypted, use only the SecureString parameter type.

  • Only the value of a SecureString parameter is encrypted. Parameter names, descriptions, and other properties aren't encrypted.

You can also use SecureString parameters with other Amazon Web Services services. In the following example, the Lambda function retrieves a SecureString parameter by using the GetParameters API.

import json
import boto3
ssm = boto3.client('ssm', 'us-east-2')
def get_parameters():
    response = ssm.get_parameters(
        Names=['LambdaSecureString'],WithDecryption=True
    )
    for parameter in response['Parameters']:
        return parameter['Value']
        
def lambda_handler(event, context):
    value = get_parameters()
    print("value1 = " + value)
    return value  # Echo back the first key value
Amazon KMS encryption and pricing

If you choose the SecureString parameter type when you create your parameter, Systems Manager uses Amazon KMS to encrypt the parameter value.

Important

Parameter Store only supports symmetric encryption KMS keys. You can't use an asymmetric encryption KMS key to encrypt your parameters. For help determining whether a KMS key is symmetric or asymmetric, see Identifying symmetric and asymmetric KMS keys in the Amazon Key Management Service Developer Guide

There is no charge from Parameter Store to create a SecureString parameter, but charges for use of Amazon KMS encryption do apply. For information, see Amazon Key Management Service pricing.

For more information about Amazon managed keys and customer managed keys, see Amazon Key Management Service Concepts in the Amazon Key Management Service Developer Guide. For more information about Parameter Store and Amazon KMS encryption, see How Amazon Systems Manager Parameter Store Uses Amazon KMS.

Note

To view an Amazon managed key, use the Amazon KMS DescribeKey operation. This Amazon Command Line Interface (Amazon CLI) example uses DescribeKey to view an Amazon managed key.

aws kms describe-key --key-id alias/aws/ssm