Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon Systems Manager Parameter Store 如何使用 Amazon KMS

通过使用 Amazon Systems Manager Parameter Store，您可以创建安全字符串参数，这些参数具有明文参数名称和加密的参数值。Parameter Store 使用 Amazon KMS 加密和解密安全字符串参数的参数值。

借助 Parameter Store，您可以将数据作为具有值的参数进行创建、存储和管理。您可以在 Parameter Store 中创建一个参数，然后在多个受您设计的策略和权限限制的应用程序和服务中使用该参数。在需要更改参数值时，您可以更改一个实例，而不是管理对众多源进行的更改，后者很容易出错。Parameter Store 支持参数名称采用分层结构，因此，您可以将某个参数限制为用于特定的用途。

要管理敏感数据，您可以创建安全字符串参数。在创建或更改安全字符串参数值时，Parameter Store 使用 Amazon KMS keys 加密它们的参数值。在访问这些参数值时，它也使用 KMS 密钥解密这些值。您可以使用 Parameter Store 为您的账户创建的 Amazon 托管式密钥，或者指定您自己的客户托管密钥。

Parameter Store 支持两个层级的安全字符串参数：标准和高级。不能超过 4096 字节的标准参数直接在指定的 KMS 密钥下进行加密和解密。为了加密和解密高级安全字符串参数，Parameter Store 将信封加密与 Amazon Encryption SDK 结合使用。您可以将标准安全字符串参数转换为高级参数，但不能将高级参数转换为标准参数。有关标准和高级安全字符串参数之间的差别的更多信息，请参阅 Amazon Systems Manager 用户指南中的关于 Systems Manager 高级参数。

保护标准安全字符串参数

Parameter Store 不执行任何加密操作。相反，它依赖于 Amazon KMS 加密和解密安全字符串参数值。在创建或更改标准参数值时，Parameter Store 会调用 Amazon KMS Encrypt 操作。该操作直接使用对称加密 KMS 密钥加密参数值，而不是使用 KMS 密钥生成数据密钥。

您可以选择 Parameter Store 使用的 KMS 密钥加密参数值。如果未指定 KMS 密钥，Parameter Store 将使用 Systems Manager 在您的账户中自动创建的 Amazon 托管式密钥。此 KMS 密钥具有 aws/ssm 别名。

要查看您账户的默认 aws/ssm KMS 密钥，请使用 Amazon KMS API 中的DescribeKey操作。以下示例在别名为 describe-key 的 Amazon Command Line Interface (Amazon CLI) 中使用 aws/ssm 命令。

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

要创建标准的安全字符串参数，请使用 Systems Manager API 中的PutParameter操作。省略 Tier 参数或指定 Standard 的值（它是默认值）。请包含具有 SecureString 值的 Type 参数。要指定 KMS 密钥，请使用 KeyId 参数。默认值为您的账户的 Amazon 托管式密钥，即 aws/ssm。

然后，Parameter Store 使用 KMS 密钥和明文参数值调用 Amazon KMS Encrypt 操作。Amazon KMS 返回加密的参数值， 将该值与参数名称一起存储。

以下示例在 Amazon CLI 中使用 Systems Manager put-parameter 命令及其 --type 参数创建安全字符串参数。由于该命令省略了可选的 --tier 和 --key-id 参数，因此，Parameter Store 将创建标准安全字符串参数，并在 Amazon 托管式密钥 下对其进行加密

aws ssm put-parameter --name MyParameter --value "secret_value" --type SecureString

以下类似的示例使用 --key-id 参数指定客户托管密钥。该示例使用 KMS 密钥 ID 标识 KMS 密钥，但您可以使用任何有效的 KMS 密钥标识符。由于该命令省略了 Tier 参数 (--tier)，因此，Parameter Store 将创建标准安全字符串参数而非高级参数。

aws ssm put-parameter --name param1 --value "secret" --type SecureString --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

从 Parameter Store 中获取安全字符串参数时，将对该参数值进行加密。要获取参数，请使用 Systems Manager API 中的GetParameter 操作。

以下示例在 Amazon CLI 中使用 Systems Manager get-parameter 命令从 Parameter Store 中获取 MyParameter 参数，而不解密该参数值。

$  aws ssm get-parameter --name MyParameter

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg/9E464VRo68cvwAAAG8wbQYJKoZIhvcNAQcGoGAwXgIBADBZBgkqhkiG9w0BBwEwHgYJYZZIAWUDBAEuMBEEDImYOw44gna0Jm00hAIBEIAsjgr7mum1EnnXzE3xM8bGle0oKYcfVCHtBkfjIeZGTgL6Hg0fSDnpMHdcSXY="
    }
}

要在返回之前解密参数值，请将 GetParameter 的 WithDecryption 参数设置为 true。在使用 WithDecryption 时，Parameter Store 代表您调用 Amazon KMS Decrypt 操作以解密该参数值。因此，GetParameter 请求返回参数以及明文参数值，如以下示例中所示。

$  aws ssm get-parameter --name MyParameter --with-decryption

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "secret_value"
    }
}

以下工作流程演示 Parameter Store 如何使用 KMS 密钥加密和解密标准安全字符串参数。

加密标准参数

解密标准参数

保护高级安全字符串参数

在使用 PutParameter 创建高级安全字符串参数时，Parameter Store 使用信封加密与 Amazon Encryption SDK 和对称加密 Amazon KMS key 来保护参数值。每个高级参数值都使用唯一数据密钥加密，数据密钥使用 KMS 密钥加密。您可以将 Amazon 托管式密钥 用于账户 (aws/ssm) 或任何客户托管密钥。

Amazon Encryption SDK 是一个开源客户端库，可帮助您使用行业标准和最佳实践来加密和解密数据。它在多个平台上受支持并支持多种编程语言，包括命令行界面。您可以在中查看源代码并为其开发做出贡献 GitHub。

对于每个安全字符串参数值，Parameter Store 会调用，使用Amazon KMS生成 (GenerateDataKey) 的唯一数据密钥对参数值进行加密。Amazon Encryption SDKAmazon Encryption SDK 向 Parameter Store 返回一条加密消息（其中包含加密参数值）和唯一数据密钥的加密副本。Parameter Store 将整个加密消息存储在安全字符串参数值中。之后，在您获取高级安全字符串参数值时，Parameter Store 使用 Amazon Encryption SDK 解密参数值。这需要调用 Amazon KMS 以解密加密的数据密钥。

要创建高级安全字符串参数，请使用 Systems Manager API 中的PutParameter操作。将 Tier 参数的值设置为 Advanced。请包含具有 SecureString 值的 Type 参数。要指定 KMS 密钥，请使用 KeyId 参数。默认值为您的账户的 Amazon 托管式密钥，即 aws/ssm。

aws ssm put-parameter --name MyParameter --value "secret_value" --type SecureString --tier Advanced

以下类似的示例使用 --key-id 参数指定客户托管密钥。此示例使用 KMS 密钥的 Amazon Resource Name (ARN)，但您可以使用任何有效的 KMS 密钥标识符。

aws ssm put-parameter --name MyParameter --value "secret_value" --type SecureString --tier Advanced --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

在从 Parameter Store 获取安全字符串参数时，其值为 Amazon Encryption SDK 所返回的加密消息。要获取参数，请使用 Systems Manager API 中的GetParameter 操作。

以下示例使用 Systems Manager GetParameter 操作从 Parameter Store 获取 MyParameter 参数，而不解密其值。

$  aws ssm get-parameter --name MyParameter

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg/9E464VRo68cvwAAAG8wbQYJKoZIhvcNAQcGoGAwXgIBADBZBgkqhkiG9w0BBwEwHgYJYZZIAWUDBAEuMBEEDImYOw44gna0Jm00hAIBEIAsjgr7mum1EnnXzE3xM8bGle0oKYcfVCHtBkfjIeZGTgL6Hg0fSDnpMHdcSXY="
    }
}

要在返回之前解密参数值，请将 GetParameter 的 WithDecryption 参数设置为 true。在使用 WithDecryption 时，Parameter Store 代表您调用 Amazon KMS Decrypt 操作以解密该参数值。因此，GetParameter 请求返回参数以及明文参数值，如以下示例中所示。

$  aws ssm get-parameter --name MyParameter --with-decryption

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "secret_value"
    }
}

您无法将高级安全字符串参数转换为标准参数，但可以将标准安全字符串参数转换为高级参数。要将标准安全字符串参数转换为高级安全字符串，请将 PutParameter 操作与 Overwrite 参数结合使用。Type 必须为 SecureString，并且 Tier 值必须为 Advanced。KeyId 参数（它标识客户托管密钥）是可选的。如果省略它，Parameter Store 将 Amazon 托管式密钥 用于账户。您可以指定委托人有权使用的任何 KMS 密钥，即使您使用不同的 KMS 密钥来加密标准参数也是如此。

当您使用 Overwrite 参数时，Parameter Store 使用 Amazon Encryption SDK 对参数值进行加密。然后，它会将新加密的消息存储在 Parameter Store 中。

$ aws ssm put-parameter --name myStdParameter --value "secret_value"  --type SecureString --tier Advanced --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --overwrite

以下工作流程演示 Parameter Store 如何使用 KMS 密钥加密和解密高级安全字符串参数。

加密高级参数

解密高级参数

设置权限以加密和解密参数值

要加密标准安全字符串参数值，用户需要 kms:Encrypt 权限。要加密高级安全字符串参数值，用户需要 kms:GenerateDataKey 权限。要解密任一类型的安全字符串参数值，用户需要 kms:Decrypt 权限。

您可以使用 IAM policy 允许或拒绝用户调用 Systems Manager PutParameter 和 GetParameter 操作的权限。

如果您使用客户托管密钥加密安全字符串参数值，则可使用 IAM policy 和密钥策略来管理加密和解密权限。不过，您无法为默认的 aws/ssm KMS 密钥制定访问控制策略。有关控制对客户托管密钥的访问的详细信息，请参阅 Amazon KMS 的身份验证和访问控制。

以下示例显示了一个用于标准安全字符串参数的 IAM policy。此策略允许用户对 FinancialParameters 路径中的所有参数调用 Systems Manager PutParameter 操作。此策略还允许用户对示例客户托管密钥调用 Amazon KMS Encrypt 操作。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:PutParameter"
            ],
            "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/FinancialParameters/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:Encrypt"
            ],
            "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ]
}

下一个示例显示用于高级安全字符串参数的 IAM policy。此策略允许用户对 ReservedParameters 路径中的所有参数调用 Systems Manager PutParameter 操作。此策略还允许用户对示例客户托管密钥调用 Amazon KMS GenerateDataKey 操作。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:PutParameter"
            ],
            "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/ReservedParameters/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey"
            ],
            "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ]
}

最后一个示例还显示了一个 IAM policy，该策略可用于标准或高级安全字符串参数。此策略允许用户对 ITParameters 路径中的所有参数调用 Systems Manager GetParameter 操作（以及相关操作）。此策略还允许用户对示例客户托管密钥调用 Amazon KMS Decrypt 操作。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:GetParameter*"
            ],
            "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/ITParameters/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ]
}

Parameter Store 加密上下文

加密上下文 是一组包含任意非机密数据的键值对。在请求中包含加密上下文以加密数据时，Amazon KMS 以加密方式将加密上下文绑定到加密的数据。要解密数据，您必须传入相同的加密上下文。

您还可以使用加密上下文在审核记录和日志中识别加密操作。加密上下文在日志中以明文形式显示，例如，Amazon CloudTrail 日志。

Amazon Encryption SDK 也接受加密上下文，尽管它以不同方式处理该上下文。Parameter Store 向加密方法提供加密上下文。Amazon Encryption SDK 以加密方式将加密上下文绑定到加密数据。它还以明文形式将加密上下文包含在其返回的加密消息的标头中。但与 Amazon KMS 不同，Amazon Encryption SDK 解密方法不将加密上下文作为输入。相反，当它解密数据时，Amazon Encryption SDK 会从加密的消息中获取加密上下文。Parameter Store 在向您返回明文参数值之前验证加密上下文中是否包含它所期望的值。

Parameter Store 在加密操作中使用以下加密上下文：

加密上下文的格式如下所示：

"PARAMETER_ARN":"arn:aws:ssm:<REGION_NAME>:<ACCOUNT_ID>:parameter/<parameter-name>"

例如，Parameter Store 在调用中包含此加密上下文，以在示例 Amazon Web Services 账户 和区域中加密和解密 MyParameter 参数。

"PARAMETER_ARN":"arn:aws:ssm:us-west-2:111122223333:parameter/MyParameter"

如果该参数位于 Parameter Store 分层路径中，则在加密上下文中包含路径和名称。例如，在示例 Amazon Web Services 账户 和区域中加密和解密 /ReadableParameters 路径中的 MyParameter 参数时，将使用此加密上下文。

"PARAMETER_ARN":"arn:aws:ssm:us-west-2:111122223333:parameter/ReadableParameters/MyParameter"

您可以使用正确的加密上下文和 Systems Manager GetParameter 操作返回的加密参数值调用 Amazon KMS Decrypt 操作，以解密加密的安全字符串参数值。不过，我们建议您将 GetParameter 操作与 WithDecryption 参数一起使用以解密 Parameter Store 参数值。

您还可以在 IAM policy 中包含加密上下文。例如，您可以允许用户仅解密某个特定参数值或一组参数值。

以下示例 IAM policy 语句允许用户获取 MyParameter 参数值，以及使用指定的 KMS 密钥解密该参数值。不过，只有在加密上下文与指定的字符串匹配时，这些权限才适用。这些权限不适用于任何其他参数或 KMS 密钥；如果加密上下文与该字符串不匹配，对 GetParameter 的调用将失败。

使用类似于此策略语句的策略语句之前，请使用有效值替换示例 ARN。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:GetParameter*"
            ],
            "Resource": "arn:aws:ssm:us-west-2:111122223333:parameter/MyParameter"
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "Condition": {
                "StringEquals": {
                    "kms:EncryptionContext:PARAMETER_ARN":"arn:aws:ssm:us-west-2:111122223333:parameter/MyParameter"
                }
            }
        }
    ]
}

对 Parameter Store 中的 KMS 密钥问题进行故障排除

要对安全字符串参数执行任何操作，Parameter Store 必须能够使用您为预期操作指定的 Amazon KMS KMS 密钥。与 KMS 密钥相关的大多数 Parameter Store 故障都是由以下问题造成的：