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

AWS Systems Manager 參數存放區如何使用 AWS KMS

使用 AWS Systems Manager 參數存放區，您可以建立安全字串參數，這些參數具有純文字參數名稱和加密的參數值。參數存放區使用 AWS KMS 來加密和解密安全字串參數的參數值。

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

若要管理敏感資料，您可以建立安全字串參數。參數存放區使用 AWS KMS keys 在您建立或變更安全字串參數的參數值時對其進行加密。當您存取這些參數時，它也使用 KMS 金鑰來解密參數值。您可以使用參數存放區為您帳戶建立的 AWS 受管金鑰，或指定您自己的客戶受管金鑰。

參數存放區支援兩層級的安全字串參數：標準型和進階型。標準參數，不能超過 4096 個位元組，直接在您指定的 KMS 金鑰下加密和解密。為了加密和解密進階安全字串參數，參數存放區會使用信封加密搭配 AWS Encryption SDK。您可以將標準安全字串參數轉換成進階參數，但無法將進階參數轉換成標準參數。如需標準和進階安全字串參數之間差異的相關資訊，請參閱《AWS Systems Manager 使用者指南》中的關於 Systems Manager 進階參數。

保護標準安全字串參數

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

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

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

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

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

參數存放區接著會使用 KMS 金鑰和純文字參數值呼叫 AWS KMS Encrypt 操作。AWS KMS 會傳回參數存放區使用參數名稱存放的加密參數值。

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

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

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

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

當您從參數存放區取得安全字串參數時，它的值已經過加密。若要取得參數，請使用 Systems Manager API 中的GetParameter 作業。

下列範例會使用 AWS CLI 中的 Systems Manager get-parameter 命令，以取得參數存放區的 MyParameter 參數，無需解密其值。

$  aws ssm get-parameter --name MyParameter

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

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

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

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

以下工作流程說明參數存放區如何使用 KMS 金鑰來加密和解密標準安全字串參數。

加密標準參數

解密標準參數

保護進階安全字串參數

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

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

對於每個安全字串參數值，參數存放區呼叫AWS Encryption SDK以使用 AWS KMS generates (GenerateDataKey) 的唯一資料金鑰來加密參數值。AWS Encryption SDK 為參數存放區傳回已加密訊息，其中包含加密的參數值和唯一資料金鑰的已加密複本。參數存放區會將整個加密的訊息存放在安全字串參數值中。接著，當您取到進階安全字串參數值時，參數存放區會使用 AWS Encryption SDK 來解密參數值。這需要呼叫 AWS KMS 來解密加密的資料金鑰。

若要建立進階安全字串參數，請使用 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-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

當您從參數存放區取得安全字串參數時，它的值是 AWS Encryption SDK 傳回的加密訊息。若要取得參數，請使用 Systems Manager API 中的GetParameter 作業。

以下範例使用 Systems Manager GetParameter 操作從參數存放區取得 MyParameter 參數，無需解密其值。

$  aws ssm get-parameter --name MyParameter

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

若要在傳回參數值之前先解密，請將 GetParameter 的 WithDecryption 參數設定為 true。當您使用 WithDecryption 時，參數存放區會代您呼叫 AWS 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 參數是選用的。如果您將其省略，則參數存放區會將 AWS 受管金鑰 用於帳戶。即使您使用不同的 KMS 金鑰來加密標準參數，您也可以指定委託人有權使用的任何 KMS 金鑰。

當您使用 Overwrite 參數時，參數存放區會使用 AWS Encryption SDK 來加密參數值。然後，它會將新加密的訊息存放在參數存放區中。

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

以下工作流程說明參數存放區如何使用 KMS 金鑰來加密和解密進階安全字串參數。

加密進階參數

解密進階參數

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

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

您可以使用 IAM 政策來允許或拒絕使用者呼叫 Systems Manager PutParameter 和 GetParameter 操作的許可。

如果您使用客戶受管金鑰來加密安全字串參數值，您可以使用 IAM 政策和金鑰政策來管理加密和解密許可。不過，您無法為預設 aws/ssm KMS 金鑰建立存取控制政策。如需控制對客戶受管金鑰之存取權的詳細資訊，請參閱 驗證和存取控制 AWS KMS。

以下範例顯示專為標準安全字串參數設計的 IAM 政策。它可讓使用者在 FinancialParameters 路徑中的所有參數上呼叫 Systems Manager PutParameter 操作。此政策也可讓使用者在範例客戶受管金鑰上呼叫 AWS 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 政策。它可讓使用者在 ReservedParameters 路徑中的所有參數上呼叫 Systems Manager PutParameter 操作。此政策也可讓使用者在範例客戶受管金鑰上呼叫 AWS 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 政策。它可讓使用者在 ITParameters 路徑中的所有參數上呼叫 Systems Manager GetParameter 操作 (以及相關操作)。此政策也可讓使用者在範例客戶受管金鑰上呼叫 AWS 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"
        }
    ]
}

參數存放區加密內容

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

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

AWS Encryption SDK 也接受加密內容，但處理方式不同。參數存放區提供加密內容給加密方法。AWS Encryption SDK 以密碼編譯方式將加密內容繫結至加密的資料。它在傳回的已加密訊息的標頭中，還會包含純文字形式的加密內容。不過，與 AWS KMS 不同，AWS Encryption SDK 解密方法不接受加密內容做為輸入。相反地，當其解密資料時，AWS Encryption SDK 會從加密的訊息中取得加密內容。參數存放區驗證加密內容是否包含在為您傳回純文字參數值之前其所預期的值。

參數存放區在其密碼編譯操作中使用下列加密內容：

加密內容的格式如下：

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

例如，參數存放區在呼叫中包含此加密內容，用來加密和解密範例 AWS 帳戶 和區域中的 MyParameter 參數。

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

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

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

您可以透過使用正確的加密內容和 Systems Manager GetParameter 操作傳回的加密參數值來呼叫 AWS KMS Decrypt 操作，解密已加密的安全字串參數值。不過，我們建議您使用 GetParameter 操作搭配 WithDecryption 參數來解密參數存放區參數值。

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

以下範例 IAM 政策陳述式允許使用者取得 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"
                }
            }
        }
    ]
}

疑難排解參數存放區中的 KMS 金鑰問題

若要在安全字串參數上執行任何操作，參數存放區必須能夠使用您為預期操作指定的 AWS KMS KMS 金鑰。KMS 金鑰相關的大部分參數存放區故障是由下列問題引起：