透過建立實體、憑證和主金鑰來初始化專用 Key Protect

為了讓專用 Key Protect 運作，您必須先使用 提供一個實例，然後使用 產生管理憑證 來操作您的加密單元，再使用 建立並載入主密鑰，允許 Key Protect 代表您對加密單元執行加密作業。

如需專屬 Key Protect 服務關鍵概念的詳細資訊，請查看 關於標準和專屬 Key Protect。

本主題將介紹每種指令的三種不同版本：適用於 Mac/ Linux、Windows Powershell 或 Windows 指令提示 (CMD)。 請確定您使用的指令與您的系統相符。

開始之前

如果您沒有最新版本的 IBM Cloud CLI，您可能無法初始化您的實體。 更新至最新版本的 CLI 外掛程式，以確保初始化成功。

您必須使用最新版本的 CLI 來完成初始化，即使您使用主控台部署您的實例。 如果您在安裝最新版本的 KP CLI 外掛程式時，收到 - Unable to obtain plug-in's metadata 錯誤，請參閱 疑難排解步驟。

在主控台中配置您的實例

若要在主控台中佈建您的實體，請遵循 此處的 指示，並在目錄中選擇「專用」磁磚。 配置過程可能需要幾分鐘。

一旦您的實例完成佈建，您就可以 產生管理憑證並領取您的加密單位。

如果您未指定加密單元的數量，您的實體將配置兩個加密單元。 您也可以使用下拉選項指定三個加密單位。 無論您指定兩個或三個加密單位，請注意此值之後不能變更。

在 CLI 中配置您的實例

在建立加密單位和初始化您的實體之前，必須先建立您的實體。 首先，透過發出設定資源群組的目標：

ibmcloud target -c <resource-group>

如果您不知道您的資源群組，您可以透過簽發來找出您有哪些資源群組：

ibmcloud resource groups

設定好資源群組後，發出指令建立實體：

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south

其中：

  • <INSTANCE_NAME> 是您賦予實體的名稱。

請注意，此指令預設為兩個 crypto 單元。 您可以透過發出指定三個加密單位：

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south -p '{"crypto_units": 3}'

如果您指定的加密單位數量不是 2 或 3，則會傳回錯誤。 之後您就無法變更加密單位的數量。

配置專用實例可能需要幾分鐘。 您可以發出指令檢查您的實例的狀態：

ibmcloud resource service-instance <INSTANCE_NAME>

其中：

  • <INSTANCE_NAME> 是您在上一步中為您的實體所取的名稱。

該實例可以有兩種狀態，活動中或進行中。 請注意，活動中的實例尚未初始化，因為初始化需要完成本主題的其餘步驟。 在您初始化您的實體之前，它無法使用，因為您的身分尚未與您的加密單元設定，以建立主金鑰。

取得端點

當您的實例啟動後，請發出指令取得端點和 GUID：

ibmcloud resource service-instance <INSTANCE_NAME> -o json

其中：

  • <INSTANCE_NAME> 是您在上一步中為您的實體所取的名稱。

端點是上述 json 輸出 endpoints stanza 中的 public 參數值。 它的格式為 https://<instance-id>.api.<region>.kms.appdomain.cloud. GUID 是上述輸出中的 GUID 參數值。 它的格式為 UUID。

您可以透過下列指令取得端點：ibmcloud resource service-instance <\kp-instance-id\> --output json | jq -r '.[].extensions.endpoints'。

在三種支援的作業系統中的一種系統上發出兩個指令，將完整端點儲存為環境變數。

對於 macOS:

export KP_TARGET_ADDR=<ST_INSTANCE_ENDPOINT>

及：

export KP_INSTANCE_ID=<GUID>

適用於 Windows Powershell：

$Env:KP_INSTANCE_ID = <GUID>

及：

$Env:KP_TARGET_ADDR = <ST_INSTANCE_ENDPOINT>

適用於 Windows CMD：

set KP_INSTANCE_ID=<GUID>

及：

set KP_TARGET_ADDR=<ST_INSTANCE_ENDPOINT>

其中：

  • <ST_INSTANCE_ENDPOINT> 是您的實例的完整端點，格式為 https://<instance-id>.api.<region>.kms.appdomain.cloud。
  • <GUID> 是上述輸出的實體 ID。

現在您已準備好產生管理憑證。

您可能需要在佈建後等待幾分鐘，才能使用您的加密單位。

有關加密單位可能處於的狀態的詳細資訊，請參閱 加密單位狀態。

產生管理員憑證和認領您的加密單位

加密單元由一個或多個管理員管理，這表示您需要有可用的身分或建立身分。 如果您有正確格式化的管理員身分 (使用 RSA-2048 的 256 位元 AES 對稱金鑰)，您可以跳到 建立主金鑰。

產生管理員憑證

如果您需要建立管理員憑證，請發出：

ibmcloud kp crypto-unit sig-key generate --file <ADMIN_KEY_FILE> --passphrase <PWD> --algo RSA-2048

其中：

  • <ADMIN_KEY_FILE> 是您電腦上建立身分的位置 (例如 admin-keyfile.key)。
  • <PWD> 是一個可選的密碼或口令，用於加密靜態檔案。 指定"-"，系統會提示您輸入密碼。

保存此密鑰檔案的副本，並記住密碼。 在與加密單元互動時，所有經過驗證的指令都需要使用它。

如果任何 ibmcloud kp crypto-unit 命令返回錯誤代碼 e00bad05，請參閱 疑難排解步驟。

申領您的加密單位

有關加密單位可能處於的狀態的詳細資訊，請參閱 加密單位狀態。

指派給使用者的 Crypto 單元會從 清除狀態 開始。 同一服務實例中的所有加密單元都必須採用相同的設定。 如果您的實例所在區域中有一個可用性區域無法存取，則可交替使用運作中的加密單元，以達到負載平衡或高可用性。

單一服務實例中所有加密單元的總鑰，必須設定為相同。 所有加密單元都必須新增同一組管理員，且所有加密單元必須同時進行初始化。

若要顯示目前使用者帳戶下目標資源群組中的服務實體和密碼單位，請使用下列指令：

ibmcloud kp crypto-units

以下是顯示的輸出範例。 輸出資料表中的「ID」欄位用於識別後續由 KP CLI 外掛程式發出的管理指令所針對的加密單位。

*******************************************************  
Id                                     InstanceID                             State  
6e0aead3-9d44-4c92-a4c4-f7a1ab415420   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
3bb363fc-b1f9-4237-b37b-2c9e07784e3c   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
*******************************************************

RSA 金鑰對的公開金鑰會被放入一份憑證中，該憑證會安裝於目標加密單元內，用以指定加密單元管理員。 使用 claim 指令將其上載為您的加密單元的預設管理員，發行：

ibmcloud kp crypto-unit claim --credential <ADMIN_KEY_FILE>

其中：

  • <ADMIN_KEY_FILE> 是儲存身分的檔案。

所有 crypto-unit 指令都適用於所有加密單元。 它們實際上是彼此的複製品。

產生與匯入主密碼鑰匙

由於您匯入的是主密鑰憑證，因此 Key Protect 無法存取或備份該密鑰。 將您的主鑰匙記錄保存在安全的地方。

現在您已經建立了您的實例和管理員身分，您可以使用它們來建立您的主密碼鑰匙。 主金鑰也稱為 HSM 主金鑰，用於加密服務實體，以儲存金鑰。 它是 256 位元 AES 對稱金鑰。 透過主金鑰，您將取得雲端 HSM 的所有權，並擁有用於加密整個加密金鑰層級結構的信任根，其中包含金鑰管理金鑰庫中的根金鑰與標準金鑰。 一個服務實例只能有一個主要金鑰。 若您刪除服務實例的主金鑰，即可有效將所有使用該服務所管理金鑰進行加密的資料進行加密銷毀。

專用的 Key Protect 採用「密鑰分割」機制，即將加密金鑰分割成多個部分，以提升安全性。 至少必須建立 2 "keyshares"，不過也可以根據使用情況使用更多。

若要在本機生成主密鑰，請在三個支援的作業系統之一上發出指令。

對於 macOS:

ibmcloud kp crypto-unit master-key generate --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2>"]' --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSOWRD3>"}]'

適用於 Windows Powershell：

ibmcloud kp crypto-unit master-key generate --keyshare-files '["""<KEYSHARE_FILE_1>#<PASSWORD1>""","""<KEYSHARE_FILE_2>#<PASSWORD2>"""]' --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSOWRD3>"""}]'

適用於 Windows CMD：

ibmcloud kp crypto-unit master-key generate --keyshare-files"[\"<KEYSHARE_FILE_1>#<PASSWORD1>\", \"<KEYSHARE_FILE_2>#<PASSWORD2>\"]" --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSOWRD3>\"}]"

其中：

  • <KEYSHARE_FILE_1>#<PASSWORD1> 是其中一個 keyshares 的位置，以及所建立檔案的密碼。 密碼是必須輸入的，且必須介於 6-255 個字元之間。 省略 #<PASSWORD1>，系統會提示您輸入密碼。
  • <KEYSHARE_FILE_2>#<PASSWORD2> 是另一個 keyshare 的位置，以及所建立檔案的密碼。 密碼是必須輸入的，且必須介於 6-255 個字元之間。 省略 #<PASSWORD2>，系統會提示您輸入密碼。 省略 #<PASSWORD2>，系統會提示您輸入密碼。
  • <KEY_NAME> 是您的主金鑰的名稱。
  • <ADMIN_KEY_FILE>#<PASSOWRD3> 是您的管理員位置，以及您先前產生的密碼 (如果您沒有攜帶自己的身分)。 省略 #<PASSWORD3>，系統會提示您輸入密碼。

請注意 keyshare-minimum，預設值是 2，但可以增加，代表您必須指定的最小 keyhares 數目 (依據其位置)。

若要將主金鑰上傳到您實例的加密單元，請在三個支援的作業系統之一上發出指令。

對於 macOS:

ibmcloud kp crypto-unit master-key import --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2"]' --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD3>"}]'

適用於 Windows PowerShell:

ibmcloud kp crypto-unit master-key import --keyshare-files '["""<KEYSHARE_FILE_1>#<PASSWORD1>""","""<KEYSHARE_FILE_2>#<PASSWORD2>"""]' --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSWORD3>"""}]'

適用於 Windows CMD：

ibmcloud kp crypto-unit master-key import --keyshare-files "[\"<KEYSHARE_FILE_1>#<PASSWORD1>\", \"<KEYSHARE_FILE_2>#<PASSWORD2\"]" --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSWORD3>\"}]"

其中：

  • <KEYSHARE_FILE_1>#<PASSWORD1> 是其中一個 keyshares 的位置，以及將會建立的檔案的口令。 密碼是必須輸入的，且必須介於 6-255 個字元之間。 省略 #<PASSWORD1>，系統會提示您輸入密碼。
  • <KEYSHARE_FILE_2>#<PASSWORD2> 是另一個 keyshare 的位置，以及將會建立的檔案的密碼。 密碼是必須輸入的，且必須介於 6-255 個字元之間。 省略 #<PASSWORD2>，系統會提示您輸入密碼。
  • <ADMIN_KEY_FILE>#<PASSWORD3> 是您的管理員位置，以及您先前產生的密碼 (如果您沒有攜帶自己的身分)。 省略 #<PASSWORD3>，系統會提示您輸入密碼。

現在您的主金鑰已經建立，您需要允許 Key Protect 服務在您的加密單元上執行動作（例如，建立金鑰）。 請注意，授予「Key Protect」的權限等級低於管理員。 使用三種支援的作業系統之一發出指令。

對於 macOS:

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD>"}]'

適用於 Windows PowerShell:

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSWORD>"""}]'

適用於 Windows CMD：

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSWORD>\"}]"

其中：

  • <ADMIN_KEY_FILE>#<PASSWORD> 是管理員金鑰檔案的位置，以及先前產生的密碼 (如果您沒有自備身分)。 省略 #<PASSWORD>，系統會提示您輸入密碼。

此指令也可用於為您的加密裝置新增管理員，方法是製作您的 --type admin，並新增指向您擁有的管理員身分的 --name 和 --file。 加入 kmsCryptoUser 時，請勿加入 --name 或 --file。 例如：

ibmcloud kp crypto-unit user add --type admin --name <USERNAME> --credential "<USERNAME_KEY_FILE>" --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PWD>"}]'

其中：

  • <USERNAME> 是您要新增的管理員身分的名稱。
  • <USERNAME_KEY_FILE> 是要與新使用者關聯的憑證的檔案路徑。
  • <ADMIN_KEY_FILE>#<PWD> 是您現有管理員的位置，以及您先前產生的密碼 (如果您沒有自備身分)。 省略 #<PWD>，系統會提示您輸入密碼。

新增 kmsCryptoUser 為管理員時，請勿新增 --name 或 --file。

恭喜！ 您的實例已完全初始化。

您可能需要等待 5 至 10 分鐘，才能開始使用您的執行個體。

下一步

現在您的實體已經建立，您也擁有可以用來操作實體的管理員身分，並已建立主金鑰，以及賦予 Key Protect 在實體上執行動作的權限，您已準備好執行下列動作：

Key Protect Dedicated 不支援匯入代幣。

不支援的功能

  • 建立匯入代幣。
  • 使用匯入代碼 保護匯入金鑰。
  • allowed_network policy.
  • 將您的實例部署到 us-south 以外的任何地方。
  • PKCS#11 金鑰庫。
  • 故障移轉加密單元。

疑難排解

Unable to obtain plug-in's metadata 在安裝或升級 KP CLI 外掛程式時發生錯誤

如果您在安裝 IBM Key Protect CLI 外掛程式時收到下列錯誤：

Installing binary...
FAILED
Unable to obtain plug-in's metadata. Error: exit status 1

Linux 環境

使用 GLIBCXX 版本 3.4.26 或更新版本，從發行版的套件管理員安裝或更新 libstdc++ 系統函式庫。 使用下列安裝指令範例：

  • Ubuntu/Debian: apt-get update && apt-get install libstdc++6
  • RHEL/Fedora/CentOS: yum install libstdc++
  • Alpine: apk add --no-cache gcompat libstdc++

如果這樣仍無法解決錯誤，請聯絡 Key Protect 技術支援。

Windows 或 macOS 環境

請聯絡 Key Protect 支援。

command failed with error code: e00bad05 錯誤

如果 ibmcloud kp crypto-unit 命令返回以下錯誤：

FAILED
command failed with error code: e00bad05

此錯誤可能表示您的系統與 ibmcloud kp crypto-unit 功能不相容。 建議的系統需求為

  • Windows: AMD64 (Windows 10 或更新版本)
  • Linux: AMD64 (Debian, Ubuntu, Red Hat)
  • macOS: ARM64 (Apple Silicon)

此清單外的系統可能仍與 ibmcloud kp crypto-unit 功能相容。 如果您要確認與您特定系統的相容性，或如果 e00bad05 錯誤在符合建議的系統需求下仍然存在，請聯絡 Key Protect 支援。

HTTP 503 no healthy upstream 錯誤

如果對 Key Protect 作業 的呼叫返回 HTTP 503 並帶有訊息 no healthy upstream: no crypto units are in kms-initialized state at this time，可能有以下原因：

  • 您尚未完成 Dedicated 初始化步驟。
  • 您已完成專用初始化步驟，但需要等待幾分鐘讓 Key Protect 識別新的 kms-initialized 加密單元。
  • 您只有一個加密裝置處於 kms-initialized 狀態，且該加密裝置因維護而停機。
  • 您上傳了不匹配的主密鑰資料到一個或多個加密裝置。

context deadline exceeded 錯誤

如果 CLI 命令返回錯誤 context deadline exceeded (Client.Timeout exceeded while awaiting headers)，您從不符合專用端點要求的系統設定 KP_TARGET_ADDR 到專用端點。

要解決這個錯誤：

  • 使用「取得端點」步驟中的公開端點。
  • 如果您打算使用專用端點，請參閱 專用 端點，瞭解有關對專用端點進行呼叫的資訊。

加密單元指令無法套用至所有加密單元

如果 crypto-unit claim、crypto-unit master-key import 或 crypto-unit user add --type kmsCryptoUser 指令無法套用到所有加密單元，您可能會看到類似以下範例的輸出：

Executing operation Generate Master Key against CryptoUnit with ID fadedbee-0000-0000-0000-1234567890ab
OK
Executing operation Generate Master Key against CryptoUnit with ID addedace-0000-0000-0000-1234567890ab
FAILED

如需解決這個問題，請採取下列動作：

  1. 預設情況下，claim、master-key import 及 user add 指令會嘗試套用到所有加密單元。 如果這些命令只部分成功 (只套用到實例中的加密單位子集)，則只針對傳回失敗的加密單位重試該命令。 每項指令都可以設定為特定的加密單元。 若要確定如何針對特定的 crypto 單元，請在任何 crypto-unit 指令後加上 -h，以檢視說明文字，或參閱 CLI 參考資料。

  2. 執行 CLI 參考 中的 kp crypto-units 指令，確認所有 crypto 單元都處於相同狀態。

    • 如果加密單元狀態不匹配，請參閱 加密單元狀態。
    • 如果任何加密單元處於 maintenance 狀態，請稍後再重試 kp crypto-unit 指令。