當您需要自行管理並控制密鑰材料時，您可以在KMS執行個體中建立密鑰材料來源為外部的密鑰，然後匯入您自己的密鑰材料。本文介紹如何為對稱金鑰匯入密鑰材料。
如果您的軟體密鑰管理執行個體、硬體密鑰管理執行個體不支援匯入密鑰材料，或者匯入密鑰材料時返回失敗，請聯絡阿里雲支援人員升級執行個體。
功能介紹
密鑰是KMS的基本資源，由密鑰ID、基本中繼資料（如密鑰狀態等）以及密鑰材料組成。建立密鑰時，您可以選擇由KMS產生密鑰材料，也可以選擇外部來源的密鑰材料。如果選擇了外部來源的密鑰材料，您需要將外部金鑰材料匯入到密鑰中，該功能通常被稱為內建密鑰（BYOK）。
不同KMS密鑰管理類型對匯入密鑰材料的支援情況，請參見下表。關於密鑰管理類型的更多資訊，請參見密鑰管理類型和密鑰規格。
：表示支援匯入相應的密鑰材料。
：表示不支援匯入相應的密鑰材料。
密鑰管理類型 | 匯入對稱金鑰材料 | 匯入非對稱金鑰材料 |
預設密鑰 |
|
|
軟體密鑰 | √ | √ |
硬體密鑰 | √ | × |
注意事項
請確保使用了符合要求的隨機數發生器產生密鑰材料。
為密鑰首次匯入密鑰材料後，密鑰即和該密鑰材料綁定，不再支援匯入其他密鑰材料。
您可以根據需要將相同的密鑰材料多次匯入到KMS密鑰中，但不能將不同的密鑰材料匯入到一個KMS密鑰。
如果密鑰的密鑰材料到期或被刪除，您可以為密鑰再次匯入相同的密鑰材料，使得該密鑰再次可用，匯入密鑰材料後不支援匯出，因此請您妥善保管密鑰材料。
前提條件
已購買和啟用KMS執行個體。具體操作，請參見購買和啟用KMS執行個體。
為預設密鑰（主要金鑰）匯入密鑰材料時，無需購買KMS執行個體。
步驟一：建立密鑰材料來源為外部的對稱金鑰
匯入密鑰材料前，請建立密鑰材料來源為外部的對稱金鑰。
預設密鑰（主要金鑰）
登入Key Management Service控制台，在頂部功能表列選擇地區後，在左側導覽列單擊资源 > 密钥管理。
單擊默认密钥頁簽，單擊主要金鑰操作列的启用，在创建密钥頁簽完成配置項設定，然後單擊確定。
配置項
說明
密钥别名
密鑰的標識符。支援英文字母、數字、底線（_）、短劃線（-）和正斜線（/）。
描述信息
密鑰的說明資訊。
高级选项
密鑰材料來源。選擇外部（导入密钥材料）。
說明請仔細閱讀並選中我瞭解使用外部金鑰材料的方法和意義。
軟體密鑰
登入Key Management Service控制台，在頂部功能表列選擇地區後，在左側導覽列單擊资源 > 密钥管理。
在用户主密钥頁簽，实例ID選擇軟體密鑰管理執行個體，單擊创建密钥。
在创建密钥面板，完成配置項設定，然後單擊確定。
配置項
說明
密钥类型
選擇對稱金鑰。
重要如果您建立的密鑰用於加密憑據值，請選擇對稱金鑰。
密钥规格
對稱金鑰規格：Aliyun_AES_256
密钥用途
Encrypt/Decrypt：密鑰的用途，用於資料加密和解密。
密钥别名
密鑰的別名標識符。支援英文字母、數字、底線（_）、短劃線（-）和正斜線（/）。
標籤
密鑰的標籤，方便您對密鑰進行分類管理。每個標籤由一個索引值對（Key:Value）組成，包含標籤鍵（Key）、標籤值（Value）。
說明標籤鍵和標籤值的格式：最多支援128個字元，可以包含英文大小寫字母、數字、正斜線（/）、反斜線（\）、底線（_）、短劃線（-）、半形句號（.）、加號（+）、等號（=）、半形冒號（:）、字元at（@）、空格。
標籤鍵不能以aliyun或acs:開頭。
每個密鑰最多可以設定20個標籤索引值對。
描述信息
密鑰的說明資訊。
高级选项
策略配置：詳細資料，請參見密鑰策略概述。
密钥材料来源：選擇外部（导入密钥材料）。
說明請仔細閱讀並選中我瞭解使用外部金鑰材料的方法和意義。
硬體密鑰
登入Key Management Service控制台，在頂部功能表列選擇地區後，在左側導覽列單擊资源 > 密钥管理。
在用户主密钥頁簽，实例ID選擇硬體密鑰管理執行個體，單擊创建密钥。
在创建密钥面板，完成配置項設定，然後單擊確定。
配置項
說明
密钥类型
選擇對稱金鑰。
重要如果您建立的密鑰用於加密憑據值，請選擇對稱金鑰。
密钥规格
對稱金鑰規格：Aliyun_AES_256、Aliyun_AES_192、Aliyun_AES_128、
密钥用途
密鑰的用途。取值：
Encrypt/Decrypt：資料加密和解密。
Sign/Verify：產生和驗證數位簽章。
密钥别名
密鑰的別名標識符。支援英文字母、數字、底線（_）、短劃線（-）和正斜線（/）。
標籤
密鑰的標籤，方便您對密鑰進行分類管理。每個標籤由一個索引值對（Key:Value）組成，包含標籤鍵（Key）、標籤值（Value）。
說明標籤鍵和標籤值的格式：最多支援128個字元，可以包含英文大小寫字母、數字、正斜線（/）、反斜線（\）、底線（_）、短劃線（-）、半形句號（.）、加號（+）、等號（=）、半形冒號（:）、字元at（@）、空格。
標籤鍵不能以aliyun或acs:開頭。
每個密鑰最多可以設定20個標籤索引值對。
描述信息
密鑰的說明資訊。
高级选项
策略配置：詳細資料，請參見密鑰策略概述。
密钥材料来源：選擇外部（导入密钥材料）。
說明請仔細閱讀並選中我瞭解使用外部金鑰材料的方法和意義。
建立完成後，密鑰狀態為待导入。
步驟二：下載封裝公開金鑰和匯入令牌
匯入密鑰材料的參數包含封裝公開金鑰和匯入令牌，封裝公開金鑰用於加密金鑰材料，在匯入處理程序中保護您的密鑰材料，匯入令牌用於匯入密鑰材料。
定位到目標密鑰，單擊操作列的详情，在密钥材料地區，單擊获取导入参数。
在获取导入密钥材料的参数對話方塊，選擇公钥类型和加密算法，單擊下一步。
密鑰管理類型
封裝公開金鑰類型
密碼編譯演算法
預設密鑰（主要金鑰）
RSA_2048
RSAES_OAEP_SHA_1
RSAES_OAEP_SHA_256
RSAES_PKCS1_V1_5（不推薦）
軟體密鑰
RSA_2048
RSAES_OAEP_SHA_256
RSAES_PKCS1_V1_5（不推薦）
硬體密鑰
RSA_2048
RSAES_OAEP_SHA_256
RSAES_PKCS1_V1_5（不推薦）
重要RSAES_PKCS1_V1_5：美國國家標準與技術研究院（National Institute of Standards and Technology，NIST）關於密碼演算法和密鑰長度的使用指導規範Transitioning the Use of Cryptographic Algorithms and Key Lengths中已明確表示2023年12月31日後應停止使用該密碼編譯演算法用於加密傳輸密鑰。
RSAES_OAEP_SHA_1：RSA加密，按照RFC 3447/PKCS#1中定義的RSAES-OAEP模式，使用MGF1和SHA-1。
RSAES_OAEP_SHA_256：RSA加密，按照RFC 3447/PKCS#1中定義的RSAES-OAEP模式，使用MGF1和SHA-256。
下載封裝公開金鑰以及匯入令牌，並妥善儲存。
公钥格式：
pem格式：下載後檔案名稱預設為publickey_******.pem。
der格式：下載後檔案名稱預設為publickey_******.bin。
导入令牌：下載後檔案名稱預設為token_******.txt。
重要匯入令牌的有效期間為24小時，在有效期間內可以重複使用，失效後需要擷取新的匯入令牌和公開金鑰。
封裝公開金鑰和匯入令牌必須配套使用。即不允許下載兩次封裝公開金鑰和匯入令牌，使用其中一個的封裝公開金鑰，另一個的匯入令牌。
步驟三：使用封裝公開金鑰加密密鑰材料
使用步驟二：下載封裝公開金鑰和匯入令牌下載的封裝公開金鑰和指定的封裝演算法，對密鑰材料進行加密。
下面以使用OpenSSL產生密鑰材料，並通過RSA公開金鑰、RSAES_OAEP_SHA_256演算法加密金鑰材料為例。
使用OpenSSL產生一個32位元組的隨機數，產生一個密鑰材料。如果您已有密鑰材料，請跳過本步驟。
openssl rand -out KeyMaterial.bin 32根據指定的密碼編譯演算法加密金鑰材料。
openssl pkeyutl -encrypt -in KeyMaterial.bin -inkey PublicKey.bin -keyform DER -pubin -out EncryptedKeyMaterial.bin -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256說明範例程式碼中密碼編譯演算法使用RSAES_OAEP_SHA_256。
範例程式碼以公開金鑰格式為der格式為例，如果您下載公開金鑰檔案時選擇了pem格式，需要將範例程式碼中的
-keyform DER替換為-keyform PEM。請將PublicKey.bin替換為步驟二：下載封裝公開金鑰和匯入令牌中下載的公開金鑰檔案名稱。
將加密後的密鑰材料進行Base64編碼，儲存為文字檔。
openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt說明EncryptedKeyMaterial_base64.txt即為可匯入KMS的密鑰材料檔案。
步驟四：匯入密鑰材料
在密鑰詳情頁面，單擊导入密钥材料，在导入打包后的密钥材料對話方塊，完成各項配置後，單擊確定。
配置項 | 說明 |
导入打包后的密钥材料 | 上傳步驟三：使用封裝公開金鑰加密密鑰材料中產生的密鑰材料檔案。 |
导入令牌 | 上傳步驟二：下載封裝公開金鑰和匯入令牌中下載的令牌檔案。 |
密钥材料过期时间 | 支援選擇永不过期，也可以自訂到期時間。 重要 如果設定了密鑰材料到期時間，在設定的時間點之後KMS會刪除已到期的密鑰材料，您將無法使用該密鑰材料。如需恢複使用，可以為密鑰再次匯入相同的密鑰材料。 |
匯入密鑰材料成功後，密鑰狀態從待导入更新為启用中。
常見問題
是否支援刪除密鑰材料？
支援刪除。
匯入的密鑰材料到期或者被刪除後，其密鑰將無法使用，需要再次匯入相同的密鑰材料才可正常使用。
直接刪除密鑰材料
控制台：在密鑰詳情頁的密钥材料地區，單擊删除密钥材料。
API介面：調用DeleteKeyMaterial介面刪除，該操作不會刪除您的密鑰。
到期後由KMS刪除
在匯入密鑰材料時設定到期時間，在時間點之後KMS會刪除已到期的密鑰材料。
如何重新匯入相同的密鑰材料？
密鑰材料到期或刪除後，您可以再次匯入相同的密鑰材料，密鑰才可繼續使用。
刪除到期的密鑰材料。
在密鑰詳情頁，單擊密钥材料頁簽，單擊删除密钥材料。
重新下載封裝公開金鑰和匯入令牌。具體操作，請參見步驟二：下載封裝公開金鑰和匯入令牌。
說明密鑰封裝過程不會影響密鑰材料的內容，因此，您可以使用不同的封裝公開金鑰和不同的封裝演算法來匯入相同的密鑰材料。
使用封裝公開金鑰加密密鑰材料。具體操作，請參見步驟三：使用封裝公開金鑰加密密鑰材料。
說明密鑰材料必須與之前到期的密鑰材料為同一個。
使用匯入令牌，匯入加密後的密鑰材料。具體操作，請參見步驟四：匯入密鑰材料。
如何判斷密鑰材料是由外部匯入還是由KMS產生？
方式一：在Key Management Service控制台查看。
預設密鑰：在密钥管理頁面，單擊默认密钥頁簽，定位到目標密鑰，單擊操作列的详情，在詳情頁面查看密钥材料来源。
軟體密鑰、硬體密鑰：在密钥管理頁面，單擊用户主密钥頁簽，選擇实例ID後定位到目標密鑰，單擊操作列的详情，在詳情頁面查看密钥材料来源。
方式二：通過調用DescribeKey介面查看。
如果
Origin值為EXTERNAL，說明密鑰材料由外部匯入。如果Origin值為Aliyun_KMS，說明密鑰材料由KMS產生。
如何輪轉使用外部金鑰材料的密鑰？
對匯入外部金鑰材料的密鑰，KMS不提供定期自動輪轉功能。如果您需要輪轉，只能建立一個新的密鑰然後匯入新的密鑰材料。