使用關鍵遷移工具從 HPCS 遷移到 Key Protect Dedicated

金鑰遷移工具 (CRKM) 可協助 HPCS 使用者將客戶根憑證 (CRK) 遷移到 Key Protect Dedicated。本文件說明如何使用 CRKM 移轉您的金鑰和相關 IBM Cloud 資源。 CRKM 僅適用於 IBM Cloud 服務和 IBM 軟體使用的 CRK，這些服務和軟體參與了自動化遷移工作流程。如需詳細資訊，請參閱從 Hyper Protect Crypto Services(HPCS)遷移到 Key Protect Dedicated。

在本主題中，除非另有說明，否則「金鑰」是指客戶根金鑰 (CRK)。

下載工具

請針對 Key Protect 建立一則 IBM 支援單，以申請使用 HPCS 至 Key Protect 遷移工具的權限。
下載支援票據中提供的工具二進位。
驗證下載的二進位檔的 SHA-256 檢查和是否與支援票單中提供的值相符。直接比較數值；兩者必須完全符合。

針對您的作業系統執行適當的指令，以取得 SHA-256 檢查和，並與支援票單中提供的值進行比較：

macOS

shasum -a 256 <crkm-binary>

範例：

shasum -a 256 crkm-darwin-arm64-1.0.0

Linux

sha256sum <crkm-binary>

範例：

sha256sum crkm-linux-amd64-1.0.0

視窗 (指令提示)

certutil -hashfile <crkm-binary> SHA256

範例：

certutil -hashfile crkm-windows-amd64-1.0.0.exe SHA256

Windows ( PowerShell )

Get-FileHash <crkm-binary> -Algorithm SHA256

範例：

Get-FileHash crkm-windows-amd64-1.0.0.exe -Algorithm SHA256

製作可執行的二進位檔 ( macOS/Linux )：

chmod +x <crkm-binary>

瞭解移轉工具的輸出

CLI 工具中的 status、create 和 sync 操作會產生以下兩個檔案：
.csv 輸出檔
在作業完成後建立，其中 execution 包含檔案名稱、作業名稱和指令執行的日期時間。此檔案包含輸入資料的複本，並針對每一行：
- 在 HPCS 鑰匙上找到的關聯數字
- 在 Key Protect 專用鍵中找到的關聯數量
- HPCS 鑰匙的操作狀態
- HPCS 金鑰的狀態以及 Key Protect 專用金鑰（例如：Active (1) ）
.log 輸出檔

在作業完成後建立，其中 summary 包含檔案名稱、作業名稱和指令執行的日期時間。該檔案提供具有移轉意圖的鑰匙狀態及其關聯數目的概覽。
delete 操作僅會產生 execution .csv 這個檔案。
status 操作對於驗證輸入檔案格式是否正確非常有用，因為此指令不採取任何動作。您可以重複使用相同的輸入檔案，而不移除已完全轉換的鍵，因為狀態會顯示未執行操作的原因。

要使遷移成功，來源 HPCS 金鑰必須處於「Active」或「Deactivated」狀態（以便能夠解封裝資料），而目標 Key Protect 專用金鑰必須處於「Active」狀態（以便能夠封裝和解封裝資料）。如果某個金鑰處於任何其他狀態，該工具會將警告訊息輸出至控制台，因為遷移作業很可能失敗。

開始之前

請完成所有遷移先決條件，才能使用遷移工具。

設定 IAM 授權政策

請依照文件所述，設定從各項服務至 Key Protect Dedicated 的 IAM 授權政策。當您為 Hybrid HPCS 建立政策時，若文件中有此要求，請勾選「啟用由來源服務和依賴服務委派授權」核取方塊。

有關範例，請參閱：

ICD PostgreSQL: 授予服務授權
IKS：加密

建立目標鍵

在「Key Protect Dedicated」中建立將作為遷移目標的金鑰。

設定輸入檔案

CLI 將 .csv 檔案（不含標頭行）作為輸入。檔案中的每一行都包含

第一列：來源 HPCS 金鑰的 CRN (sourceCRK)
第二欄：目標 Key Protect 專用金鑰的 CRN（targetCRK ）

每一行皆指定您要遷移的雲端資源。遷移工具會使用「targetCRK」重新加密那些採用「sourceCRK」的資源。

輸入檔案範例

（下表顯示其結構。請勿在 CSV 檔案中包含標頭)

表 1. 輸入檔案格式範例
來源 HPCS Key CRN	Target Key Protect 專用金鑰 CRN
`crn:v1:bluemix:public:hs-crypto:eu-fr2:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:key:deadbeef-0000-0000-0000-1234567890ab`	`crn:v1:bluemix:public:kms:eu-fr2:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:key:deadbeef-0000-0000-0000-1234567890ab`
`crn:v1:bluemix:public:hs-crypto:eu-fr2:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:key:deadbeef-0000-0000-0000-1234567890ab`	`crn:v1:bluemix:public:kms:eu-fr2:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:key:deadbeef-0000-0000-0000-1234567890ab`
`crn:v1:bluemix:public:hs-crypto:eu-fr2:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:key:deadbeef-0000-0000-0000-1234567890ab`	`crn:v1:bluemix:public:kms:eu-fr2:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:key:deadbeef-0000-0000-0000-1234567890ab`

請勿在實際 CSV 檔案中包含標頭列。

設定遷移工具

在終端機執行下列指令：

export HPCS_API_ENDPOINT=<HPCS endpoint>
export KP_ST_API_ENDPOINT=<Key Protect Dedicated endpoint>
export IBMCLOUD_API_KEY=<IBM Cloud API key>
export IBMCLOUD_API_KEY_KP_ST=<IBM Cloud API key that can access Key Protect Dedicated instance>

HPCS_API_ENDPOINT 和 KP_ST_API_ENDPOINT 的範例：

export HPCS_API_ENDPOINT=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
export KP_ST_API_ENDPOINT=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.kms.appdomain.cloud

對於 status、create、sync 以及 delete 這些指令，請將 API 金鑰與具備以下服務存取角色的 IAM 身分進行關聯：

IBMCLOUD_API_KEY (HPCS): 需要「經理」服務存取角色。服務存取角色具有累積性，因此「管理員」包含「讀取者」和「寫入者」，涵蓋所有四項指令。之所以需要「管理員」角色，是因為「刪除」指令以及帶有 --replace-mi 選項的「建立」指令，會從來源金鑰中移除遷移意圖。
IBMCLOUD_API_KEY_KP_ST（ Key Protect 專用）: 需要「讀取者」服務存取角色。這些指令僅會讀取目標金鑰，因此使用 Reader 便已足夠。「刪除」指令不會存取「Key Protect Dedicated」。

「authz-check」指令所需的服务存取角色與其他指令不同。如需更多資訊，請參閱「檢查 IAM 授權政策」。

只有當 IBMCLOUD_API_KEY 無法存取目標 Key Protect 專用實例時，才需要設定 IBMCLOUD_API_KEY_KP_ST 變數。在下列情況下，此動作將會發生：

HPCS 執行個體與 Key Protect 專用執行個體位於不同的 IBM Cloud 帳戶中
來源與目標環境使用不同的 IAM 身分

可選的環境變數

可以設定下列可選的環境變數：

IAM_API_ENDPOINT: 如果未使用預設 https://iam.cloud.ibm.com/identity/token，則採用自訂 IAM 端點。
DEBUG_MODE: 接受 true 或 false。當設定為 true`` 時，此工具會產生詳細的日誌：包含啟動時的已解析配置，以及每次 API 呼叫的 HTTP 詳情（方法、包含查詢字串的路徑、回應狀態及關聯 ID）。對於失敗的請求，其回應正文也會被記錄下來。授權標頭和 API 金鑰絕不會被記錄。

驗證輸入檔案

使用 status 作業檢查遷移的狀態，並驗證您的輸入檔案格式是否正確。此指令不會執行任何移轉動作。

./<crkm-binary> status <.csv input file>

您可能會在輸出檔案 .csv 中所有關鍵輸入的狀態欄位，以及控制台日誌中，看到「FAILED - No Migration Intent that is found for the key」的訊息。當尚未建立移轉意向時，預計會出現這種情況。

檢查 IAM 授權政策

請使用 authz-check 指令，確認已設定 IAM 授權政策，以便目前使用 HPCS 來源金鑰的雲端服務，在遷移後能使用對應的 Key Protect 專用目標金鑰。

./<crkm-binary> authz-check <.csv input file>

必要的存取權

authz-check 指令僅用於讀取資訊。此操作不會建立、更新或刪除任何金鑰或原則，因此無需具備 Writer 或 Manager 的存取權限。

此指令需要以下存取權限：

HPCS 實例: Reader 服務存取角色，用以讀取來源金鑰的關聯資訊。
Key Protect 專用執行個體: Reader 服務存取角色，以便讀取目標金鑰的元資料。
IAM 授權政策: 帳戶層級的權限，可檢視「TargetCRK」欄位中所引用的每個帳戶的 IAM 授權政策。這並非「Key Protect」或「HPCS」服務存取角色。這是對 IBM Cloud Identity and Access Management 的帳戶層級存取權限。

用於 IAM 政策查詢的身分，是與 IBMCLOUD_API_KEY_KP_ST 相關聯的那個。若未設定 IBMCLOUD_API_KEY_KP_ST，則會使用與 IBMCLOUD_API_KEY 關聯的身分。

若該身分無法檢視目標帳戶中的政策，該工具會記錄此失敗狀況並繼續執行。它將該帳戶中的每個關聯都顯示為「NO MATCH」。 IAM 存取權限不足的情況，會以「NO MATCH」結果顯示為「false」，而非授權錯誤。在依據輸出結果之前，請先驗證此存取權限。

指令分兩個階段運作：

第 1 階段：擷取政策

該工具會從 CSV 中的 TargetCRK 欄中擷取不同的帳號 ID，取得每個帳號的所有 IAM 授權政策，並將其寫入 JSON 檔案 (policies-{serviceName}-{accountID}.json) 以供參考。

第二階段：匹配協會

對於 CSV 中的每一行，工具會擷取來源 HPCS 金鑰上的所有關聯 (由該金鑰加密的雲端資源)。此工具會檢查是否存在 IAM 授權政策，允許每個相關服務使用目標的 Key Protect 專用金鑰。

該工具還會透過 IBM Cloud 資源控制器 API，查詢每個目標 Key Protect 專用執行個體的資源群組。此查詢功能可讓工具比對範圍限定於資源群組的政策。

對於每個關聯，該工具都會報告：

MATCH: 找到有效的授權政策。會列印政策 JSON。
NO MATCH: 未找到授權政策。該工具會顯示一則訊息，說明缺少哪些內容，並提供一個符合該匹配條件的政策之彩色 JSON 範本。在範本中，必填欄位顯示為綠色，可選欄位顯示為藍色。

最後會列印摘要，顯示已檢查、匹配和未匹配關聯的總數。

授權檢查標誌

--match-all-authz-policies: 預設情況下，工具會停在每個關聯的第一個匹配原則。使用此旗標記錄所有匹配的原則。

比對準則

當以下條件皆成立時，授權政策即與某個關聯相符：

該政策的對象（即獲授權者）包含與相關雲端服務相符的 serviceName 及 accountId。
該政策的資源（即被存取的對象）包含一個 serviceName 和 accountId，這兩者與目標 Key Protect 專用金鑰的服務相符。
政策的角色授予適當的存取權 (Reader, ReaderPlus, Writer, 或 Manager)。
如果相關服務需要 (例如 databases-for-*, messages-for-rabbitmq, containers-kubernetes)，政策也會包含 AuthorizationDelegator 角色。

若政策指定了可選屬性（例如 resourceGroupId、serviceInstance、keyRing 或 resource ），則這些屬性也必須與目標金鑰或其 Key Protect 專用實例相符。

建立移轉意向

在建立包含 HPCS 金鑰配對的 .csv 檔案，以便將其遷移至各自的 Key Protect 專用金鑰後，請使用 create 操作在 HPCS 金鑰上建立遷移意向。

./<crkm-binary> create <.csv input file>

此操作會執行以下動作：

觸發同步事件至有關聯的服務（使用正在遷移的金鑰的雲端資源），以便它們可以開始遷移 HPCS 金鑰
您必須在活動追蹤日誌中監控事件確認與遷移狀況（請參閱「未及時完成的遷移」以進行疑難排解）

如果某個金鑰上已存在遷移意圖，且您希望使用更新後的 .csv 輸入檔來更新該意圖，請使用 --replace-mi 標誌執行 CLI 工具。

若在建立遷移意圖時遇到任何問題，請參閱「疑難排解」章節。

同步按鍵

上一步完成五分鐘後，使用 sync 作業：

./<crkm-binary> sync <.csv input file>

此操作會觸發同步事件到有關聯的服務 (使用遷移中金鑰的雲端資源)。此步驟可確保即使對於間接使用 HPCS 金鑰的服務，也能進行遷移。例如，ICD 使用 IBM Cloud Object Storage 來儲存備份，而 IBM Cloud Object Storage 則使用 Key Protect。

請等待至少五分鐘，然後查看遷移狀態。採用 HPCS 的服務單位負責進行遷移作業，其回應 HPCS 的時間上限為四小時。對於 Event Streams，在您建立遷移意圖後，遷移過程可能需要長達一個工作天。

檢查移轉狀態

使用 status 作業檢查遷移的狀態：

./<crkm-binary> status <.csv input file>

如果 HPCS 鑰匙的關聯數在遷移開始時不是零，並且下降到零，則遷移完成。

若您發現「狀態」欄位中出現問題，或 HPCS 關聯數（KpStAssociationsCount ）仍不為零，請參閱疑難排解。

刪除遷移意圖

使用「delete」操作，從一個或多個 HPCS 金鑰中移除遷移意圖。例如，可在遷移開始前，使用此操作來撤銷一個因目標金鑰設定錯誤而建立的遷移意圖。對於每個金鑰，該工具會檢查是否存在遷移意圖。若存在該項目，此工具會列印遷移意圖的屬性（ID、來源 CRK、目標 CRK、建立者及建立日期），然後將其刪除。若不存在遷移意圖，該工具會回報「未找到任何遷移意圖」。

與其他操作不同，delete 操作可接受「.csv」輸入檔案，或單一 HPCS 金鑰 CRN。

若要刪除 .csv 檔案中每個 HPCS 金鑰的遷移意圖，請使用以下指令：

./<crkm-binary> delete <.csv input file>

若要透過傳入其完整的 CRN 來刪除單一 HPCS 金鑰的遷移意圖，請使用以下指令：

./<crkm-binary> delete <HPCS key CRN>

範例：

./<crkm-binary> delete crn:v1:bluemix:public:hs-crypto:eu-fr2:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:key:deadbeef-0000-0000-0000-1234567890ab

delete 操作僅對來源 HPCS 金鑰生效。因此，僅需設定 HPCS_API_ENDPOINT 和 IBMCLOUD_API_KEY 這兩項環境變數。 Key Protect 無需指定專用變數。

delete 操作會立即移除遷移意圖，且不會要求確認。當您傳入一個 .csv 檔案時，該檔案中每個金鑰的遷移意圖都會被刪除。

疑難排解

使用以下資訊排除移轉工具的常見問題。

未及時完成遷移

有時，服務在遷移金鑰的過程中可能會遇到問題。

使用 sync 作業，以 .csv 檔案作為輸入，通知與金鑰有關聯的服務再次嘗試遷移：

./<crkm-binary> sync <.csv input file>

如果 HPCS 金鑰的關聯數在遷移開始時不是零，也沒有降為零，服務可能在遷移金鑰時遇到問題。另外，也可能存在陳舊的聯想。請針對 Key Protect 建立一則 IBM 支援單，並在單中提及「從 HPCS 遷移至 Key Protect」一事。

無效的資源 CRN 格式

錯誤訊息：

invalid key crn for key : crn must be specified to 10 segments

CSV 的狀態欄位輸出內容亦顯示：FAILED - crn must be specified to 10 segments

請檢視輸入檔案 .csv，並確保 HPCS 金鑰及 Key Protect 專用金鑰的 CRN 格式正確。

找不到金鑰

錯誤訊息：

2023/03/29 09:23:39 Sleeping for 100ms before processing row 5
2023/03/29 09:23:39 Retrieving Key...
2023/03/29 09:23:39 Get Key failed for keyID d4c4cbee-20ed-4deb-b59d-4674f70713b5 with the following error: kp.Error: correlation_id='643a49af-a3cc-4eba-b23b-368bbc33115d', msg='Not Found: Key could not be retrieved: Please see `reasons` for more details (KEY_NOT_FOUND_ERR)', reasons='[KEY_NOT_FOUND_ERR: key does not exist - FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'
2023/03/29 09:23:39 -----------------------------------------------

CSV 狀態列輸出也讀取：

FAILED - kp.Error: correlation_id='643a49af-a3cc-4eba-b23b-368bbc33115d', msg='Not Found: Key could not be retrieved: Please see `reasons` for more details (KEY_NOT_FOUND_ERR)', reasons='[KEY_NOT_FOUND_ERR: key does not exist - FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'

金鑰的 CRN 不存在。請檢視輸入檔案 .csv，並確認待遷移的 HPCS 金鑰以及 Key Protect 專用目標金鑰均已存在。

Instance 不存在或使用者未經授權

錯誤訊息：

2023/03/29 09:26:44 Retrieving Key...
2023/03/29 09:26:44 Get Key failed for keyID d4c4cbee-20ed-4deb-b59d-4674f70713b5 with the following error: kp.Error: correlation_id='4629f1af-1a9b-44ea-9139-3c5c39b9790e', msg='Unauthorized: Either the user does not have access to the specified resource, the resource does not exist, or the region is incorrectly set'
2023/03/29 09:26:44 -----------------------------------------------

CSV 狀態列輸出也讀取：

FAILED - kp.Error: correlation_id='4629f1af-1a9b-44ea-9139-3c5c39b9790e', msg='Unauthorized: Either the user does not have access to the specified resource, the resource does not exist, or the region is incorrectly set'

使用者無法存取金鑰，或該金鑰在 CRN 中的實例不存在。

建立指令：未找到關聯

錯誤訊息：

2023/03/22 10:39:36 Retrieving Key...
2023/03/22 10:39:36 Key retrieved successfully
2023/03/22 10:39:36 Retrieving associations...
2023/03/22 10:39:36 Associations retrieved successfully
2023/03/22 10:39:36 Retrieving Migration Intent...
2023/03/22 10:39:36 Migration Intent retrieved successfully
2023/03/22 10:39:36 No associations found for the key
2023/03/22 10:39:36 -----------------------------------------------

CSV 的狀態欄位輸出內容亦顯示：FAILED - No associations were found for the key

HPCS 金鑰沒有任何與其相關的雲端資源。因此，您不需要在 HPCS 金鑰上建立遷移意向或執行遷移。

建立指令：存在遷移意圖

錯誤訊息：

2023/03/22 10:39:35 Retrieving Key...
2023/03/22 10:39:35 Key retrieved successfully
2023/03/22 10:39:35 Retrieving associations...
2023/03/22 10:39:35 Associations retrieved successfully
2023/03/22 10:39:35 Retrieving Migration Intent...
2023/03/22 10:39:35 Migration Intent retrieved successfully
2023/03/22 10:39:35 Migration Intent already exists
2023/03/22 10:39:35 -----------------------------------------------

CSV 的狀態欄位輸出內容亦顯示：FAILED - Migration Intent exists for the key

HPCS 金鑰已經有一個現有的移轉意向。若要更新遷移意圖，請完成以下步驟：

請更新輸入檔案 .csv ，並將其中的 Key Protect 專用金鑰更新為要遷移至的目標金鑰的新 CRN。
在 create 指令中加入 --replace-mi 標誌。
請重新執行該指令。

狀態指令：未找到移轉意圖

錯誤訊息：

2023/03/22 13:15:56 Retrieving Key...
2023/03/22 13:15:56 Key retrieved successfully
2023/03/22 13:15:56 Retrieving associations...
2023/03/22 13:15:56 Associations retrieved successfully
2023/03/22 13:15:56 Retrieving Migration Intent...
2023/03/22 13:15:56 No Migration Intent found for keyID a2cd689e-9a49-4cd7-ba0d-07d25a0b3a25
2023/03/22 13:15:56 -----------------------------------------------

CSV 的狀態欄位輸出內容亦顯示：FAILED - No Migration Intent found for the key

該 HPCS 金鑰不存在移轉意向。請重新嘗試建立遷移意圖，以確保輸入檔案中包含關鍵資源的 CRN，並檢查該操作的狀態。

同步指令：未找到關聯

錯誤訊息：

2023/03/22 13:13:45 Retrieving Key...
2023/03/22 13:13:45 Key retrieved successfully
2023/03/22 13:13:45 Retrieving associations...
2023/03/22 13:13:45 Associations retrieved successfully
2023/03/22 13:13:45 Retrieving Migration Intent...
2023/03/22 13:13:45 Migration Intent retrieved successfully
2023/03/22 13:13:45 No associations found for keyID d4c3cbee-20ed-4deb-b59d-4674f70713b5
2023/03/22 13:13:45 -----------------------------------------------

CSV 的狀態欄位輸出內容亦顯示：FAILED - No associations were found for the key

HPCS 金鑰沒有任何與其相關的雲端資源。因此，您不需要執行資源同步。這也表示金鑰的遷移已經完成。

同步指令：未找到移轉意圖

錯誤訊息：

2023/03/22 13:15:13 Retrieving Key...
2023/03/22 13:15:13 Key retrieved successfully
2023/03/22 13:15:13 Retrieving associations...
2023/03/22 13:15:13 Associations retrieved successfully
2023/03/22 13:15:13 Retrieving Migration Intent...
2023/03/22 13:15:13 Migration Intent retrieved successfully
2023/03/22 13:15:13 No Migration Intent found for keyID a2cd689e-9a49-4cd7-ba0d-07d25a0b3a25
2023/03/22 13:15:13 -----------------------------------------------

CSV 的狀態欄位輸出內容亦顯示：FAILED - No Migration Intent found for the key

該金鑰不存在移轉意向。重試建立移轉意向，確保輸入檔案中包含關鍵資源 CRN，並檢查作業狀態。

同步指令：要求太早

錯誤訊息：

2023/03/29 09:17:06 Sleeping for 100ms before processing row 2
2023/03/29 09:17:06 Retrieving Key...
2023/03/29 09:17:06 Key retrieved successfully
2023/03/29 09:17:06 Retrieving associations...
2023/03/29 09:17:06 Associations retrieved successfully
2023/03/29 09:17:06 Retrieving Migration Intent...
2023/03/29 09:17:06 Migration Intent retrieved successfully
2023/03/29 09:17:06 Post Sync Resources for key...
2023/03/29 09:17:06 Post Sync Call Failed: kp.Error: correlation_id='8f088c29-2f61-4dc4-b00f-c99f7edd00fe', msg='Conflict: Could not initiate sync requests to associated resources: Please see `reasons` for more details (REQ_TOO_EARLY_ERR)', reasons='[REQ_TOO_EARLY_ERR: The key was updated recently: Please wait and try again: Sync cannot be performed until at least 2023-03-29T14:17:19Z - FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'
2023/03/29 09:17:06 -----------------------------------------------

CSV 狀態列輸出也讀取：

FAILED - kp.Error: correlation_id='0cefcea8-7e29-4c4a-9721-00244eb9752c', msg='Conflict: Could not initiate sync requests to associated resources: Please see `reasons` for more details (REQ_TOO_EARLY_ERR)', reasons='[REQ_TOO_EARLY_ERR: The key was updated recently: Please wait and try again: Sync cannot be performed until at least 2023-03-29T14:17:19Z - FOR_MORE_INFO_REFER: https://cloud.ibm.com/apidocs/key-protect]'

sync 操作執行得太快。請等待至少五分鐘，然後再試一次。