保護標準安全字串參數保護進階安全字串參數設定許可來加密和解密參數值參數存放區加密內容參數存放區中的KMS金鑰問題疑難排解

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

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

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

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

重要

參數存放區僅支援對稱KMS索引鍵。您不能使用非對稱KMS金鑰來加密參數。如需協助判斷KMS金鑰是對稱或非對稱，請參閱識別不同的金鑰類型。

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

保護標準安全字串參數

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

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

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


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

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

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

下列範例使用中的 Systems Manager put-parameter 命令及其--type參數 AWS CLI 來建立安全字串參數。由於命令省略選用 --tier和 --key-id 參數，因此 Parameter Store 會建立標準安全字串參數，並在下加密 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 中的 GetParameter 操作API。

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


$  aws ssm get-parameter --name MyParameter

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

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


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

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

下列工作流程顯示 Parameter Store 如何使用KMS金鑰來加密和解密標準安全字串參數。

加密標準參數

當您使用 PutParameter 建立安全字串參數時，參數存放區會傳送 Encrypt 請求至 AWS KMS。該請求包含純文字參數值、您選擇的KMS金鑰，以及參數存放區加密內容。在傳輸到期間 AWS KMS，安全字串參數中的純文字值受到 Transport Layer Security （）的保護TLS。
AWS KMS 會使用指定的KMS金鑰和加密內容來加密參數值。它將加密文字傳回給參數存放區，以儲存參數名稱及其加密的值。

解密標準參數

當您在 GetParameter 請求中包含 WithDecryption 參數時，參數存放區會傳送 Decrypt 請求至 AWS KMS ，其中包含加密的安全字串參數值和參數存放區加密內容。
AWS KMS 使用相同的KMS金鑰和提供的加密內容來解密加密值。它將純文字 (解密的) 參數值傳回至參數存放區。在傳輸期間，純文字資料受到的保護TLS。
在 GetParameter 回應中，參數存放區會傳回純文字參數值給您。

保護進階安全字串參數

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

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

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

若要建立進階安全字串參數，請使用 Systems Manager 中的 PutParameter操作API。將 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

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

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


$  aws ssm get-parameter --name MyParameter

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


$  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 會將 AWS 受管金鑰用於帳戶。您可以指定主體有權使用的任何KMS金鑰，即使您使用不同的KMS金鑰來加密標準參數。

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


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

下列工作流程顯示 Parameter Store 如何使用KMS金鑰來加密和解密進階安全字串參數。

加密進階參數

當您使用 PutParameter建立進階安全字串參數時，Parameter Store 會使用 AWS Encryption SDK 和 AWS KMS 來加密參數值。參數存放區 AWS Encryption SDK 會使用參數值、您指定的KMS金鑰，以及參數存放區加密內容呼叫。
AWS Encryption SDK 會將GenerateDataKey請求傳送至 AWS KMS ，其中包含您指定KMS金鑰的識別碼，以及參數存放區加密內容。 AWS KMS 會傳回唯一資料金鑰的兩份副本：一份為純文字，一份為KMS金鑰下加密。(加密資料金鑰時會使用加密內容。)
AWS Encryption SDK 使用純文字資料金鑰來加密參數值。它會傳回加密的訊息，其中包含加密的參數值、加密的資料金鑰和其他資料 (包括參數存放區加密內容)。
參數存放區將加密的訊息存放為參數值。

解密進階參數

您可以在 GetParameter 請求中包含 WithDecryption 參數，以取得進階安全字串參數。當您這麼做時，參數存放區會從參數值中將加密的訊息傳遞到 AWS Encryption SDK的解密方法。
會 AWS Encryption SDK 呼叫 AWS KMS 解密操作。它從加密的訊息傳入加密的資料金鑰和參數存放區加密內容。
AWS KMS 使用 KMS金鑰和參數存放區加密內容來解密加密的資料金鑰。然後，它將純文字 (解密的) 資料金鑰傳回給 AWS Encryption SDK。
AWS Encryption SDK 使用純文字資料金鑰解密參數值。它將純文字參數值傳回至參數存放區。
參數存放區驗證加密內容，並在 GetParameter 回應中將純文字參數值傳回給您。

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

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

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

如果您使用客戶受管金鑰來加密安全字串參數值，則可以使用IAM政策和金鑰政策來管理加密和解密許可。不過，您無法為預設aws/ssmKMS金鑰建立存取控制政策。如需控制對客戶受管金鑰之存取權的詳細資訊，請參閱 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
值：正在加密之參數的 Amazon Resource Name （ARN）。

加密內容的格式如下：


"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"

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


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

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

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

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

在使用像這樣的政策陳述式之前，請將範例取代ARNs為有效值。


{
    "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金鑰相關的大多數參數存放區故障都是下列問題所造成：

應用程式正在使用的憑證沒有對KMS金鑰執行指定動作的許可。

若要修正此錯誤，請使用不同的登入資料執行應用程式，或修改阻止操作的 IAM或金鑰政策。如需 AWS KMS IAM和金鑰政策的協助，請參閱 KMS 金鑰存取和許可。
找不到 KMS金鑰。

當您使用不正確的 KMS 金鑰識別碼時，通常會發生這種情況。尋找索引鍵的正確識別碼，然後再次嘗試命令。 KMS
KMS 金鑰未啟用。發生這種情況時，Parameter Store 會傳回InvalidKeyId例外狀況，其中包含來自的詳細錯誤訊息 AWS KMS。如果KMS金鑰狀態為 Disabled，請啟用它。如果是 Pending Import，請完成匯入程序。如果金鑰狀態為 Pending Deletion，請取消金鑰刪除或使用不同的KMS金鑰。

若要尋找金鑰的KMS金鑰狀態，請使用 DescribeKey操作。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Amazon Redshift

參考資料