必要條件

在設定及使用 PKCS #11 API 之前，請先遵循 設定 PKCS #11 使用者類型的最佳作法，為各種 PKCS #11 使用者類型建立不同的服務 ID API 金鑰。

步驟 1: 設定 PKCS #11 程式庫

您需要在工作站上設定 PKCS #11 程式庫，讓應用程式可以呼叫標準 PKCS #11 函數。

僅在 Linux上支援 amd64 及 s390x 平台的 PKCS #11 程式庫。

如果您在 IBM Z (s390x) 平台上使用 SunPKCS11 提供者執行 Java PKCS #11 應用程式，請確定您使用最新的 IBM Semeru JVM，並在啟動應用程式時指定 -Xjit:noResumableTrapHandler Java 選項。 您可以在 IBM Semeru 執行時期下載頁面」上，將 架構 過濾器欄位變更為 s390x，以下載 IBM Semeru JVM 的最新 s390x 版本。

1. 下載最新 PKCS #11 程式庫。 程式庫檔案名稱使用命名慣例: pkcs11-grep11-<platform>.so.<version>。 平台是 amd64 或 s390x，版本是標準 major.minor.build 語法。
2. 將檔案庫移至應用程式可存取的資料夾。 例如，如果您在 Linux上執行應用程式，則可以將程式庫移至 /usr/local/lib、/usr/local/lib64 或 /usr/lib。

步驟 2: (選用) 驗證 PKCS #11 程式庫的完整性和確實性

為了達到最高安全，請先驗證 PKCS #11 程式庫的完整性和確實性，然後再執行 PKCS #11 應用程式來使用程式庫。

Hyper Protect Crypto Services 會啟用 簽署的程式碼驗證，以確保簽章符合原始程式碼。 如果下載的 PKCS #11 程式庫檔案已變更或毀損，則會產生不同的簽章，且驗證失敗。 若要確保檔案在下載處理程序期間未遭竄改或毀損，請使用 OpenSSL 指令行工具完成下列步驟。

1. 將下列檔案的最新版本從 程式庫儲存庫 下載至您儲存 PKCS #11 程式庫的相同目錄:

   • pkcs11-grep11-<platform>.so.<version>.sig:PKCS #11 程式庫的已簽署加密雜湊，其中平台是 amd64 或 s390x，版本是簽章檔案的 major.minor.build。 平台 和 版本 都必須符合您使用之 PKCS #11 程式庫的個別 平台 和 版本。

   • signing_cert.pem: Hyper Protect Crypto Services PKCS #11 用戶端檔案的簽署憑證。

   • digicert_cert.pem: 中間程式碼簽署憑證，用來證明 Hyper Protect Crypto Services PKCS #11 用戶端檔案的簽署憑證。

2. 使用下列指令，將公開金鑰從簽署憑證 signing_cert.pem 擷取至 sigkey.pub 檔案:

   openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub
   

3. 使用下列指令驗證 PKCS #11 程式庫檔案的完整性:

   openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>
   

   將 平台 取代為 amd64 或 s390x，並將 版本 取代為程式庫的 major.minor.build。

   當驗證成功時，會顯示 Verified OK。

4. 使用下列指令來驗證簽署憑證的確實性和有效性:

   openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest
   

   當驗證成功時，Response verify OK 和 signing_cert.pem: good 會顯示在輸出中。

5. 如果驗證失敗，請取消安裝，並 聯絡 IBM 以取得支援。

步驟 3: 設定 PKCS #11 配置檔

若要將 PKCS #11 程式庫連接至 Hyper Protect Crypto Services 雲端 HSM 以執行加密功能，您需要完成下列步驟來設定配置檔。

1. 根據下列範例，建立名為 grep11client.yaml 的配置檔。 程式庫儲存庫 也提供可供您調整的範本。 您可以參閱程式碼中的註解，以瞭解每一個欄位。

   iamcredentialtemplate: &defaultiamcredential
     enabled: true
     endpoint: "https://iam.cloud.ibm.com"
   
   sessionauthtemplate: &defaultsessionauth
     enabled: false
     tokenspaceIDPassword:  # Authenticated keystore password 6-8 characters in length
   
   tokens:
     0:
       grep11connection:
         # The EP11 endpoint address starting from 'ep11'. For example: "<instance_ID>.ep11.us-south.hs-crypto.appdomain.cloud"
         address: "<EP11_endpoint_URL>"
         port: "<EP11_endpoint_port_number>" # The EP11 endpoint port number
         tls:
           enabled: true # EP11 requires TLS connection.
           # Set it 'true' if you want to enable mutual TLS connections.
           # By default, set it 'false' because EP11 requires server-only authentication.
           mutual: <enable_mtls>
           # 'cacert' is a full-path certificate file. In Linux with the 'ca-ca-certificates' package installed, this is normally not needed.
           cacert:
           # Specify the file path of the client certificate if you enable mutual TLS. Otherwise, keep it empty.
           certfile: <client_certificate>
           # Specify the file path of the client certificate private key if you enable mutual TLS. Otherwise, keep it empty.
           keyfile: <client_certificate_private_key>
       storage:
           # 'remotestore' needs to be enabled if you want to generate keys with the attribute CKA_TOKEN.
         remotestore:
           enabled: true
       users:
         0: # The index of the Security Officer (SO) user MUST be 0.
           # The name for the Security Officer (SO) user. For example: "Administrator".
           name: "<SO_user_name>"
           iamauth: *defaultiamcredential
         1: # The index of the normal user MUST be 1.
           # The name for the normal user. For example: "Normal user".
           name: "<normal_user_name>"
           # The 128-bit UUID of the private keystore. For example: "f00db2f1-4421-4032-a505-465bedfa845b".
           tokenspaceID: "<private_keystore_spaceid>"
           iamauth: *defaultiamcredential
           # Do not override the defaultsessionauth template
           # The same values must be used for both the private (normal user) and public (anonymous) keystores
           sessionauth: *defaultsessionauth
         2: # The index of the anonymous user MUST be 2.
           # The name for the anonymous user. For example: "Anonymous".
           name: "<anonymous_user_name>"
           # The 128-bit UUID of the public keystore. For example: "ca22be26-b798-4fdf-8c83-3e3a492dc215".
           tokenspaceID: "<public_keystore_spaceid>"
           iamauth:
             <<: *defaultiamcredential
             # The API key for the anonymous user. All other users can specify API key using the C_Login command.
             apikey: "<apikey_for_anonymous_user>"
           # Do not override the defaultsessionauth template
           # The same values must be used for both the private (normal user) and public (anonymous) keystores
           sessionauth: *defaultsessionauth
   
   logging:
     # Set the logging level.
     # The supported levels, in an increasing order of verboseness: 'panic', 'fatal', 'error', 'warning'/'warn', 'info', 'debug', 'trace'. The Default value is 'warning'.
     loglevel: "<logging_level>"
     logpath: "<log_file_path>" # The full path of your logging file.
   
   

   如果使用已鑑別的金鑰儲存庫，則必須在 tokenspaceIDPassword 欄位中針對兩個金鑰儲存庫啟用 sessionauth 配置選項，且長度為 6-8 個字元的文字密碼必須相同。

   根據下表替換範例中的變數：

   如果您在 2024 年 4 月 12 日之後在某些區域建立實例，您可能需要使用新格式的新 API 終端節點：<instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud。 可用日期因地區而異。 有關支援的區域、可用日期和新端點 URL 的更多信息，請參閱 新端點。

   表 1. 說明建立 PKCS #11 配置檔所需的變數

   變數	說明
   EP11_endpoint_URL	Hyper Protect Crypto Services Enterprise PKCS #11 (EP11) API 端點。 您可以透過使用者介面中的 概觀 > Connect > EP11 端點 URL 來取得它，也可以使用 API 來動態 擷取端點 URL。 視您使用公用或 專用網路 而定，請使用公用或專用 EP11 端點 URL。
   EP11_endpoint_port_number	EP11 API 端點的埠號。 它位於端點 URL 中的冒號之後。
   enable_mtls	有效值為 true 或 false，指出您是否要啟用相互 TLS，以針對 Hyper Protect Crypto Services 標準方案的 PKCS #11 API 存取新增第二層鑑別。 依預設，將它設為 false，因為 EP11 需要僅限伺服器鑑別。 如需相互 TLS 連線的相關資訊，請參閱 啟用 EP11 連線的第二層鑑別。
   client_certificate	如果您啟用相互 TLS 連線，請指定憑證管理者上傳至實例之用戶端憑證的檔案路徑。 否則，請將此欄位保留空白。
   client_certificate_private_key	如果您啟用相互 TLS 連線，請指定用來簽署憑證之用戶端憑證私密金鑰的檔案路徑。 否則，請將此欄位保留空白。
   SO_user_name	「安全主管 (SO)」使用者類型的名稱。 PKCS #11 標準定義兩種登入使用者類型: 安全主管 (SO) 和一般使用者。 如需 PKCS #11 使用者類型的相關資訊，請參閱 PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40-Users。
   normal_user_name	一般使用者類型的名稱。 PKCS #11 標準定義兩種登入使用者類型: 安全主管 (SO) 和一般使用者。 如需 PKCS #11 使用者類型的相關資訊，請參閱 PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40-Users。
   private_keystore_spaceid	專用金鑰儲存庫的 128 位元 通用唯一 ID(UUID)。 您可以使用協力廠商工具 (例如 UUID 產生器) 來產生 UUID。 Hyper Protect Crypto Services 為您提供兩個資料庫支援的 EP11 金鑰儲存庫，以加強安全並提供更好的使用者存取管理: 只有一般使用者類型才能存取的專用金鑰儲存庫，以及所有使用者類型都可以存取的公開金鑰儲存庫。 UUID 必須不同於指定給 public_keystore_spaceid 參數的 UUID。
   private_keystore_password	啟用 sessionauth 配置選項即可使用授權階段作業。 如果已啟用 sessionauth 選項，則必須針對這兩個金鑰儲存庫啟用它。 此外，tokenspaceIDPassword 欄位需要長度為 6-8 個字元的文字密碼，且兩個金鑰儲存庫的密碼必須相同。 授權階段作業是 HSM 特有的階段作業，在 PKCS #11 流程中用於登入及登出，且鑑別金鑰作業需要這些階段作業。 使用授權階段作業產生的所有金鑰都儲存在已鑑別及已加密的金鑰儲存庫中。 tokenspaceIDPassword 欄位用來保護已鑑別及已加密金鑰儲存庫中的金鑰。 對於每一個服務實例，最多支援五個已鑑別的金鑰儲存庫。
   anonymous_user_name	匿名使用者的名稱。 PKCS #11 標準定義兩種登入使用者類型: 安全主管 (SO) 和一般使用者。 如果使用者未使用 C_Login Cryptoki 函數登入，則該使用者稱為匿名使用者。 如需 PKCS #11 使用者類型的相關資訊，請參閱 PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40-Users。
   public_keystore_spaceid	公用金鑰儲存庫的 128 位元 通用唯一 ID(UUID)。 您可以使用協力廠商工具 (例如 UUID 產生器) 來產生 UUID。 Hyper Protect Crypto Services 為您提供兩個資料庫支援的 EP11 金鑰儲存庫，以加強安全並提供更好的使用者存取管理: 只有一般使用者類型才能存取的專用金鑰儲存庫，以及所有使用者類型都可以存取的公開金鑰儲存庫。 UUID 必須不同於指定給 private_keystore_spaceid 參數的 UUID。 重要事項: UUID 字串值必須符合用來為匿名使用者設定存取原則的 UUID 字串。 請參閱 建立匿名使用者存取原則。
   apikey_for_anonymous_user	您在 前一個必要條件步驟 中為匿名使用者類型建立的服務 ID API 金鑰。
   logging_level	支援的記載層次，以遞增的 Verboseness 順序: panic、fatal、error、warning/warn、info、debug 及 trace。 預設值為 warning。
   log_file_path	記載檔的完整路徑。 它會儲存應用程式與 Hyper Protect Crypto Services 雲端 HSM 互動時所產生的所有日誌，以執行 PKCS #11 功能。

   若要加密並鑑別 PKCS #11所使用的金鑰儲存庫，請啟用 sessionauth 參數，並配置金鑰儲存庫的密碼。 對於每一個服務實例，最多支援五個已鑑別的金鑰儲存庫。 密碼可以是 6-8 個字元。 金鑰儲存庫密碼不會儲存在服務實例中。 作為金鑰儲存庫管理者，您負責維護密碼的本端副本。 如果遺失密碼，您需要聯絡「IBM 支援中心」來重設金鑰儲存庫，這表示會清除金鑰儲存庫中的所有資料。

2. 將配置檔移至 /etc/ep11client 目錄。 創建 /etc/ep11client 目錄（如果不存在）。 或者，您可以將環境變數 EP11CLIENT_CFG 設為配置檔的完整路徑及檔名。 這樣做不會限制您只能使用 yaml 檔案的 grep11client 名稱。 範例： export EP11CLIENT_CFG=/home/user/pkcs11-config.yaml

步驟 4: 使用 PKCS #11 程式庫進行 PKCS #11 API 呼叫

在設定磁帶庫及配置檔之後，必須起始設定金鑰儲存庫。 若要起始設定金鑰儲存庫，安全主管 (SO) 使用者需要執行 C_InitToken 作業。

起始設定金鑰儲存庫之後，請使用 PKCS #11 程式庫來呼叫標準 PKCS #11 函數，以產生、儲存及列出金鑰。 如需受支援 PKCS #11 函數的詳細清單，請參閱 PKCS #11 API 參考資料。

視應用程式的特性及安全需求而定，傳遞您在 前一個必要條件步驟 中建立的不同服務 ID API 金鑰，以便應用程式可以執行對應的作業。 例如，如果您的應用程式需要刪除金鑰儲存庫，請提供 SO 使用者 API 金鑰。 如果您的應用程式需要存取私密金鑰儲存庫以儲存新金鑰，則需要提供一般使用者 API 金鑰。 如需 PKCS #11 API 使用者存取權管理的相關資訊，請參閱 設定 PKCS #11 使用者類型的最佳作法。

如果您在 IBM Z (s390x) 平台上使用 SunPKCS11 提供者執行 Java PKCS #11 應用程式，請確定您使用最新的 IBM Semeru JVM，並在啟動應用程式時指定 -Xjit:noResumableTrapHandler Java 選項。 您可以在 IBM Semeru 執行時期下載頁面」上，將 架構 過濾器欄位變更為 s390x，以下載 IBM Semeru JVM 的最新 s390x 版本。

下一步

• 請參閱指導教學，其中顯示如何 使用 Hyper Protect Crypto Services PKCS #11 程式庫進行 Oracle Database Transparent Database Encryption，以更充分地瞭解 PKCS #11 程式庫使用情形。
• 如需加密函數的詳細資訊，請參閱 PKCS #11 API 參考資料。