IBM Cloud Docs
使用 PKCS #11 API 执行加密操作

使用 PKCS #11 API 执行加密操作

IBM Cloud® Hyper Protect Crypto Services 提供了用于访问 Hyper Protect Crypto Services 云 HSM 以执行加密操作的标准 PKCS #11 API。

先决条件

在可以设置和使用 PKCS #11 API 之前，请先遵循 设置 PKCS #11 用户类型的最佳实践，以便为各种 PKCS #11 用户类型创建不同的服务标识 API 密钥。

步骤 1: 设置 PKCS #11 库

您需要在工作站上设置 PKCS #11 库，以使其可供应用程序调用标准 PKCS #11 函数。

对于 amd64 和 s390x 平台，仅在 Linux上支持 PKCS #11 库。

如果要在 IBM Z (s390x) 平台上使用 SunPKCS11 提供程序运行 Java PKCS #11 应用程序，请确保使用最新的 IBM Semeru JVM，并在启动应用程序时指定 -Xjit:noResumableTrapHandler Java 选项。 您可以通过在 IBM Semeru Runtime Downloads 页面上将 Architecture 过滤器字段更改为 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.

    如果使用已认证的密钥库，那么必须对这两个密钥库启用 sessionauth 配置选项，并且对于 tokenspaceIDPassword 字段中的两个密钥库，长度为 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 端点。 您可以通过 概述 > 连接 > EP11 端点 URL 在 UI 中进行获取，也可以使用 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 位 通用唯一标识(UUID)。 您可以使用第三方工具 (例如， UUID generator) 生成 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 位 通用唯一标识(UUID)。 您可以使用第三方工具 (例如， UUID generator) 生成 UUID。

    Hyper Protect Crypto Services 为您提供了两个数据库支持的 EP11 密钥库，用于增强安全性和更好的用户访问管理: 只有普通用户类型才能访问的专用密钥库以及所有用户类型都可以访问的公用密钥库。 UUID 必须与为 private_keystore_spaceid 参数指定的 UUID 不同。

    要点: UUID 字符串值必须与用于为匿名用户设置访问策略的 UUID 字符串匹配。 请参阅 匿名用户访问策略创建。
    apikey_for_anonymous_user 您在 先前的先决条件步骤 中为匿名用户类型创建的服务标识 API 密钥。
    logging_level 受支持的日志记录级别，按详细程度递增: 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 参考。

根据应用程序的功能部件和安全性需求，传递您在 先前的先决条件步骤 中创建的不同服务标识 API 密钥，以便应用程序可以执行相应的操作。 例如，如果应用程序需要删除密钥库，请提供 SO 用户 API 密钥。 如果应用程序需要访问专用密钥库以存储新密钥，那么需要提供正常用户 API 密钥。 有关 PKCS #11 API 的用户访问权管理的更多信息，请参阅 设置 PKCS #11 用户类型的最佳实践。

如果要在 IBM Z (s390x) 平台上使用 SunPKCS11 提供程序运行 Java PKCS #11 应用程序，请确保使用最新的 IBM Semeru JVM，并在启动应用程序时指定 -Xjit:noResumableTrapHandler Java 选项。 您可以通过在 IBM Semeru Runtime Downloads 页面上将 Architecture 过滤器字段更改为 s390x 来下载 IBM Semeru JVM 的最新 s390x 版本。

下一步