本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS KMSAWS Systems ManagerParameter Store SecureString 參數的加密

您可以使用 AWS Systems Manager Parameter Store建立 SecureString 參數，這些參數具有純文字參數名稱和加密參數值。 Parameter Store使用 AWS KMS 來加密和解密SecureString參數的參數值。

使用 Parameter Store 可以將資料當做具有值的參數來建立、存放和管理。您可以在 Parameter Store 中建立參數，並將它用在遵守您設計之政策和許可的多個應用程式和服務。需要變更參數值時，您只需變更一個執行個體，而不用管理容易出錯的多個來源變更。Parameter Store 支援層級結構的參數名稱，所以您可以限定參數用於特定用途。

若要管理敏感資料，您可以建立SecureString參數。 會在您建立或變更參數時 AWS KMS keys ，Parameter Store使用 來加密SecureString參數的參數值。當您存取這些參數時，它也使用 KMS 金鑰來解密參數值。使用 Parameter Store 為帳戶建立的 AWS 受管金鑰，或指定自己的客戶自管金鑰。

Parameter Store 支援兩種層級的SecureString參數：標準和進階。標準參數，不能超過 4096 個位元組，直接在您指定的 KMS 金鑰下加密和解密。為了加密和解密進階SecureString參數，Parameter Store 會使用信封加密搭配 AWS Encryption SDK。您可以將標準SecureString參數轉換成進階參數，但無法將進階參數轉換成標準參數。如需有關標準和進階 SecureString 參數之間差異的詳細資訊，請參閱管理參數層。

保護標準 SecureString 參數

Parameter Store 不會執行任何密碼編譯操作。而是倚賴 AWS KMS 來加密和解密SecureString參數值。當您建立或變更標準SecureString參數值時， 會Parameter Store呼叫 AWS KMS 加密操作。這個操作會直接使用對稱加密 KMS 金鑰來加密參數值，而不使用 KMS 金鑰產生資料金鑰。

您可以選擇 Parameter Store 用來加密參數值的 KMS 金鑰。如果未指定 KMS 金鑰，Parameter Store 會使用 Systems Manager 在帳戶中自動建立的 AWS 受管金鑰 。此 KMS 金鑰具有 aws/ssm 別名。

若要檢視您帳戶的預設 aws/ssm KMS 金鑰，請使用 AWS KMS API 中的 DescribeKey 操作。下列範例使用 AWS Command Line Interface (AWS CLI) 中的 aws/ssm describe-key命令搭配別名名稱。

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

若要建立標準 SecureString 參數，請使用 Systems Manager API 中的 PutParameter 操作。省略 Tier 參數，或指定值為 Standard (預設值)。加入值為 SecureString 的 Type 參數。若要指定 KMS 金鑰，請使用 KeyId 參數。預設為 AWS 受管金鑰 您帳戶的 aws/ssm。

Parameter Store 然後使用 KMS 金鑰和純文字參數值呼叫 AWS KMS Encrypt操作。 AWS KMS 會傳回以參數名稱Parameter Store存放的加密參數值。

下列範例使用 Systems Manager put-parameter 命令及其在 中的--type參數 AWS CLI 來建立SecureString參數。由於命令會省略選用 --tier 和 --key-id 參數，Parameter Store 會建立標準 SecureString 參數，並在 AWS 受管金鑰下加密此參數。

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

以下類似範例使用 --key-id 參數來指定客戶受管金鑰。此範例使用 KMS 金鑰 ID 來識別 KMS 金鑰，但您可以使用任何有效的 KMS 金鑰識別符。由於命令省略 Tier 參數 (--tier)，Parameter Store 會建立標準SecureString參數，而不是進階參數。

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

當您從 Parameter Store 取得SecureString參數時，它的值會加密。若要取得參數，請使用 Systems Manager API 中的 GetParameter 操作。

下列範例使用 中的 Systems Manager get-parameter 命令 AWS CLI ，從 取得 MyParameter 參數，Parameter Store而不解密其值。

aws ssm get-parameter --name MyParameter

{
    "Parameter": {
        "Type": "SecureString", 
        "Name": "MyParameter", 
        "Value": "AQECAHgnOkMROh5LaLXkA4j0+vYi6tmM17Lg"
    }
}

若要在傳回參數值之前先解密，請將 GetParameter 的 WithDecryption 參數設定為 true。當您使用 時WithDecryption， 會代表您Parameter Store呼叫 AWS KMS 解密操作來解密參數值。因此，GetParameter 請求會傳回具有純文字參數值的參數，如以下範例所示。

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

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

以下工作流程說明 Parameter Store 如何使用 KMS 金鑰來加密和解密標準 SecureString 參數。

加密標準參數

解密標準參數

保護進階 SecureString 參數

當您使用 PutParameter建立進階SecureString參數時， Parameter Store會使用信封加密搭配 AWS Encryption SDK 和對稱加密 AWS KMS key 來保護參數值。每個進階參數值都在唯一的資料金鑰下加密，而資料金鑰是在 KMS 金鑰下加密。您可以使用帳戶 (aws/ssm) 的 AWS 受管金鑰，或任何客戶受管金鑰。

AWS Encryption SDK 是開放原始碼的用戶端程式庫，可協助您使用產業標準和最佳實務來加密和解密資料。它支援多種平台和多種程式設計語言，包括命令列界面。您可以檢視原始程式碼，並在 GitHub 中對其開發做出貢獻。

對於每個SecureString參數值，Parameter Store 會呼叫 AWS Encryption SDK ，並使用 AWS KMS 產生的唯一資料金鑰 (GenerateDataKey) 來加密參數值。 AWS Encryption SDK 會傳回Parameter Store加密的訊息，其中包含加密的參數值和唯一資料金鑰的加密複本。 會將整個加密訊息Parameter Store存放在 SecureString 參數值中。然後，當您取得進階SecureString參數值時， Parameter Store會使用 AWS Encryption SDK 解密參數值。這需要呼叫 AWS KMS 來解密加密的資料金鑰。

若要建立進階 SecureString 參數，請使用 Systems Manager API 中的 PutParameter 操作。將 Tier 參數的值設為 Advanced。加入值為 SecureString 的 Type 參數。若要指定 KMS 金鑰，請使用 KeyId 參數。預設為 AWS 受管金鑰 您帳戶的 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-east-2:987654321098:key/1234abcd-12ab-34cd-56ef-1234567890ab

當您從 取得SecureString參數時Parameter Store，其值是 AWS 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"
    }
}

若要在傳回參數值之前先解密，請將 GetParameter 的 WithDecryption 參數設定為 true。當您使用 時WithDecryption， 會代表您Parameter Store呼叫 AWS KMS 解密操作，以解密 參數值。因此，GetParameter 請求會傳回具有純文字參數值的參數，如以下範例所示。

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

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

您無法將進階SecureString參數轉換成標準參數，但可以將標準SecureString轉換成進階參數。若要將標準SecureString參數轉換成進階SecureString，請使用 PutParameter 操作搭配 Overwrite 參數。Type 必須是 SecureString，Tier 值必須是 Advanced。識別客戶受管金鑰的 KeyId 參數是選用的。如果您省略它， Parameter Store會使用 AWS 受管金鑰 帳戶的 。即使您使用不同的 KMS 金鑰來加密標準參數，您也可以指定委託人有權使用的任何 KMS 金鑰。

當您使用 Overwrite 參數時，Parameter Store 會使用 AWS 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 金鑰來加密和解密進階 SecureString 參數。

加密進階參數

解密進階參數

設定許可來加密和解密參數值

若要加密標準SecureString參數值，使用者需要 kms:Encrypt 許可。若要加密進階SecureString參數值，使用者需要 kms:GenerateDataKey 許可。若要解密任一類型的SecureString參數值，使用者需要 kms:Decrypt 許可。

您可以使用 AWS Identity and Access Management (IAM) 政策來允許或拒絕使用者呼叫 Systems Manager PutParameter和 GetParameter 操作的許可。

如果使用客戶自管金鑰來加密 SecureString 參數值，則可以使用 IAM 政策和金鑰政策來管理加密和解密許可。不過，您無法為預設 aws/ssm KMS 金鑰建立存取控制政策。如需有關控制客戶自管金鑰存取的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 KMS key access and permissions。

以下範例顯示專為標準 SecureString 參數設計的 IAM 政策。它可讓使用者在 FinancialParameters 路徑中的所有參數上呼叫 Systems Manager PutParameter 操作。此政策也允許使用者在 AWS KMS Encrypt範例客戶受管金鑰上呼叫 操作。

{
    "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"
        }
    ]
}

以下範例顯示專為進階 SecureString 參數設計的 IAM 政策。它可讓使用者在 ReservedParameters 路徑中的所有參數上呼叫 Systems Manager PutParameter 操作。此政策也允許使用者在 AWS KMS GenerateDataKey範例客戶受管金鑰上呼叫 操作。

{
    "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"
        }
    ]
}

最後一個範例還顯示可用於標準或進階SecureString參數的 IAM 政策。它可讓使用者在 ITParameters 路徑中的所有參數上呼叫 Systems Manager GetParameter 操作 (以及相關操作)。此政策也允許使用者在 AWS KMS Decrypt範例客戶受管金鑰上呼叫 操作。

{
    "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 加密內容

加密內容是一組金鑰/值對，其中包含任意非私密資料。當您在加密資料的請求中包含加密內容時， AWS KMS 加密會以加密內容繫結至加密的資料。若要解密資料，您必須傳遞相同的加密內容。

您也可以使用加密內容來識別稽核記錄和日誌中的密碼編譯操作。加密內容會以純文字形式出現在日誌中，例如 AWS CloudTrail 日誌。

AWS Encryption SDK 也會採用加密內容，雖然處理方式不同。 會將加密內容Parameter Store提供給加密方法。 AWS Encryption SDK 密碼編譯會將加密內容繫結至加密的資料。它在傳回的已加密訊息的標頭中，還會包含純文字形式的加密內容。不過，與解密方法不同 AWS KMS， AWS Encryption SDK 解密方法不會將加密內容視為輸入。相反地，當 解密資料時， 會從加密的訊息 AWS Encryption SDK 取得加密內容。 Parameter Store 會驗證加密內容包含預期的值，然後再將純文字參數值傳回給您。

Parameter Store 在其密碼編譯操作中使用下列加密內容：

加密內容的格式如下：

"PARAMETER_ARN":"arn:aws:ssm:region-id:account-id:parameter/parameter-name"

例如， 會在呼叫中Parameter Store包含此加密內容，以加密和解密範例 AWS 帳戶 和區域中的 MyParameter 參數。

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

如果參數位於 Parameter Store 階層路徑，則路徑和名稱會包含在加密內容中。例如，在範例和區域中的/ReadableParameters路徑中加密 AWS 帳戶 和解密 MyParameter 參數時，會使用此加密內容。

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

您可以透過使用正確的加密內容和 Systems Manager 操作傳回的加密SecureString參數值呼叫 AWS KMS DecryptGetParameter操作，來解密加密的參數值。不過，我們建議您使用 GetParameter 操作搭配 WithDecryption 參數來解密 Parameter Store 參數值。

您也可以在 IAM 政策包含加密內容。例如，您可以允許使用者只解密一個特定的參數值或一組參數值。

以下範例 IAM 政策陳述式允許使用者取得 MyParameter 參數的值和使用指定的 KMS 金鑰來解密其值。不過，只有在加密內容符合指定的字串時，才會套用許可。這些許可不適用於任何其他參數或 KMS 金鑰，如果加密內容不符合字串，則呼叫 GetParameter 會失敗。

使用這類政策陳述式之前，請使用有效值取代範例 ARN。

{
    "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"
                }
            }
        }
    ]
}

對 Parameter Store 中的 KMS 金鑰問題進行疑難排解

若要對SecureString參數執行任何操作， Parameter Store 必須能夠使用您為預期操作指定的 AWS KMS KMS 金鑰。KMS 金鑰相關的大部分 Parameter Store 失敗是由下列問題引起：