使用 AWS CLI 的 AWS KMS 範例

下列程式碼範例示範如何使用 AWS Command Line Interface 搭配 AWS KMS 來執行動作，並實作常見案例。

Actions 是大型程式的程式碼摘錄，必須在內容中執行。雖然動作會告訴您如何呼叫個別服務函數，但您可以在其相關情境中查看內容中的動作。

每個範例均包含完整原始程式碼的連結，您可在連結中找到如何在內容中設定和執行程式碼的相關指示。

主題

動作

動作

以下程式碼範例顯示如何使用 cancel-key-deletion。

AWS CLI

取消客戶自管 KMS 金鑰的排程刪除

下列 cancel-key-deletion 範例會取消客戶自管 KMS 金鑰的排程刪除。


aws kms cancel-key-deletion \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

當 cancel-key-deletion 命令成功時，會取消排程的刪除。不過，KMS 金鑰的金鑰狀態為 Disabled，因此您無法在密碼編譯作業中使用 KMS 金鑰。若要還原其功能，請使用 enable-key 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的排程和取消金鑰刪除。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 CancelKeyDeletion。

以下程式碼範例顯示如何使用 connect-custom-key-store。

AWS CLI

連接自訂金鑰存放區

下列 connect-custom-key-store 範例會重新連接指定的自訂金鑰存放區。您可以使用像這樣的命令來第一次連接自訂金鑰存放區，或重新連接已中斷連接的金鑰存放區。

您可以使用此命令來連接 AWS CloudHSM 金鑰存放區或外部金鑰存放區。


aws kms connect-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

此命令不會傳回任何輸出。若要驗證命令是否有效，請使用 describe-custom-key-stores 命令。

如需有關連接 AWS CloudHSM 金鑰存放區的資訊，請參閱《AWS Key Management Service 開發人員指南》中的連接和中斷連接 AWS CloudHSM 金鑰存放區。

如需有關連接外部金鑰存放區的資訊，請參閱《AWS Key Management Service 開發人員指南》中的連接和中斷連接外部金鑰存放區。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ConnectCustomKeyStore。

以下程式碼範例顯示如何使用 create-alias。

AWS CLI

建立 KMS 金鑰的別名

下列 create-alias 命令會為金鑰 ID 1234abcd-12ab-34cd-56ef-1234567890ab 所識別的 KMS 金鑰建立一個名為 example-alias 的別名。

別名的開頭不可為 alias/。請勿使用以 alias/aws 開頭的別名；這些名稱會保留供 AWS 使用。


aws kms create-alias \
    --alias-name alias/example-alias \
    --target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab

此命令不會傳回任何輸出。若要查看新的別名，請使用 list-aliases 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的使用別名。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 CreateAlias。

以下程式碼範例顯示如何使用 create-custom-key-store。

AWS CLI

範例 1：建立 AWS CloudHSM 金鑰存放區

下列 create-custom-key-store 範例會使用所需的參數，建立 AWS CloudHSM 叢集所支援的 AWS CloudHSM 金鑰存放區。您也可以新增 custom-key-store-type``parameter with the default value: ``AWS_CLOUDHSM。

若要在 AWS CLI 中指定 trust-anchor-certificate 命令的檔案輸入，則需要 file:// 字首。


aws kms create-custom-key-store \
    --custom-key-store-name ExampleCloudHSMKeyStore \
    --cloud-hsm-cluster-id cluster-1a23b4cdefg \
    --key-store-password kmsPswd \
    --trust-anchor-certificate file://customerCA.crt

輸出：


{
    "CustomKeyStoreId": cks-1234567890abcdef0
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的建立 AWS CloudHSM 金鑰存放區。

範例 2：建立具有公有端點連線能力的外部金鑰存放區

下列 create-custom-key-store 範例會建立透過網際網路與 AWS KMS 通訊的外部金鑰存放區 (XKS)。

在此範例中，XksProxyUriPath 使用選用的字首 example-prefix。

注意：如果您使用 AWS CLI 1.0 版，則請先執行下列命令，然後再指定具有 HTTP 或 HTTPS 值的參數，例如 XksProxyUriEndpoint 參數。


aws configure set cli_follow_urlparam false

否則，AWS CLI 1.0 版會將參數值取代為在該 URI 位址找到的內容。


aws kms create-custom-key-store \
    --custom-key-store-name ExamplePublicEndpointXKS \
    --custom-key-store-type EXTERNAL_KEY_STORE \
    --xks-proxy-connectivity PUBLIC_ENDPOINT \
    --xks-proxy-uri-endpoint "https://myproxy.xks.example.com" \
    --xks-proxy-uri-path "/example-prefix/kms/xks/v1" \
    --xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="

輸出：


{
    "CustomKeyStoreId": cks-2234567890abcdef0
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的建立外部金鑰存放區。

範例 3：建立具有 VPC 端點服務連線能力的外部金鑰存放區

下列 create-custom-key-store 範例會建立外部金鑰存放區 (XKS)，其使用 Amazon VPC 端點服務與 AWS KMS 通訊。

注意：如果您使用 AWS CLI 1.0 版，則請先執行下列命令，然後再指定具有 HTTP 或 HTTPS 值的參數，例如 XksProxyUriEndpoint 參數。


aws configure set cli_follow_urlparam false

否則，AWS CLI 1.0 版會將參數值取代為在該 URI 位址找到的內容。


aws kms create-custom-key-store \
    --custom-key-store-name ExampleVPCEndpointXKS \
    --custom-key-store-type EXTERNAL_KEY_STORE \
    --xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
    --xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
    --xks-proxy-uri-path "/kms/xks/v1" \
    --xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example1" \
    --xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="

輸出：


{
    "CustomKeyStoreId": cks-3234567890abcdef0
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的建立外部金鑰存放區。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 CreateCustomKeyStore。

以下程式碼範例顯示如何使用 create-grant。

AWS CLI

建立授權

下列 create-grant 範例會建立授權，其允許 exampleUser 使用者在 1234abcd-12ab-34cd-56ef-1234567890ab 範例 KMS 金鑰上使用 decrypt 命令。淘汰主體是 adminRole 角色。授權使用 EncryptionContextSubset 授權限制條件，允許只在 decrypt 請求中的加密內容包含 "Department": "IT" 鍵值對時，才授予此權限。


aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::123456789012:user/exampleUser \
    --operations Decrypt \
    --constraints EncryptionContextSubset={Department=IT} \
    --retiring-principal arn:aws:iam::123456789012:role/adminRole

輸出：


{
    "GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
    "GrantToken": "<grant token here>"
}

若要檢視授權的詳細資訊，請使用 list-grants 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的在 AWS KMS 中授予。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 CreateGrant。

以下程式碼範例顯示如何使用 create-key。

AWS CLI

範例 1：在 AWS KMS 中建立客戶自管 KMS 金鑰

以下 create-key 範例會建立對稱加密 KMS 金鑰。

若要建立基本 KMS 金鑰 (對稱加密金鑰)，您不需要指定任何參數。這些參數的預設值會建立對稱加密金鑰。

由於此命令未指定金鑰政策，KMS 金鑰會取得適用於以程式設計方式建立之 KMS 金鑰的預設金鑰政策。若要檢視金鑰政策，請使用 get-key-policy 命令。若要變更金鑰政策，請使用 put-key-policy 命令。


aws kms create-key

create-key 命令會傳回金鑰中繼資料，包括新 KMS 金鑰的金鑰 ID 和 ARN。您可以使用這些值來識別其他 AWS KMS 操作中的 KMS 金鑰。輸出不包含標籤。若要檢視 KMS 金鑰的標籤，請使用 list-resource-tags command。

輸出：


{
    "KeyMetadata": {
        "AWSAccountId": "111122223333",
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "CreationDate": "2017-07-05T14:04:55-07:00",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "AWS_KMS"
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    }
}

注意：create-key 命令不允許您指定別名。若要為新的 KMS 金鑰建立別名，請使用 create-alias 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的建立金鑰。

範例 2：建立用於加密和解密的非對稱 RSA KMS 金鑰

下列 create-key 範例會建立 KMS 金鑰，其中包含用於加密和解密的非對稱 RSA 金鑰對。建立金鑰之後，就無法變更金鑰規格和金鑰用量：


aws kms create-key \
   --key-spec RSA_4096 \
   --key-usage ENCRYPT_DECRYPT

輸出：


{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2021-04-05T14:04:55-07:00",
        "CustomerMasterKeySpec": "RSA_4096",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
            "RSAES_OAEP_SHA_1",
            "RSAES_OAEP_SHA_256"
        ],
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "RSA_4096",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "AWS_KMS"
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

範例 3：建立用於簽署和驗證的非對稱橢圓曲線 KMS 金鑰

建立非對稱 KMS 金鑰，其中包含用於簽署和驗證的非對稱橢圓曲線 (ECC) 金鑰對。即使 SIGN_VERIFY 是 ECC KMS 金鑰的唯一有效值，仍需要 --key-usage 參數。建立金鑰之後，就無法變更金鑰規格和金鑰用量：


aws kms create-key \
    --key-spec ECC_NIST_P521 \
    --key-usage SIGN_VERIFY

輸出：


{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2019-12-02T07:48:55-07:00",
        "CustomerMasterKeySpec": "ECC_NIST_P521",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "ECC_NIST_P521",
        "KeyState": "Enabled",
        "KeyUsage": "SIGN_VERIFY",
        "MultiRegion": false,
        "Origin": "AWS_KMS",
        "SigningAlgorithms": [
            "ECDSA_SHA_512"
        ]
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

範例 4：建立用於簽署和驗證的非對稱 ML-DSA KMS 金鑰

此範例會建立用於簽署和驗證的模組格線數位簽章演算法 (ML-DSA) 金鑰。即使 SIGN_VERIFY 是 ML-DSA 金鑰的唯一有效值，仍需要 key-usage 參數。


aws kms create-key \
    --key-spec ML_DSA_65 \
    --key-usage SIGN_VERIFY

輸出：


{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2019-12-02T07:48:55-07:00",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "ML_DSA_65",
        "KeyState": "Enabled",
        "KeyUsage": "SIGN_VERIFY",
        "MultiRegion": false,
        "Origin": "AWS_KMS",
        "SigningAlgorithms": [
            "ML_DSA_SHAKE_256"
        ]
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

範例 5：建立 HMAC KMS 金鑰

以下 create-key 範例會建立 384 位元 HMAC KMS 金鑰。--key-usage 參數的 GENERATE_VERIFY_MAC 值是必要的，即使它是 HMAC KMS 金鑰的唯一有效值。


aws kms create-key \
    --key-spec HMAC_384 \
    --key-usage GENERATE_VERIFY_MAC

輸出：


{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2022-04-05T14:04:55-07:00",
        "CustomerMasterKeySpec": "HMAC_384",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "HMAC_384",
        "KeyState": "Enabled",
        "KeyUsage": "GENERATE_VERIFY_MAC",
        "MacAlgorithms": [
            "HMAC_SHA_384"
        ],
        "MultiRegion": false,
        "Origin": "AWS_KMS"
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的 HMAC 金鑰。

範例 6：建立多區域主要 KMS 金鑰

以下 create-key 範例會建立多區域主要對稱加密金鑰。由於所有參數的預設值都會建立對稱加密金鑰，此 KMS 金鑰只需要 --multi-region 參數。在 AWS CLI 中，若要指出布林值參數為 true，則只需指定參數名稱即可。


aws kms create-key \
    --multi-region

輸出：


{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2021-09-02T016:15:21-09:00",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
          "SYMMETRIC_DEFAULT"
        ],
        "KeyId": "mrk-1234abcd12ab34cd56ef12345678990ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": true,
        "MultiRegionConfiguration": {
            "MultiRegionKeyType": "PRIMARY",
            "PrimaryKey": {
                "Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
                "Region": "us-west-2"
            },
            "ReplicaKeys": []
        },
        "Origin": "AWS_KMS"
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

範例 7：為匯入的金鑰材料建立 KMS 金鑰

下列 create-key 範例會建立不含金鑰材料的 KMS 金鑰。完成操作後，您可以將自己的金鑰材料匯入 KMS 金鑰。若要建立此 KMS 金鑰，請將 --origin 參數設定為 EXTERNAL。


aws kms create-key \
    --origin EXTERNAL

輸出：


{
     "KeyMetadata": {
         "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
         "AWSAccountId": "111122223333",
         "CreationDate": "2019-12-02T07:48:55-07:00",
         "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
         "Description": "",
         "Enabled": false,
         "EncryptionAlgorithms": [
             "SYMMETRIC_DEFAULT"
         ],
         "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
         "KeyManager": "CUSTOMER",
         "KeySpec": "SYMMETRIC_DEFAULT",
         "KeyState": "PendingImport",
         "KeyUsage": "ENCRYPT_DECRYPT",
         "MultiRegion": false,
         "Origin": "EXTERNAL"
     }
 }

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的在 AWS KMS 中匯入金鑰材料。

範例 6：在 AWS CloudHSM 金鑰存放區中建立 KMS 金鑰

下列 create-key 範例會在指定的 AWS CloudHSM 金鑰存放區中建立 KMS 金鑰。該作業會在 AWS KMS 中建立 KMS 金鑰及其中繼資料，並在與自訂金鑰存放區相關聯的 AWS CloudHSM 叢集中建立金鑰材料。--custom-key-store-id 和 --origin 是必要參數。


aws kms create-key \
    --origin AWS_CLOUDHSM \
    --custom-key-store-id cks-1234567890abcdef0

輸出：


{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CloudHsmClusterId": "cluster-1a23b4cdefg",
        "CreationDate": "2019-12-02T07:48:55-07:00",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "CustomKeyStoreId": "cks-1234567890abcdef0",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "AWS_CLOUDHSM"
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS CloudHSM 金鑰存放區。

範例 8：在外部金鑰存放區中建立 KMS 金鑰

下列 create-key 範例會在指定的外部金鑰存放區中建立 KMS 金鑰。此命令需要用到 --custom-key-store-id、--origin 和 --xks-key-id 參數。

--xks-key-id 參數會在外部金鑰管理員中，指定現有對稱加密金鑰的 ID。此金鑰用作 KMS 金鑰的外部金鑰材料。--origin 參數的值必須是 EXTERNAL_KEY_STORE。custom-key-store-id 參數必須識別連接到其外部金鑰存放區代理的外部金鑰存放區。


aws kms create-key \
    --origin EXTERNAL_KEY_STORE \
    --custom-key-store-id cks-9876543210fedcba9 \
    --xks-key-id bb8562717f809024

輸出：


{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2022-12-02T07:48:55-07:00",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "CustomKeyStoreId": "cks-9876543210fedcba9",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "EXTERNAL_KEY_STORE",
        "XksKeyConfiguration": {
            "Id": "bb8562717f809024"
        }
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的外部金鑰存放區。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 CreateKey。

以下程式碼範例顯示如何使用 decrypt。

AWS CLI

範例 1：使用對稱 KMS 金鑰 (Linux 和 macOS) 將加密的訊息解密

下列 decrypt 命令範例展示使用 AWS CLI 解密資料的建議方法。此版本示範如何在對稱 KMS 金鑰下解密資料。

在檔案中提供密文。--ciphertext-blob 參數的值中，使用 fileb:// 字首，其會告知 CLI 從二進位檔案讀取資料。如果檔案不在目前的目錄中，請輸入檔案的完整路徑。如需有關從檔案讀取 AWS CLI 參數值的詳細資訊，請參閱《AWS Command Line Interface 使用者指南》中的「從檔案<https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html>載入 AWS CLI 參數」，以及《AWS 命令列工具部落格》中的「本機檔案參數最佳實務<https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/>」。指定 KMS 金鑰以解密加密文字。使用對稱 KMS 金鑰解密時，不需要 --key-id 參數。AWSKMS 可以取得 KMS 金鑰的金鑰 ID，其曾經用於為加密文字中的中繼資料加密。但是指定您正在使用的 KMS 金鑰永遠是最佳實務。此實務可確保您使用想要的 KMS 金鑰，並防止不小心使用您不信任的 KMS 金鑰來解密加密文字。請求純文字輸出作為文字值。--query 參數會告知 CLI 僅從輸出取得 Plaintext 欄位的值。--output 參數會以純文字傳回輸出。Base64 將純文字解碼，並儲存在檔案中。下列範例會將 Plaintext 參數的管道符號 (|) 值輸送至 Base64 公用程式，以將其解碼。然後，將解碼的輸出重新導向 (>) 至 ExamplePlaintext 檔案。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。


aws kms decrypt \
    --ciphertext-blob fileb://ExampleEncryptedFile \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --output text \
    --query Plaintext | base64 \
    --decode > ExamplePlaintextFile

此命令不會產生輸出。來自 decrypt 命令的輸出經過 base64 解碼，並儲存在檔案中。

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的解密。

範例 2：使用對稱 KMS 金鑰解密加密的訊息 (Windows 命令提示)

下列範例與上一個範例相同，唯一不同的是其使用 certutil 公用程式對純文字資料進行 Base64 解碼。如下列範例所示，此程序需要兩個命令。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。


aws kms decrypt ^
    --ciphertext-blob fileb://ExampleEncryptedFile ^
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
    --output text ^
    --query Plaintext > ExamplePlaintextFile.base64

執行 certutil 命令。


certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile

輸出：


Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的解密。

範例 3：使用非對稱 KMS 金鑰 (Linux 和 macOS) 解密加密的訊息

下列 decrypt 命令範例示範如何將以 RSA 非對稱 KMS 金鑰加密的資料解密。

使用非對稱 KMS 金鑰時，需要指定用於加密純文字的演算法的 encryption-algorithm 參數。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。


aws kms decrypt \
    --ciphertext-blob fileb://ExampleEncryptedFile \
    --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --encryption-algorithm RSAES_OAEP_SHA_256 \
    --output text \
    --query Plaintext | base64 \
    --decode > ExamplePlaintextFile

此命令不會產生輸出。來自 decrypt 命令的輸出經過 base64 解碼，並儲存在檔案中。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 Decrypt。

以下程式碼範例顯示如何使用 delete-alias。

AWS CLI

刪除 AWS KMS 別名

以下 delete-alias 範例會刪除別名 alias/example-alias。別名名稱必須以別名/ 開頭。


aws kms delete-alias \
    --alias-name alias/example-alias

此命令不會產生輸出。要尋找別名，請使用 list-aliases 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的刪除別名。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DeleteAlias。

以下程式碼範例顯示如何使用 delete-custom-key-store。

AWS CLI

刪除自訂金鑰存放區

下列 delete-custom-key-store 範例會刪除指定的自訂金鑰存放區。

刪除 AWS CloudHSM 金鑰存放區不會影響相關聯的 CloudHSM 叢集。刪除外部金鑰存放區不會影響相關聯的外部金鑰存放區代理、外部金鑰管理員或外部金鑰。

注意：您必須先排程刪除自訂金鑰存放區中的所有 KMS 金鑰，然後等待刪除這些 KMS 金鑰後，才能刪除自訂金鑰存放區。然後，您必須中斷連接自訂金鑰存放區。如需有關在您的自訂金鑰存放區中尋找 KMS 金鑰的說明，請參閱《AWS Key Management Service 開發人員指南》中的刪除 AWS CloudHSM 金鑰存放區 (API)。


delete-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

此命令不會傳回任何輸出。若要確認自訂金鑰存放區是否已刪除，請使用 describe-custom-key-stores 命令。

如需有關刪除 AWS CloudHSM 金鑰存放區的資訊，請參閱《AWS Key Management Service 開發人員指南》中的刪除 AWS CloudHSM 金鑰存放區。

如需有關刪除外部金鑰存放區的資訊，請參閱《AWSKey Management Service 開發人員指南》中的刪除外部金鑰存放區。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DeleteCustomKeyStore。

以下程式碼範例顯示如何使用 delete-imported-key-material。

AWS CLI

從 KMS 金鑰刪除匯入的金鑰材料

下列 delete-imported-key-material 範例會刪除已匯入 KMS 金鑰的金鑰材料。


aws kms delete-imported-key-material \
   --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的刪除匯入的金鑰材料。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DeleteImportedKeyMaterial。

以下程式碼範例顯示如何使用 derive-shared-secret。

AWS CLI

衍生共享秘密

下列 derive-shared-secret 範例使用金鑰協議演算法衍生共享秘密。

您必須使用 NIST 建議的非對稱橢圓曲線 (ECC) 或 SM2 (僅限中國地區) KMS 金鑰對 (KeyUsage 值為 KEY_AGREEMENT) 來呼叫 DeriveSharedSecret。


aws kms derive-shared-secret \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --key-agreement-algorithm ECDH \
    --public-key "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvH3Yj0wbkLEpUl95Cv1cJVjsVNSjwGq3tCLnzXfhVwVvmzGN8pYj3U8nKwgouaHbBWNJYjP5VutbbkKS4Kv4GojwZBJyHN17kmxo8yTjRmjR15SKIQ8cqRA2uaERMLnpztIXdZp232PQPbWGxDyXYJ0aJ5EFSag"

輸出：


{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "SharedSecret": "MEYCIQCKZLWyTk5runarx6XiAkU9gv3lbwPO/pHa+DXFehzdDwIhANwpsIV2g/9SPWLLsF6p/hiSskuIXMTRwqrMdVKWTMHG",
    "KeyAgreementAlgorithm": "ECDH",
    "KeyOrigin": "AWS_KMS"
}

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的 DeriveSharedSecret。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DeriveSharedSecret。

以下程式碼範例顯示如何使用 describe-custom-key-stores。

AWS CLI

範例 1：取得 AWS CloudHSM 金鑰存放區的詳細資訊

下列 describe-custom-key-store 範例顯示指定的 AWS CloudHSM 金鑰存放區的詳細資訊。命令對於所有類型的自訂金鑰存放區都是一樣的，但輸出會因金鑰存放區類型而有所不同，對於外部金鑰存放區，其連線選項也不同。

根據預設，此命令會顯示帳戶和區域中所有自訂金鑰存放區的相關資訊。若要顯示特定自訂金鑰存放區的相關資訊，請使用 custom-key-store-name 或 custom-key-store-id 參數。


aws kms describe-custom-key-stores \
    --custom-key-store-name ExampleCloudHSMKeyStore

此命令的輸出包含 AWS CloudHSM 金鑰存放區的實用詳細資訊，包括其連線狀態 (ConnectionState)。如果連線狀態為 FAILED，則輸出會包含描述問題的 ConnectionErrorCode 欄位。

輸出：


{
    "CustomKeyStores": [
        {
            "CloudHsmClusterId": "cluster-1a23b4cdefg",
            "ConnectionState": "CONNECTED",
            "CreationDate": "2022-04-05T14:04:55-07:00",
            "CustomKeyStoreId": "cks-1234567890abcdef0",
            "CustomKeyStoreName": "ExampleExternalKeyStore",
            "TrustAnchorCertificate": "<certificate appears here>"
        }
    ]
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的檢視 AWS CloudHSM 金鑰存放區。

範例 2：取得具有公有端點連線能力的外部金鑰存放區詳細資訊

下列 describe-custom-key-store 範例顯示指定外部金鑰存放區的詳細資訊。命令對於所有類型的自訂金鑰存放區都是一樣的，但輸出會因金鑰存放區類型而有所不同，對於外部金鑰存放區，其連線選項也不同。


aws kms describe-custom-key-stores \
    --custom-key-store-id cks-9876543210fedcba9

此命令的輸出涵蓋外部金鑰存放區的實用詳細資訊，包括其連線狀態 (ConnectionState)。如果連線狀態為 FAILED，則輸出會包含描述問題的 ConnectionErrorCode 欄位。

輸出：


{
    "CustomKeyStores": [
        {
            "CustomKeyStoreId": "cks-9876543210fedcba9",
            "CustomKeyStoreName": "ExampleXKS",
            "ConnectionState": "CONNECTED",
            "CreationDate": "2022-12-02T07:48:55-07:00",
            "CustomKeyStoreType": "EXTERNAL_KEY_STORE",
            "XksProxyConfiguration": {
                "AccessKeyId": "ABCDE12345670EXAMPLE",
                "Connectivity": "PUBLIC_ENDPOINT",
                "UriEndpoint": "https://myproxy.xks.example.com",
                "UriPath": "/example-prefix/kms/xks/v1"
            }
        }
    ]
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的檢視外部金鑰存放區。

範例 3：取得具有 VPC 端點服務連線能力的外部金鑰存放區詳細資訊


aws kms describe-custom-key-stores \
    --custom-key-store-id cks-2234567890abcdef0

輸出：


{
    "CustomKeyStores": [
        {
            "CustomKeyStoreId": "cks-3234567890abcdef0",
            "CustomKeyStoreName": "ExampleVPCExternalKeyStore",
            "ConnectionState": "CONNECTED",
            "CreationDate": "2022-12-22T07:48:55-07:00",
            "CustomKeyStoreType": "EXTERNAL_KEY_STORE",
            "XksProxyConfiguration": {
                "AccessKeyId": "ABCDE12345670EXAMPLE",
                "Connectivity": "VPC_ENDPOINT_SERVICE",
                "UriEndpoint": "https://myproxy-private.xks.example.com",
                "UriPath": "/kms/xks/v1",
                "VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example1"
            }
        }
    ]
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的檢視外部金鑰存放區。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DescribeCustomKeyStores。

以下程式碼範例顯示如何使用 describe-key。

AWS CLI

範例 1：尋找 KMS 金鑰的詳細資訊

下列 describe-key 範例取得範例帳戶和區域中 Amazon S3 AWS 受管金鑰的詳細資訊。您可以使用此命令尋找 AWS 受管金鑰和客戶自管金鑰的詳細資訊。

若要指定 KMS 金鑰，請使用 key-id 參數。此範例使用別名的名稱值，但您可以在此命令中使用金鑰 ID、金鑰 ARN、別名的名稱或別名 ARN。


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

輸出：


{
    "KeyMetadata": {
        "AWSAccountId": "846764612917",
        "KeyId": "b8a9477d-836c-491f-857e-07937918959b",
        "Arn": "arn:aws:kms:us-west-2:846764612917:key/b8a9477d-836c-491f-857e-07937918959b",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "CreationDate": 2017-06-30T21:44:32.140000+00:00,
        "Enabled": true,
        "Description": "Default KMS key that protects my S3 objects when no other key is defined",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "AWS",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    }
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的檢視金鑰。

範例 2：取得 RSA 非對稱 KMS 金鑰的詳細資訊

下列 describe-key 範例會取得用於簽署和驗證的非對稱 RSA KMS 金鑰的詳細資訊。


aws kms describe-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "KeyMetadata": {
        "AWSAccountId": "111122223333",
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "CreationDate": "2019-12-02T19:47:14.861000+00:00",
        "CustomerMasterKeySpec": "RSA_2048",
        "Enabled": false,
        "Description": "",
        "KeyState": "Disabled",
        "Origin": "AWS_KMS",
        "MultiRegion": false,
        "KeyManager": "CUSTOMER",
        "KeySpec": "RSA_2048",
        "KeyUsage": "SIGN_VERIFY",
        "SigningAlgorithms": [
            "RSASSA_PKCS1_V1_5_SHA_256",
            "RSASSA_PKCS1_V1_5_SHA_384",
            "RSASSA_PKCS1_V1_5_SHA_512",
            "RSASSA_PSS_SHA_256",
            "RSASSA_PSS_SHA_384",
            "RSASSA_PSS_SHA_512"
        ]
    }
}

範例 3：取得多區域複本金鑰的詳細資訊

下列 describe-key 範例會取得多區域複本金鑰的中繼資料。此多區域金鑰是對稱加密金鑰。任何多區域金鑰的 describe-key 命令輸出，都會傳回主金鑰及其所有複本的相關資訊。


aws kms describe-key \
    --key-id arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

輸出：


{
    "KeyMetadata": {
        "MultiRegion": true,
        "AWSAccountId": "111122223333",
        "Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
        "CreationDate": "2021-06-28T21:09:16.114000+00:00",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "Description": "",
        "Enabled": true,
        "KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "Origin": "AWS_KMS",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "MultiRegionConfiguration": {
            "MultiRegionKeyType": "PRIMARY",
            "PrimaryKey": {
                "Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                "Region": "us-west-2"
            },
            "ReplicaKeys": [
                {
                    "Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "eu-west-1"
                },
                {
                    "Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "ap-northeast-1"
                },
                {
                    "Arn": "arn:aws:kms:sa-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "sa-east-1"
                }
            ]
        }
    }
}

範例 4：取得 HMAC KMS 金鑰的詳細資訊

下列 describe-key 範例會取得 HMAC KMS 金鑰的詳細資訊。


aws kms describe-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "KeyMetadata": {
        "AWSAccountId": "123456789012",
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "CreationDate": "2022-04-03T22:23:10.194000+00:00",
        "Enabled": true,
        "Description": "Test key",
        "KeyUsage": "GENERATE_VERIFY_MAC",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "CUSTOMER",
        "CustomerMasterKeySpec": "HMAC_256",
        "MacAlgorithms": [
            "HMAC_SHA_256"
        ],
        "MultiRegion": false
    }
}

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DescribeKey。

以下程式碼範例顯示如何使用 disable-key-rotation。

AWS CLI

停用 KMS 金鑰的自動輪換

下列 disable-key-rotation 範例會停用客戶自管 KMS 金鑰的自動輪換。若要重新啟用自動輪換，請使用 enable-key-rotation 命令。


aws kms disable-key-rotation \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

此命令不會產生輸出。若要確認 KMS 金鑰的自動輪換已停用，請使用 get-key-rotation-status 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的輪換金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DisableKeyRotation。

以下程式碼範例顯示如何使用 disable-key。

AWS CLI

暫時停用 KMS 金鑰

下列 disable-key 命令會停用客戶自管 KMS 金鑰。若要重新啟用 KMS 金鑰，請使用 enable-key 命令。


aws kms disable-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

此命令不會產生輸出。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的啟用和停用金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DisableKey。

以下程式碼範例顯示如何使用 disconnect-custom-key-store。

AWS CLI

中斷連線自訂金鑰存放區

下列 disconnect-custom-key-store 範例會使自訂金鑰存放區與其 AWS CloudHSM 叢集中斷連線。您可以中斷連接金鑰存放區，以對問題進行故障診斷、更新其設定，或防止金鑰存放區中的 KMS 金鑰用於密碼編譯操作。

此命令對所有自訂金鑰存放區都相同，包括 AWS CloudHSM 金鑰存放區和外部金鑰存放區。

執行此命令之前，請將範例自訂金鑰存放區 ID 以有效的 ID 取代。


$ aws kms disconnect-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

此命令不會產生任何輸出。請確認命令是否有效，使用 describe-custom-key-stores 命令。

如需有關中斷連接 AWS CloudHSM 金鑰存放區的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的連接和中斷連接 AWS CloudHSM 金鑰存放區。

如需有關中斷連接外部金鑰存放區的資訊，請參閱《AWS Key Management Service 開發人員指南》中的連接和中斷連接外部金鑰存放區。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 DisconnectCustomKeyStore。

以下程式碼範例顯示如何使用 enable-key-rotation。

AWS CLI

啟用 KMS 金鑰的自動輪換

下列 enable-key-rotation 範例會啟用客戶自管 KMS 金鑰的自動輪換，輪換期間為 180 天。KMS 金鑰將從此命令完成之日起一年 (大約 365 天) 輪換，之後每年輪換一次。

--key-id 參數可識別 KMS 金鑰。此範例使用金鑰 ARN 值，但您可以使用金鑰 ID 或 KMS 金鑰的 ARN。--rotation-period-in-days 參數會指定每個輪換日期之間的天數。指定介於 90 到 2560 之間的值。如未指定任何值，則預設值為 365 天。


aws kms enable-key-rotation \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --rotation-period-in-days 180

此命令不會產生輸出。若要確認 KMS 金鑰已啟用，請使用 get-key-rotation-status 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的輪換金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 EnableKeyRotation。

以下程式碼範例顯示如何使用 enable-key。

AWS CLI

啟用 KMS 金鑰

下列 enable-key 範例會啟用客戶自管金鑰。您可以使用像這樣的命令，來啟用使用 disable-key 命令暫時停用的 KMS 金鑰。您也可以使用它來啟用已停用的 KMS 金鑰，因為其已排定刪除的時程，且已取消刪除。

若要指定 KMS 金鑰，請使用 key-id 參數。此範例使用金鑰 ID 值，但您可以在此命令中使用金鑰 ID 或金鑰 ARN 值。

執行此命令之前，請將範例金鑰 ID 取代為有效的代碼。


aws kms enable-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

此命令不會產生輸出。若要確認 KMS 金鑰已啟用，請使用 describe-key 命令。查看 describe-key 輸出中 KeyState 和 Enabled 欄位的值。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的啟用和停用金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 EnableKey。

以下程式碼範例顯示如何使用 encrypt。

AWS CLI

範例 1：在 Linux 或 MacOS 上加密檔案的內容

下列 encrypt 命令展示使用 AWS CLI 加密資料的建議方式。


aws kms encrypt \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --plaintext fileb://ExamplePlaintextFile \
    --output text \
    --query CiphertextBlob | base64 \
    --decode > ExampleEncryptedFile

命令會執行數個動作：

使用 --plaintext 參數來指示要加密的資料。此參數值必須是 base64 編碼。plaintext 參數的值必須是 base64 編碼，或者您必須使用 fileb:// 字首，指示 AWS CLI 從檔案讀取二進位資料。如果檔案不在目前的目錄中，請輸入檔案的完整路徑。例如：fileb:///var/tmp/ExamplePlaintextFile 或 fileb://C:\Temp\ExamplePlaintextFile。如需從檔案讀取 AWS CLI 參數值的詳細資訊，請參閱《AWS 命令列介面使用者指南》中的從檔案載入參數，以及 AWS 命令列工具部落格上的本機檔案參數的最佳實務。使用 --output 和 --query 參數來控制命令的輸出。這些參數會從命令的輸出擷取加密的資料，稱為加密文字。如需控制輸出的詳細資訊，請參閱《AWS 命令列介面使用者指南》中的控制命令輸出。使用 base64 公用程式將擷取的輸出解碼為二進位資料。成功的 encrypt 命令傳回的加密文字是 base64 編碼的文字。您必須先解碼此文字，才能使用 AWS CLI 將其解密。將二進位加密文字儲存到檔案。命令 (> ExampleEncryptedFile) 的最終部分會將二進位加密文字儲存到檔案，讓解密更容易。如需使用 AWS CLI 解密資料的範例命令，請參閱解密範例。

範例 2：使用 AWS CLI 加密 Windows 上的資料

此範例與上一個範例相同，但其使用的是 certutil 工具 (而非 base64)。此程序需要兩個命令，如下列範例所示。


aws kms encrypt \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --plaintext fileb://ExamplePlaintextFile \
    --output text \
    --query CiphertextBlob > C:\Temp\ExampleEncryptedFile.base64

certutil -decode C:\Temp\ExampleEncryptedFile.base64 C:\Temp\ExampleEncryptedFile

範例 3：使用非對稱 KMS 金鑰加密

下列 encrypt 命令顯示如何使用非對稱 KMS 金鑰加密純文字。--encryption-algorithm 參數是必要參數。如同所有 encrypt CLI 命令，plaintext 參數必須是 base64 編碼，或者您必須使用 fileb:// 字首，告知 AWS CLI 從檔案讀取二進位資料。


aws kms encrypt \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --encryption-algorithm RSAES_OAEP_SHA_256 \
    --plaintext fileb://ExamplePlaintextFile \
    --output text \
    --query CiphertextBlob | base64 \
    --decode > ExampleEncryptedFile

此命令不會產生輸出。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 Encrypt。

以下程式碼範例顯示如何使用 generate-data-key-pair-without-plaintext。

AWS CLI

產生 ECC NIST P384 非對稱資料金鑰對

下列 generate-data-key-pair-without-plaintext 範例會請求在 AWS 外部使用的 ECC NIST P384 金鑰對。

命令會傳回純文字公有金鑰，和以指定之 KMS 金鑰加密的私有金鑰複本。命令不會傳回純文字私有金鑰。您可以安全地將加密的私有金鑰與加密的資料一起存放，並在您需要使用私有金鑰時呼叫 AWS KMS，以解密私有金鑰。

若要請求 ECC NIST P384 非對稱資料金鑰對，請使用值為 ECC_NIST_P384 的 key-pair-spec 參數。

您指定的 KMS 金鑰必須是對稱加密 KMS 金鑰，也就是 KeySpec 值為 SYMMETRIC_DEFAULT 的 KMS 金鑰。

注意：此範例輸出中的值會截斷以方便顯示。


aws kms generate-data-key-pair-without-plaintext \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --key-pair-spec ECC_NIST_P384

輸出：


{
    "PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
    "PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
    "KeyPairSpec": "ECC_NIST_P384"
}

PublicKey 和 PrivateKeyCiphertextBlob 會以 base64 編碼格式傳回。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的資料金鑰對。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GenerateDataKeyPairWithoutPlaintext。

以下程式碼範例顯示如何使用 generate-data-key-pair。

AWS CLI

產生 2048 位元 RSA 非對稱資料金鑰對

下列 generate-data-key-pair 範例會請求在 AWS 外部使用的 2048 位元 RSA 非對稱資料金鑰對。命令會傳回純文字公有金鑰和純文字私有金鑰，以供立即使用和刪除，以及使用指定的 KMS 金鑰加密的私有金鑰複本。加密的私有金鑰可以安全地跟加密資料一起存放。

若要請求 2048 位元 RSA 非對稱資料金鑰對，請使用值為 RSA_2048 的 key-pair-spec 參數。

您指定的 KMS 金鑰必須是對稱加密 KMS 金鑰，也就是 KeySpec 值為 SYMMETRIC_DEFAULT 的 KMS 金鑰。

注意：此範例輸出中的值會截斷以方便顯示。


aws kms generate-data-key-pair \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --key-pair-spec RSA_2048

輸出：


{
    "PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
    "PrivateKeyPlaintext": "MIIG/QIBADANBgkqhkiG9w0BAQEFAASCBucwggbjAgEAAoIBgQDcDd4YzI+u9Kfv4t2UkTWhShBXkekS4cBVt07I0P42ZgMf+YvU5IgS4ut...",
    "PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
    "KeyPairSpec": "RSA_2048"
}

PublicKey、PrivateKeyPlaintext 和 PrivateKeyCiphertextBlob 會以 base64 編碼格式傳回。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的資料金鑰對。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GenerateDataKeyPair。

以下程式碼範例顯示如何使用 generate-data-key-without-plaintext。

AWS CLI

產生不含純文字金鑰的 256 位元對稱資料金鑰

下列 generate-data-key-without-plaintext 範例會請求 256 位元對稱資料金鑰的加密複本，以供在 AWS 之外使用。當您準備好要使用資料金鑰時，您可以呼叫 AWS KMS 來解密資料金鑰。

若要請求 256 位元資料金鑰，請使用值為 AES_256 的 key-spec 參數。若要請求 128 位元資料金鑰，請使用值為 AES_128 的 key-spec 參數。對於所有其他資料金鑰長度，請使用 number-of-bytes 參數。

您指定的 KMS 金鑰必須是對稱加密 KMS 金鑰，也就是 KeySpec 值為 SYMMETRIC_DEFAULT 的 KMS 金鑰。


aws kms generate-data-key-without-plaintext \
    --key-id "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
    --key-spec AES_256

輸出：


{
    "CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogL",
    "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

CiphertextBlob (加密的資料金鑰) 會以 base64 編碼格式傳回。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的資料金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GenerateDataKeyWithoutPlaintext。

以下程式碼範例顯示如何使用 generate-data-key。

AWS CLI

範例 1：產生 256 位元對稱資料金鑰

下列 generate-data-key 範例會請求在 AWS 之外使用的 256 位元對稱資料金鑰。命令會傳回純文字資料金鑰，以供立即使用和刪除，以及在指定的 KMS 金鑰下加密的資料金鑰複本。加密的資料金鑰可以安全地跟加密資料一起存放。

您指定的 KMS 金鑰必須是對稱加密 KMS 金鑰，也就是 KeySpec 值為 SYMMETRIC_DEFAULT 的 KMS 金鑰。


aws kms generate-data-key \
    --key-id alias/ExampleAlias \
    --key-spec AES_256

輸出：


{
    "Plaintext": "VdzKNHGzUAzJeRBVY+uUmofUGGiDzyB3+i9fVkh3piw=",
    "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
    "CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogLqPWZconQhwHAIBEIA7d9AC7GeJJM34njQvg4Wf1d5sw0NIo1MrBqZa+YdhV8MrkBQPeac0ReRVNDt9qleAt+SHgIRF8P0H+7U="
}

Plaintext (純文字資料金鑰) 和 CiphertextBlob (加密的資料金鑰) 會以 base64 編碼格式傳回。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的資料金鑰。範例 2：產生 512 位元對稱資料金鑰

下列 generate-data-key 範例會請求 512 位元對稱資料金鑰，以進行加密和解密。命令會傳回純文字資料金鑰，以供立即使用和刪除，以及在指定的 KMS 金鑰下加密的資料金鑰複本。加密的資料金鑰可以安全地跟加密資料一起存放。

若要請求 128 或 256 位元以外的金鑰長度，請使用 number-of-bytes 參數。若要請求 512 位元資料金鑰，下列範例會使用值為 64 (位元組) 的 number-of-bytes 參數。

您指定的 KMS 金鑰必須是對稱加密 KMS 金鑰，也就是 KeySpec 值為 SYMMETRIC_DEFAULT 的 KMS 金鑰。

注意：此範例輸出中的值會截斷以方便顯示。


aws kms generate-data-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --number-of-bytes 64

輸出：


{
    "CiphertextBlob": "AQIBAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAEnX/QQNmMwDfg2korNMEc8AAACaDCCAmQGCSqGSIb3DQEHBqCCAlUwggJRAgEAMIICSgYJKoZ...",
    "Plaintext": "ty8Lr0Bk6OF07M2BWt6qbFdNB+G00ZLtf5MSEb4al3R2UKWGOp06njAwy2n72VRm2m7z/Pm9Wpbvttz6a4lSo9hgPvKhZ5y6RTm4OovEXiVfBveyX3DQxDzRSwbKDPk/...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

Plaintext (純文字資料金鑰) 和 CiphertextBlob (加密的資料金鑰) 會以 base64 編碼格式傳回。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的資料金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GenerateDataKey。

以下程式碼範例顯示如何使用 generate-mac。

AWS CLI

範例 1：產生訊息的 HMAC

下列 generate-mac 命令會產生訊息的 HMAC、HMAC KMS 金鑰和 MAC 演算法。演算法必須由指定的 HMAC KMS 金鑰支援。

在 AWS CLI v2 中，message 參數的值必須是以 Base64 編碼。或者，您可以將訊息儲存在檔案中，並使用 fileb:// 字首，告知 AWS CLI 從檔案讀取二進位資料。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。金鑰 ID 必須代表金鑰用量為 GENERATE_VERIFY_MAC 的 HMAC KMS 金鑰。


msg=(echo 'Hello World' | base64)

aws kms generate-mac \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://Message \
    --mac-algorithm HMAC_SHA_384

輸出：


{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "Mac": "<HMAC_TAG>",
    "MacAlgorithm": "HMAC_SHA_384"
}

如需有關在 AWS KMS 中使用 HMAC KMS 的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的 HMAC 金鑰。

範例 2：將 HMAC 儲存在檔案中 (Linux 和 macOs)

下列 generate-mac 範例會為儲存在本機檔案中的簡訊產生 HMAC。命令也會從回應取得 Mac 屬性，以 Base64 進行解碼，然後將其儲存在 ExampleMac 檔案中。您可以在驗證 MAC 的 verify-mac 命令中使用 MAC 檔案。

generate-mac 命令需要以 Base64 編碼的訊息，和 HMAC KMS 金鑰支援的 MAC 演算法。若要取得 KMS 金鑰支援的 MAC 演算法，請使用 describe-key 命令。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。金鑰 ID 必須代表金鑰用量為 GENERATE_VERIFY_MAC 的非對稱 KMS 金鑰。


echo 'hello world' | base64 > EncodedMessage

aws kms generate-mac \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://EncodedMessage \
    --mac-algorithm HMAC_SHA_384 \
    --output text \
    --query Mac | base64 --decode > ExampleMac

此命令不會產生輸出。此範例會擷取輸出的 Mac 屬性，並將其儲存在檔案中。

如需有關在 AWS KMS 中使用 HMAC KMS 的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的 HMAC 金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GenerateMac。

以下程式碼範例顯示如何使用 generate-random。

AWS CLI

範例 1：產生 256 位元隨機位元組字串 (Linux 或 macOs)

下列 generate-random 範例會產生 256 位元 (32 位元組) 的 base64 編碼隨機位元組字串。此範例會解碼位元組字串，並將其儲存在隨機檔案中。

執行此命令時，您必須使用 number-of-bytes 參數來指定以位元組為單位的隨機值長度。

當您執行此命令時，不會指定 KMS 金鑰。隨機位元組字串與任何 KMS 金鑰無關。

根據預設，AWS KMS 會產生隨機數字。不過，如果您指定自訂金鑰存放區，隨機位元組字串會在與自訂金鑰存放區相關聯的 AWS CloudHSM 叢集中產生。

此範例使用下列參數和值：

範例使用值為 32 的必要 --number-of-bytes 參數來請求 32 位元組 (256 位元) 字串。範例使用值為 text 的 --output 參數來指示 AWS CLI 以文字形式 (而不是 JSON) 傳回輸出。範例使用 --query parameter 以從回應中擷取 Plaintext 屬性值。範例使用管線 (|) 分隔命令的輸出，並擷取到 base64 公用程式，以將擷取的輸出解碼。範例使用重新導向運算子 (>) 將解碼的位元組字串儲存到 ExampleRandom 檔案中。範例使用重新導向運算子 (>) 將二進位加密文字儲存到檔案中。


aws kms generate-random \
    --number-of-bytes 32 \
    --output text \
    --query Plaintext | base64 --decode > ExampleRandom

此命令不會產生輸出。

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的 GenerateRandom。

範例 2：產生 256 位元隨機數字 (Windows 命令提示)

下列範例使用 generate-random 命令來產生 256 位元 (32 位元組) 的 base64 編碼隨機位元組字串。此範例會解碼位元組字串，並將其儲存在隨機檔案中。此範例與先前的範例相同，不過它會在 Windows 中使用 certutil 公用程式將隨機位元組字串進行 base64 解碼，然後再將其儲存在檔案中。

首先，產生 base64 編碼的隨機位元組字串，並將其儲存在暫存檔案 ExampleRandom.base64 中。


aws kms generate-random \
    --number-of-bytes 32 \
    --output text \
    --query Plaintext > ExampleRandom.base64

由於 generate-random 命令的輸出會儲存在檔案中，此範例不會產生輸出。

現在，請使用 certutil -decode 命令來解碼 ExampleRandom.base64 檔案中的 base64 編碼位元組字串。然後，其會將解碼後的位元組字串儲存在 ExampleRandom 檔案中。


certutil -decode ExampleRandom.base64 ExampleRandom

輸出：


Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的 GenerateRandom。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GenerateRandom。

以下程式碼範例顯示如何使用 get-key-policy。

AWS CLI

將金鑰政策從某個 KMS 金鑰複製到另一個 KMS 金鑰

下列 get-key-policy 範例會從一個 KMS 金鑰取得金鑰政策，並將其儲存在文字檔中。然後，其會使用文字檔取代不同 KMS 金鑰的政策，作為政策輸入。

由於 put-key-policy 的 --policy 參數需要字串，您必須使用 --output text 選項將輸出以文字字串傳回，而非 JSON。


aws kms get-key-policy \
    --policy-name default \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --query Policy \
    --output text > policy.txt

aws kms put-key-policy \
    --policy-name default \
    --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --policy file://policy.txt

此命令不會產生輸出。

如需詳細資訊，請參閱《AWS KMS API 參考》中的 PutKeyPolicy。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GetKeyPolicy。

以下程式碼範例顯示如何使用 get-key-rotation-status。

AWS CLI

擷取 KMS 金鑰的輪換狀態。

下列 get-key-rotation-status 範例會傳回指定 KMS 金鑰輪換狀態的相關資訊，包括是否啟用自動輪換、輪換期間，以及下一個排程的輪換日期。您可以在客戶自管 KMS 金鑰和 AWS 受管 KMS 金鑰上使用此命令。不過，所有 AWS 受管 KMS 金鑰每年都會自動輪換。


aws kms get-key-rotation-status \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyRotationEnabled": true,
    "NextRotationDate": "2024-02-14T18:14:33.587000+00:00",
    "RotationPeriodInDays": 365
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的輪換金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GetKeyRotationStatus。

以下程式碼範例顯示如何使用 get-parameters-for-import。

AWS CLI

取得將金鑰材料匯入 KMS 金鑰所需的項目

下列 get-parameters-for-import 範例會取得將金鑰材料匯入 KMS 金鑰所需的公有金鑰和匯入字符。當您使用 import-key-material 命令時，請務必使用由相同 get-parameters-for-import 命令中傳回的公有金鑰加密的匯入字符和金鑰材料。此外，您在此命令中指定的包裝演算法，必須是您使用公有金鑰加密金鑰材料的演算法。

若要指定 KMS 金鑰，請使用 key-id 參數。此範例使用金鑰 ID，但您可以在此命令中使用金鑰 ID 或金鑰 ARN。


aws kms get-parameters-for-import \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --wrapping-key-spec RSA_2048

輸出：


{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "PublicKey": "<public key base64 encoded data>",
    "ImportToken": "<import token base64 encoded data>",
    "ParametersValidTo": 1593893322.32
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的下載公有金鑰和匯入字符。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GetParametersForImport。

以下程式碼範例顯示如何使用 get-public-key。

AWS CLI

範例 1：下載非對稱 KMS 金鑰的公有金鑰

下列 get-public-key 範例會下載非對稱 KMS 金鑰的公有金鑰。

除了傳回公有金鑰之外，輸出還包含您在 AWS KMS 以外安全使用公有金鑰所需的資訊，包括金鑰用量和支援的加密演算法。


aws kms get-public-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "PublicKey": "jANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAl5epvg1/QtJhxSi2g9SDEVg8QV/...",
    "CustomerMasterKeySpec": "RSA_4096",
    "KeyUsage": "ENCRYPT_DECRYPT",
    "EncryptionAlgorithms": [
        "RSAES_OAEP_SHA_1",
        "RSAES_OAEP_SHA_256"
    ]
}

如需有關在 AWS KMS 中使用非對稱 KMS 金鑰的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。範例 2：將公有金鑰轉換為 DER 格式 (Linux 和 macOS)

下列 get-public-key 範例會下載非對稱 KMS 金鑰的公有金鑰，並將其儲存在 DER 檔案中。

當您在 CLI AWS 中使用 get-public-key 命令時，該命令會傳回以 Base64 編碼的 DER 編碼 X.509 公有金鑰。此範例會以文字形式取得 PublicKey 屬性的值。其會 Base64 解碼 PublicKey，並將其儲存在 public_key.der 檔案中。output 參數會以文字形式傳回輸出，而非 JSON。--query 參數只會取得 PublicKey 屬性，而不是您在 AWS KMS 之外安全使用公有金鑰所需的屬性。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。


aws kms get-public-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --output text \
    --query PublicKey | base64 --decode > public_key.der

此命令不會產生輸出。

如需有關在 AWS KMS 中使用非對稱 KMS 金鑰的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 GetPublicKey。

以下程式碼範例顯示如何使用 import-key-material。

AWS CLI

將金鑰材料匯入 KMS 金鑰

下列 import-key-material 範例會將金鑰材料上傳至不使用金鑰材料建立的 KMS 金鑰。KMS 金鑰的金鑰狀態必須是 PendingImport。

此命令使用您以 get-parameters-for-import 命令傳回的公有金鑰加密的金鑰材料。其也會使用來自相同 get-parameters-for-import 命令的匯入字符。

expiration-model 參數指出，金鑰材料會在 valid-to 參數指定的日期和時間自動到期。當金鑰材料到期時，AWS KMS 會刪除金鑰材料，KMS 金鑰的金鑰狀態會變更為 Pending import，而 KMS 金鑰會變成無法使用。若要還原 KMS 金鑰，您必須將相同的金鑰材料重新匯入。若要使用不同的金鑰材料，您必須建立新的 KMS 金鑰。

執行此命令之前，請將範例金鑰 ID 取代為 AWS 帳戶的有效 ID 或金鑰 ARN。


aws kms import-key-material \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --encrypted-key-material fileb://EncryptedKeyMaterial.bin \
    --import-token fileb://ImportToken.bin \
    --expiration-model KEY_MATERIAL_EXPIRES \
    --valid-to 2021-09-21T19:00:00Z

輸出：


{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的匯入金鑰材料。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ImportKeyMaterial。

以下程式碼範例顯示如何使用 list-aliases。

AWS CLI

範例 1：列出 AWS 帳戶和區域中的所有別名

下列範例使用 list-aliases 命令列出 AWS 帳戶預設區域中的所有別名。輸出包含與 AWS 受管 KMS 金鑰和客戶自管 KMS 金鑰相關聯的別名。


aws kms list-aliases

輸出：


{
    "Aliases": [
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/testKey",
            "AliasName": "alias/testKey",
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
        },
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/FinanceDept",
            "AliasName": "alias/FinanceDept",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
        },
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb",
            "AliasName": "alias/aws/dynamodb",
            "TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
        },
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs",
            "AliasName": "alias/aws/ebs",
            "TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef"
        },
        ...
    ]
}

範例 2：列出特定 KMS 金鑰的所有別名

下列範例使用 list-aliases 命令及其 key-id 參數來列出與特定 KMS 金鑰相關聯的所有別名。

每個別名只會與一個 KMS 金鑰相關聯，但 KMS 金鑰可以有多個別名。此命令非常有用，因為 AWS KMS 主控台只會為每個 KMS 金鑰列出一個別名。若要尋找 KMS 金鑰的所有別名，您必須使用 list-aliases 命令。

此範例使用 --key-id 參數之 KMS 金鑰的金鑰 ID，但您可以在此命令中使用金鑰 ID、金鑰 ARN、別名的名稱，或別名 ARN。


aws kms list-aliases --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "Aliases": [
        {
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/oregon-test-key",
            "AliasName": "alias/oregon-test-key"
        },
        {
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/project121-test",
            "AliasName": "alias/project121-test"
        }
    ]
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的使用別名。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ListAliases。

以下程式碼範例顯示如何使用 list-grants。

AWS CLI

檢視 AWS KMS 金鑰上的授權

下列 list-grants 範例顯示您帳戶中 Amazon DynamoDB 之指定 AWS 受管 KMS 金鑰的所有授權。此授權可讓 DynamoDB 代表您使用 KMS 金鑰加密 DynamoDB 資料表，然後再寫入磁碟。您可以使用像這樣的命令，檢視 AWS 帳戶和區域中 AWS 受管 KMS 金鑰和客戶自管 KMS 金鑰的授權。

此命令搭配使用 key-id 參數和金鑰 ID 來識別 KMS 金鑰。您可以使用金鑰 ID 或金鑰 ARN 來識別 KMS 金鑰。若要取得 AWS 受管 KMS 金鑰的金鑰 ID 或金鑰 ARN，請使用 list-keys 或 list-aliases 命令。


aws kms list-grants \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出顯示，授權包括為 Amazon DynamoDB 提供使用 KMS 金鑰進行密碼編譯操作的許可，並提供讓其檢視 KMS 金鑰 (DescribeKey) 詳細資訊，和淘汰授予 (RetireGrant) 的權限。EncryptionContextSubset 限制條件會將這些許可限制為包含指定加密內容對的請求。因此，授予的許可僅在指定的帳戶和 DynamoDB 資料表上有效。


{
    "Grants": [
        {
            "Constraints": {
                "EncryptionContextSubset": {
                    "aws:dynamodb:subscriberId": "123456789012",
                    "aws:dynamodb:tableName": "Services"
                }
            },
            "IssuingAccount": "arn:aws:iam::123456789012:root",
            "Name": "8276b9a6-6cf0-46f1-b2f0-7993a7f8c89a",
            "Operations": [
                "Decrypt",
                "Encrypt",
                "GenerateDataKey",
                "ReEncryptFrom",
                "ReEncryptTo",
                "RetireGrant",
                "DescribeKey"
            ],
            "GrantId": "1667b97d27cf748cf05b487217dd4179526c949d14fb3903858e25193253fe59",
            "KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "RetiringPrincipal": "dynamodb.us-west-2.amazonaws.com",
            "GranteePrincipal": "dynamodb.us-west-2.amazonaws.com",
            "CreationDate": "2021-05-13T18:32:45.144000+00:00"
        }
    ]
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的在 AWS KMS 中授予。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ListGrants。

以下程式碼範例顯示如何使用 list-key-policies。

AWS CLI

取得 KMS 金鑰的金鑰政策名稱

下列 list-key-policies 範例會取得範例帳戶和區域中客戶自管金鑰的金鑰政策名稱。您可以使用此命令來尋找 AWS 受管金鑰和客戶自管金鑰的金鑰政策名稱。

由於唯一有效的金鑰政策名稱是 default，因此這個命令沒有作用。

若要指定 KMS 金鑰，請使用 key-id 參數。此範例使用金鑰 ID 值，但您可以在此命令中使用金鑰 ID 或金鑰 ARN。


aws kms list-key-policies \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "PolicyNames": [
    "default"
    ]
}

如需有關 AWS KMS 金鑰政策的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的在 AWS KMS 中使用關鍵政策。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ListKeyPolicies。

以下程式碼範例顯示如何使用 list-key-rotations。

AWS CLI

擷取所有已完成金鑰材料輪換的相關資訊

下列 list-key-rotations 範例列出指定 KMS 金鑰之所有已完成金鑰材料輪換的相關資訊。


aws kms list-key-rotations \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "Rotations": [
        {
            "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "RotationDate": "2024-03-02T10:11:36.564000+00:00",
            "RotationType": "AUTOMATIC"
        },
        {
            "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "RotationDate": "2024-04-05T15:14:47.757000+00:00",
            "RotationType": "ON_DEMAND"
        }
    ],
    "Truncated": false
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的輪換金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ListKeyRotations。

以下程式碼範例顯示如何使用 list-keys。

AWS CLI

取得帳戶和區域中的 KMS 金鑰

下列 list-keys 範例取得帳戶和區域中的 KMS 金鑰。此命令會同時傳回 AWS 受管金鑰和客戶自管金鑰。


aws kms list-keys

輸出：


{
    "Keys": [
        {
            "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
        },
        {
            "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
            "KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
        },
        {
            "KeyArn": "arn:aws:kms:us-east-2:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
            "KeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
        }
    ]
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的檢視金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ListKeys。

以下程式碼範例顯示如何使用 list-resource-tags。

AWS CLI

取得 KMS 金鑰上的標籤

下列 list-resource-tags 範例會取得 KMS 金鑰的標籤。若要新增或取代 KMS 金鑰上的資源標籤，請使用 tag-resource 命令。輸出中顯示此 KMS 金鑰有兩個資源標籤，每個標籤都有一個金鑰和值。

若要指定 KMS 金鑰，請使用 key-id 參數。此範例使用金鑰 ID 值，但您可以在此命令中使用金鑰 ID 或金鑰 ARN。


aws kms list-resource-tags \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "Tags": [
    {
        "TagKey": "Dept",
        "TagValue": "IT"
    },
    {
        "TagKey": "Purpose",
        "TagValue": "Test"
    }
    ],
    "Truncated": false
}

如需有關在 AWS KMS 中使用標籤的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的標記金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ListResourceTags。

以下程式碼範例顯示如何使用 list-retirable-grants。

AWS CLI

檢視主體可以淘汰的授予

下列 list-retirable-grants 範例顯示 ExampleAdmin 使用者可以在 AWS 帳戶和區域中的 KMS 金鑰淘汰的所有授予。您可以使用像這樣的命令，檢視任何帳戶主體可以在 AWS 帳戶和區域中的 KMS 金鑰上淘汰的授予。

必要 retiring-principal 參數的值必須是帳戶、使用者或角色的 Amazon Resource Name (ARN)。

您無法在此命令中指定 retiring-principal 值的服務，即使服務可以是淘汰的主體。若要尋找特定服務為淘汰主體的授予，請使用 list-grants 命令。

輸出中顯示，ExampleAdmin 使用者有權淘汰帳戶和區域中兩個不同 KMS 金鑰的授予。除了淘汰主體之外，帳戶還擁有淘汰帳戶中任何授予的許可。


aws kms list-retirable-grants \
    --retiring-principal arn:aws:iam::111122223333:user/ExampleAdmin

輸出：


{
    "Grants": [
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "GrantId": "156b69c63cb154aa21f59929ff19760717be8d9d82b99df53e18b94a15a5e88e",
            "Name": "",
            "CreationDate": 2021-01-14T20:17:36.419000+00:00,
            "GranteePrincipal": "arn:aws:iam::111122223333:user/ExampleUser",
            "RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "Operations": [
                "Encrypt"
            ],
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                }
            }
        },
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
            "GrantId": "8c94d1f12f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
            "Name": "",
            "CreationDate": "2021-02-02T19:49:49.638000+00:00",
            "GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
            "RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "Operations": [
                "Decrypt"
            ],
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                }
            }
        }
    ],
    "Truncated": false
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的在 AWS KMS 中授予。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ListRetirableGrants。

以下程式碼範例顯示如何使用 put-key-policy。

AWS CLI

變更 KMS 金鑰的金鑰政策

下列 put-key-policy 範例會變更客戶自管金鑰的金鑰政策。

一開始，請建立金鑰政策，並將其儲存在本機 JSON 檔案中。在此範例中，檔案是 key_policy.json。您也可以將金鑰政策指定為 policy 參數的字串值。

此金鑰政策中的第一個陳述式，提供 AWS 帳戶使用 IAM 政策控制 KMS 金鑰存取的許可。第二個陳述式提供 test-user 使用者在 KMS 金鑰上執行 describe-key 和 list-keys 命令的許可。

key_policy.json 的內容：


{
    "Version":"2012-10-17",		 	 	 
    "Id" : "key-default-1",
    "Statement" : [
        {
            "Sid" : "Enable IAM User Permissions",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:root"
            },
            "Action" : "kms:*",
            "Resource" : "*"
        },
        {
            "Sid" : "Allow Use of Key",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:user/test-user"
            },
            "Action" : [
                "kms:DescribeKey",
                "kms:ListKeys"
            ],
            "Resource" : "*"
        }
    ]
}

若要識別 KMS 金鑰，此範例會使用金鑰 ID，但您也可以使用金鑰 ARN。為指定金鑰政策，命令使用 policy 參數。為了指出政策位於檔案中，其會使用必要的 file:// 字首。要識別所有支援的作業系統上的檔案，需要此字首。最後，命令會使用值為 default 的 policy-name 參數。若未指定政策名稱，預設值為 default。唯一有效的值為 default。


aws kms put-key-policy \
    --policy-name default \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --policy file://key_policy.json

此命令不會產生任何輸出。若要驗證命令是否有效，請使用 get-key-policy 命令。下列範例命令會取得相同 KMS 金鑰的金鑰政策。值為 text 的 output 參數會傳回易於讀取的文字格式。


aws kms get-key-policy \
    --policy-name default \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --output text

輸出：


{
    "Version":"2012-10-17",		 	 	 
    "Id" : "key-default-1",
    "Statement" : [
        {
            "Sid" : "Enable IAM User Permissions",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:root"
            },
            "Action" : "kms:*",
            "Resource" : "*"
            },
            {
            "Sid" : "Allow Use of Key",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:user/test-user"
            },
            "Action" : [ "kms:Describe", "kms:List" ],
            "Resource" : "*"
        }
    ]
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的變更金鑰政策。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 PutKeyPolicy。

以下程式碼範例顯示如何使用 re-encrypt。

AWS CLI

範例 1：在不同的對稱 KMS 金鑰 (Linux 和 macOS) 下，重新加密訊息。

下列 re-encrypt 命令範例展示使用 AWS CLI 重新加密資料的建議方法。

在檔案中提供密文。--ciphertext-blob 參數的值中，使用 fileb:// 字首，其會告知 CLI 從二進位檔案讀取資料。如果檔案不在目前的目錄中，請輸入檔案的完整路徑。如需從檔案讀取 AWS CLI 參數值的詳細資訊，請參閱《AWS 命令列介面使用者指南》中的從檔案載入 AWS CLI 參數，以及《AWS 命令列工具部落格》中的本機檔案參數最佳實務。指定解密加密文字的來源 KMS 金鑰。使用對稱加密 KMS 金鑰解密時，不需要 --source-key-id 參數。AWSKMS 可以取得 KMS 金鑰，以用於加密文字 Blob 中之中繼資料的資料。但是指定您正在使用的 KMS 金鑰永遠是最佳實務。此做法可確保使用您想要的 KMS 金鑰，並可防止不小心使用不信任的 KMS 金鑰解密加密文字。指定目的地 KMS 金鑰，這會重新加密資料。--destination-key-id 參數一律為必要項。此範例使用金鑰 ARN，但您可以使用任何有效的金鑰識別碼。請求純文字輸出作為文字值。--query 參數會告知 CLI 僅從輸出取得 Plaintext 欄位的值。--output 參數會以純文字傳回輸出。Base64 將純文字解碼，並儲存在檔案中。下列範例會將 Plaintext 參數的管道符號 (|) 值輸送至 Base64 公用程式，以將其解碼。然後，將解碼的輸出重新導向 (>) 至 ExamplePlaintext 檔案。

執行此命令前，請將範例金鑰 ID 取代為 AWS 帳戶的有效金鑰識別碼。


aws kms re-encrypt \
    --ciphertext-blob fileb://ExampleEncryptedFile \
    --source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --query CiphertextBlob \
    --output text | base64 --decode > ExampleReEncryptedFile

此命令不會產生輸出。來自 re-encrypt 命令的輸出經過 base64 解碼，並儲存在檔案中。

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的 ReEncrypt。

範例 2：在不同的對稱 KMS 金鑰 (Windows 命令提示) 下，重新加密已加密的訊息。

下列 re-encrypt 命令範例與上一個範例相同，唯一不同的是它使用 certutil 公用程式對純文字資料進行 Base64 解碼。如下列範例所示，此程序需要兩個命令。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。


aws kms re-encrypt ^
    --ciphertext-blob fileb://ExampleEncryptedFile ^
    --source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
    --destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 ^
    --query CiphertextBlob ^
    --output text > ExampleReEncryptedFile.base64

然後使用 certutil 公用程式


certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile

輸出：


Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的 ReEncrypt。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ReEncrypt。

以下程式碼範例顯示如何使用 retire-grant。

AWS CLI

淘汰客戶主金鑰的授予

下列 retire-grant 範例會從 KMS 金鑰刪除授予。

下列範例命令會指定 grant-id 和 key-id 參數。key-id 參數的值必須是 KMS 金鑰的金鑰 ARN。


aws kms retire-grant \
    --grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

此命令不會產生輸出。若要確認授予已淘汰，請使用 list-grants 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的淘汰和撤銷授予。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 RetireGrant。

以下程式碼範例顯示如何使用 revoke-grant。

AWS CLI

撤銷客戶主金鑰的授予

下列 revoke-grant 範例會從 KMS 金鑰刪除授予。下列範例命令會指定 grant-id 和 key-id 參數。key-id 參數的值可以是 KMS 金鑰的金鑰 ID 或金鑰 ARN。


aws kms revoke-grant \
    --grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

此命令不會產生輸出。若要確認授予已撤銷，請使用 list-grants 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的淘汰和撤銷授予。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 RevokeGrant。

以下程式碼範例顯示如何使用 rotate-key-on-demand。

AWS CLI

執行 KMS 金鑰的隨需輪換

下列 rotate-key-on-demand 範例會立即為指定的 KMS 金鑰啟動金鑰材料的輪換。


aws kms rotate-key-on-demand \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

輸出：


{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的如何執行隨需金鑰輪換。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 RotateKeyOnDemand。

以下程式碼範例顯示如何使用 schedule-key-deletion。

AWS CLI

為客戶自管 KMS 金鑰刪除排程。

下列 schedule-key-deletion 範例為需要在 15 天內刪除的指定客戶自管 KMS 金鑰排程。

--key-id 參數可識別 KMS 金鑰。此範例使用金鑰 ARN 值，但您可以使用金鑰 ID 或 KMS 金鑰的 ARN。--pending-window-in-days 參數會指定 7-30 天等待期的時間長度。預設等待期為 30 天。此範例會指定值 15，指示 AWS 在命令完成後的 15 天，永久刪除 KMS 金鑰。


aws kms schedule-key-deletion \
    --key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --pending-window-in-days 15

回應包含金鑰 ARN、金鑰狀態、等待期 (PendingWindowInDays)，以及以 Unix 時間表示的刪除日期。若要以當地時間檢視刪除日期，請使用 AWS KMS 主控台。PendingDeletion 金鑰狀態中的 KMS 金鑰，無法在密碼編譯操作中使用。


{
    "KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "DeletionDate": "2022-06-18T23:43:51.272000+00:00",
    "KeyState": "PendingDeletion",
    "PendingWindowInDays": 15
}

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的刪除金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 ScheduleKeyDeletion。

以下程式碼範例顯示如何使用 sign。

AWS CLI

範例 1：產生訊息的數位簽章

下列 sign 範例會產生簡訊的密碼編譯簽章。命令的輸出包含 base-64 編碼 Signature 欄位，您可以使用 verify 命令進行驗證。

您必須指定要簽署的訊息，以及非對稱 KMS 金鑰支援的簽署演算法。若要取得 KMS 金鑰的簽署演算法，請使用 describe-key 命令。

在 AWS CLI v2 中，message 參數的值必須是以 Base64 編碼。或者，您可以將訊息儲存在檔案中，並使用 fileb:// 字首，告知 AWS CLI 從檔案讀取二進位資料。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。金鑰 ID 必須代表金鑰用量為 SIGN_VERIFY 的非對稱 KMS 金鑰。


msg=(echo 'Hello World' | base64)

aws kms sign \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://UnsignedMessage \
    --message-type RAW \
    --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256

輸出：


{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "Signature": "ABCDEFhpyVYyTxbafE74ccSvEJLJr3zuoV1Hfymz4qv+/fxmxNLA7SE1SiF8lHw80fKZZ3bJ...",
    "SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}

如需有關在 AWS KMS 中使用非對稱 KMS 金鑰的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

範例 2：在檔案 (Linux 和 macOs) 中儲存數位簽章

下列 sign 範例會為儲存在本機檔案中的簡訊產生密碼編譯簽章。命令也會從回應取得 Signature 屬性，以 Base64 進行解碼，然後將其儲存在 ExampleSignature 檔案中。您可以在驗證簽章的 verify 命令中使用簽章檔案。

sign 命令需要以 Base64 編碼的訊息，以及非對稱 KMS 金鑰支援的簽署演算法。若要取得 KMS 金鑰支援的簽署演算法，請使用 describe-key 命令。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。金鑰 ID 必須代表金鑰用量為 SIGN_VERIFY 的非對稱 KMS 金鑰。


echo 'hello world' | base64 > EncodedMessage

aws kms sign \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://EncodedMessage \
    --message-type RAW \
    --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
    --output text \
    --query Signature | base64 --decode > ExampleSignature

此命令不會產生輸出。此範例會擷取輸出的 Signature 屬性，並將其儲存在檔案中。

如需有關在 AWS KMS 中使用非對稱 KMS 金鑰的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的非對稱金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 Sign。

以下程式碼範例顯示如何使用 tag-resource。

AWS CLI

將標籤新增至 KMS 金鑰

下列tag-resource 範例會將 "Purpose":"Test" 和 "Dept":"IT" 標籤新增至客戶自管 KMS 金鑰。您可以使用這類標籤來標記 KMS 金鑰，並建立 KMS 金鑰類別以供許可和稽核之用。

若要指定 KMS 金鑰，請使用 key-id 參數。此範例使用金鑰 ID 值，但您可以在此命令中使用金鑰 ID 或金鑰 ARN。


aws kms tag-resource \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --tags TagKey='Purpose',TagValue='Test' TagKey='Dept',TagValue='IT'

此命令不會產生輸出。若要檢視 AWS KMS KMS 金鑰上的標籤，請使用 list-resource-tags 命令。

如需有關在 AWS KMS 中使用標籤的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的標記金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 TagResource。

以下程式碼範例顯示如何使用 untag-resource。

AWS CLI

從金鑰對刪除標籤

下列 untag-resource 範例會從客戶自管 KMS 金鑰，刪除具有 "Purpose" 金鑰的標籤。

若要指定 KMS 金鑰，請使用 key-id 參數。此範例使用金鑰 ID 值，但您可以在此命令中使用金鑰 ID 或金鑰 ARN。執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。


aws kms untag-resource \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --tag-key 'Purpose'

此命令不會產生輸出。若要檢視 AWS KMS KMS 金鑰上的標籤，請使用 list-resource-tags 命令。

如需有關在 AWS KMS 中使用標籤的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的標記金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 UntagResource。

以下程式碼範例顯示如何使用 update-alias。

AWS CLI

將別名與不同的 KMS 金鑰相關聯

下列 update-alias 範例會將別名 alias/test-key 與不同的 KMS 金鑰建立關聯。

請注意，--alias-name 參數會指定別名。別名的名稱值必須以 alias/ 開頭。--target-key-id 參數會指定要與別名建立關聯的 KMS 金鑰。您不需要為別名指定目前的 KMS 金鑰。


aws kms update-alias \
    --alias-name alias/test-key \
    --target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab

此命令不會產生輸出。要尋找別名，請使用 list-aliases 命令。

如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的更新別名。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 UpdateAlias。

以下程式碼範例顯示如何使用 update-custom-key-store。

AWS CLI

範例 1：編輯自訂金鑰存放區的易記名稱

下列 update-custom-key-store 範例會變更自訂金鑰存放區的名稱。此範例適用於 AWS CloudHSM 金鑰存放區或外部金鑰存放區。

使用 custom-key-store-id 識別金鑰存放區。使用 new-custom-key-store-name 參數指定新的易記名稱。

若要更新 AWS CloudHSM 金鑰存放區的易記名稱，您必須先中斷連接金鑰存放區，例如使用 disconnect-custom-key-store 命令。您可以在外部金鑰存放區連線或中斷連線時，更新其易記名稱。若要尋找自訂金鑰存放區的連線狀態，請使用 describe-custom-key-store 命令。


aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --new-custom-key-store-name ExampleKeyStore

此命令不會傳回任何資料。若要驗證命令是否正常運作，請使用 describe-custom-key-stores 命令。

如需有關更新 AWS CloudHSM 金鑰存放區的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的編輯 AWS CloudHSM 金鑰存放區設定。

如需有關更新外部金鑰存放區的詳細資訊，請參閱《AWSKey Management Service 開發人員指南》中的編輯外部金鑰存放區屬性。

範例 2：編輯 AWS CloudHSM 金鑰存放區的 kmsuser 密碼

下列 update-custom-key-store 範例會將 kmsuser 密碼的值更新為：與指定金鑰存放區相關聯之 CloudHSM 叢集中 kmsuser 的目前密碼。此命令不會變更叢集的 kmsuser 密碼。其只告訴 AWS KMS 目前的密碼。如果 KMS 沒有目前的 kmsuser 密碼，則無法連線至 AWS CloudHSM 金鑰存放區。

注意：在更新 AWS CloudHSM 金鑰存放區之前，必須中斷連線。使用 disconnect-custom-key-store 命令。命令完成後，您可以重新連接 AWS CloudHSM 金鑰存放區。使用 connect-custom-key-store 命令。


aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --key-store-password ExamplePassword

此命令不會傳回任何輸出。若要驗證變更是否有效，請使用 describe-custom-key-stores 命令。

如需有關更新 AWS CloudHSM 金鑰存放區的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的編輯 AWS CloudHSM 金鑰存放區設定。

範例 3：編輯 AWS CloudHSM 金鑰存放區的 AWS CloudHSM 叢集

下列範例會將與 AWS CloudHSM 金鑰存放區相關聯的 AWS CloudHSM 叢集變更為相關叢集，例如相同叢集的不同備份。


aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --cloud-hsm-cluster-id cluster-1a23b4cdefg

此命令不會傳回任何輸出。若要驗證變更是否有效，請使用 describe-custom-key-stores 命令。

如需有關更新 AWS CloudHSM 金鑰存放區的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的編輯 AWS CloudHSM 金鑰存放區設定。

範例 4：編輯外部金鑰存放區的代理身分驗證憑證

以下範例更新外部金鑰存放區的代理身分驗證憑證。您必須同時指定 raw-secret-access-key 和 access-key-id，即使您只變更其中一個值。您可以使用此功能來修正無效的憑證，或在外部金鑰存放區代理輪換憑證時變更憑證。

在您的外部金鑰存放區上為 AWS KMS 建立代理身分驗證憑證。然後，使用此命令將憑證提供給 AWS KMS。AWSKMS 使用此憑證來簽署其對您的外部金鑰存放區代理的請求。

您可以在連接或中斷連接外部金鑰存放區時，更新代理身分驗證憑證。若要尋找自訂金鑰存放區的連線狀態，請使用 describe-custom-key-store 命令。


aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="

此命令不會傳回任何輸出。若要驗證變更是否有效，請使用 describe-custom-key-stores 命令。

如需有關更新外部金鑰存放區的詳細資訊，請參閱《AWSKey Management Service 開發人員指南》中的編輯外部金鑰存放區屬性。

範例 5：編輯外部金鑰存放區的代理連線

下列範例會將外部金鑰存放區代理連線選項，從公有端點連線變更為 VPC 端點服務連線。除了變更 xks-proxy-connectivity 值之外，您還必須變更 xks-proxy-uri-endpoint 值，以反映與 VPC 端點服務相關聯的私有 DNS 名稱。您也必須新增 xks-proxy-vpc-endpoint-service-name 值。

注意：在更新外部存放區的代理連線之前，您必須中斷連線。使用 disconnect-custom-key-store 命令。命令完成後，您可以使用 connect-custom-key-store 命令重新連接外部金鑰存放區。


aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
    --xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
    --xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example"

此命令不會傳回任何輸出。若要驗證變更是否有效，請使用 describe-custom-key-stores 命令。

如需有關更新外部金鑰存放區的詳細資訊，請參閱《AWSKey Management Service 開發人員指南》中的編輯外部金鑰存放區屬性。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 UpdateCustomKeyStore。

以下程式碼範例顯示如何使用 update-key-description。

AWS CLI

範例 1：新增或變更客戶自管 KMS 金鑰的描述

下列 update-key-description 範例會將描述新增至客戶自管 KMS 金鑰。您可以使用相同的命令來變更現有的描述。

--key-id 參數會在命令中識別 KMS 金鑰。此範例使用金鑰 ARN 值，但您可以使用金鑰 ID 或 KMS 金鑰的金鑰 ARN。--description 參數會指定新的描述。此參數的值會取代 KMS 金鑰的目前描述 (如果有)。


aws kms update-key-description \
    --key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --description "IT Department test key"

此命令不會產生輸出。若要檢視 KMS 金鑰的描述，請使用 describe-key 命令。

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的 UpdateKeyDescription。

範例 2：刪除客戶自管 KMS 金鑰的描述

下列 update-key-description 範例會刪除客戶自管 KMS 金鑰的描述。

--key-id 參數會在命令中識別 KMS 金鑰。此範例使用金鑰 ID 值，但您可以使用 KMS 金鑰的金鑰 ID 或金鑰 ARN。具有空字串值 ('') 的 --description 參數會刪除現有的描述。


aws kms update-key-description \
    --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --description ''

此命令不會產生輸出。若要檢視 KMS 金鑰的描述，請使用 describe-key 命令。

如需詳細資訊，請參閱《AWS Key Management Service API 參考》中的 UpdateKeyDescription。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 UpdateKeyDescription。

以下程式碼範例顯示如何使用 verify-mac。

AWS CLI

範例 1：驗證 HMAC

下列 verify-mac 命令會驗證特定訊息的 HMAC、HMAC KMS 金鑰和 MAC 演算法。MacValid 值中的 'true' 值表示 HMAC 有效。

在 AWS CLI v2 中，message 參數的值必須是以 Base64 編碼。或者，您可以將訊息儲存在檔案中，並使用 fileb:// 字首，告知 AWS CLI 從檔案讀取二進位資料。

您指定的 MAC 不能以 base64 編碼。如需將 generate-mac 命令傳回的 MAC 解碼的說明，請參閱 generate-mac 命令範例。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。金鑰 ID 必須代表金鑰用量為 GENERATE_VERIFY_MAC 的 HMAC KMS 金鑰。


msg=(echo 'Hello World' | base64)

aws kms verify-mac \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://Message \
    --mac-algorithm HMAC_SHA_384 \
    --mac fileb://ExampleMac

輸出：


{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "MacValid": true,
    "MacAlgorithm": "HMAC_SHA_384"
}

如需有關在 AWS KMS 中使用 HMAC KMS 的詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的 AWS KMS 中的 HMAC 金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 VerifyMac。

以下程式碼範例顯示如何使用 verify。

AWS CLI

驗證數位簽章

下列 verify 命令會驗證以 Base64 編碼的簡短訊息的加密簽章。金鑰 ID、訊息、訊息類型和簽署演算法，必須與用來簽署訊息的演算法相同。

在 AWS CLI v2 中，message 參數的值必須是以 Base64 編碼。或者，您可以將訊息儲存在檔案中，並使用 fileb:// 字首，告知 AWS CLI 從檔案讀取二進位資料。

您指定的簽章不能以 base64 編碼。如需將 sign 命令傳回的簽章解碼的說明，請參閱 sign 命令範例。

命令的輸出包含布林值 SignatureValid 欄位，指出簽章已驗證。如果簽章驗證失敗，verify 命令也會失敗。

執行此命令之前，請將範例金鑰 ID 更換成您 AWS 帳戶的有效 ID。


aws kms verify \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://EncodedMessage \
    --message-type RAW \
    --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
    --signature fileb://ExampleSignature

輸出：


{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "SignatureValid": true,
    "SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}

如需有關在 AWS KMS 中使用非對稱 KMS 金鑰的詳細資訊，請參閱《AWSKey Management Service 開發人員指南》中的使用非對稱金鑰。

如需 API 詳細資訊，請參閱《AWS CLI 命令參考》中的 Verify。

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

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

文件慣用形式

Kinesis

Lake Formation