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 のさまざまなユーザー・タイプごとに異なるサービス ID の API キーを作成しておく必要があります。

ステップ 1: PKCS #11 ライブラリーをセットアップする

ワークステーションに PKCS #11 ライブラリーをセットアップして、アプリケーションからの標準 PKCS #11 関数の呼び出しに使用できるようにする必要があります。

PKCS #11 ライブラリー ( amd64 プラットフォームと s390x プラットフォームの両方) は、 Linuxでのみサポートされます。

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>
    

    platformamd64 または s390x に置き換え、version はライブラリーの 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 OKsigning_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 構成オプションを有効にする必要があります。また、長さが 6 文字から 8 文字のテキスト・パスワードは、 tokenspaceIDPassword フィールド内の両方の鍵ストアで同一でなければなりません。

    次の表に従って、例内の変数を置き換えてください。

    特定の地域で 2024 年 4 月 12 日より後にインスタンスを作成する場合、 <instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud という新しい形式で新しい API エンドポイントを使用する必要が生じることがあります。 利用可能日は地域によって異なります。 サポートされる地域、可用性の日付、および新規エンドポイント URL について詳しくは、 新規エンドポイント を参照してください。

    表 1. PKCS #11 構成ファイルの作成に必要な変数について説明します。
    変数 説明
    EP11_endpoint_URL Hyper Protect Crypto Services の Enterprise PKCS #11 (EP11) の API エンドポイント。 UI の 「概要」 > 「接続」 > EP11 エンドポイント URL から取得することも、API を使用して動的に エンドポイント URL を取得 することもできます。 パブリック・ネットワークかプライベート・ネットワークのどちらを使用しているかによって、パブリックかプライベートのいずれかの EP11 エンドポイント URL を使用します。
    EP11_endpoint_port_number EP11 API エンドポイントのポート番号。 これは、エンドポイント URL 内のコロンの後にあります。
    enable_mtls 有効な値は、 Hyper Protect Crypto Services 標準プランの PKCS #11 API アクセスの認証の第 2 層を追加するために相互 TLS を有効にするかどうかを示す true または false です。 EP11 ではサーバーのみの認証が必要であるため、デフォルトでは false に設定されます。 相互 TLS 接続について詳しくは、EP11 接続の認証の第 2 層の有効化を参照してください。
    client_certificate 相互 TLS 接続を有効にする場合は、証明書管理者がインスタンスにアップロードしたクライアント証明書のファイル・パスを指定します。 有効にしない場合、このフィールドは空のままにします。
    client_certificate_private_key 相互 TLS 接続を有効にする場合は、証明書の署名に使用されるクライアント証明書の秘密鍵のファイル・パスを指定します。 有効にしない場合、このフィールドは空のままにします。
    SO_user_name セキュリティー・オフィサー (SO) のユーザー・タイプの名前。 PKCS #11 標準では、セキュリティー・オフィサー (SO) と一般ユーザーという 2 つのタイプのログイン・ユーザーが規定されています。 PKCS #11 ユーザー・タイプについて詳しくは、PKCS #11 Cryptographic Token Interface Usage Guide バージョン 2.40 - ユーザーを参照してください。
    normal_user_name 一般ユーザー・タイプの名前。 PKCS #11 標準では、セキュリティー・オフィサー (SO) と一般ユーザーという 2 つのタイプのログイン・ユーザーが規定されています。 PKCS #11 ユーザー・タイプについて詳しくは、PKCS #11 Cryptographic Token Interface Usage Guide バージョン 2.40 - ユーザーを参照してください。
    private_keystore_spaceid プライベート・キー・ストアの 128 ビットの Universally Unique IDentifier (UUID)UUID generator などのサード・パーティー・ツールを使用して UUID を生成できます。

    Hyper Protect Crypto Services は、セキュリティーを強化してユーザー・アクセス管理を向上させるための 2 つのデータベース・ベースの EP11 鍵ストアを提供します。通常のユーザー・タイプのみがアクセスできる秘密鍵ストアと、すべてのユーザー・タイプがアクセスできる公開鍵ストアです。 UUID は、 public_keystore_spaceid パラメーターに指定された UUID とは異なるものでなければなりません。

    private_keystore_password sessionauth 構成オプションを有効にすると、許可セッションを使用できます。 sessionauth オプションを有効にする場合は、両方の鍵ストアに対して有効にする必要があります。 さらに、 tokenspaceIDPassword フィールドには 6 文字から 8 文字の長さのテキスト・パスワードが必要であり、パスワードは両方の鍵ストアで同一でなければなりません。 許可セッションは HSM に固有のものであり、PKCS#11 フローでログインとログアウトのために使用されます。認証される鍵操作には、許可セッションが必要です。 許可セッションを使用して生成されたすべての鍵は、認証と暗号化が行われる鍵ストアに保管されます。 tokenspaceIDPassword フィールドは、認証と暗号化が行われる鍵ストア内の鍵を保護するために使用されます。 サービス・インスタンスごとに、最大 5 つの鍵ストアの認証がサポートされます。
    anonymous_user_name 匿名ユーザーの名前。 PKCS #11 標準では、セキュリティー・オフィサー (SO) と一般ユーザーという 2 つのタイプのログイン・ユーザーが規定されています。 Cryptoki の関数 C_Login を使用してログインしないユーザーは、匿名ユーザーと呼ばれます。 PKCS #11 ユーザー・タイプについて詳しくは、PKCS #11 Cryptographic Token Interface Usage Guide バージョン 2.40 - ユーザーを参照してください。
    public_keystore_spaceid パブリック・キー・ストアの 128 ビットの Universally Unique IDentifier (UUID)UUID generator などのサード・パーティー・ツールを使用して UUID を生成できます。

    Hyper Protect Crypto Services は、セキュリティーを強化してユーザー・アクセス管理を向上させるための 2 つのデータベース・ベースの EP11 鍵ストアを提供します。通常のユーザー・タイプのみがアクセスできる秘密鍵ストアと、すべてのユーザー・タイプがアクセスできる公開鍵ストアです。 UUID は、 private_keystore_spaceid パラメーターに指定された UUID とは異なるものでなければなりません。

    重要: UUID ストリング値は、匿名ユーザーのアクセス・ポリシーをセットアップするために使用される UUID ストリングと一致している必要があります。 匿名ユーザー・アクセス・ポリシーの作成 を参照してください。

    apikey_for_anonymous_user 上記の前提条件の手順で、匿名ユーザー・タイプ用に作成したサービス ID の API キー。
    logging_level サポートされるロギング・レベル (詳細度が高くなる順): panicfatalerrorwarning/warninfodebugtrace。 デフォルト値は warning です。
    log_file_path ロギング・ファイルの絶対パス。 アプリケーションが PKCS #11 関数を実行するために Hyper Protect Crypto Services のクラウド HSM と対話したときに生成されたすべてのログが保存されます。

    PKCS #11 で使用される鍵ストアの暗号化と認証を行うには、sessionauth パラメーターを有効にし、鍵ストアのパスワードを構成します。 サービス・インスタンスごとに、最大 5 つの鍵ストアの認証がサポートされます。 パスワードの長さは 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 Runtime Downloads ページ「Architecture」 フィルター・フィールドを s390x に変更することにより、 IBM Semeru JVM の最新バージョンである s390x をダウンロードできます。

次の作業