pkcs11-toolによるPKCS#11。#

このガイドは、NetHSMのPKCS#11ドライバの使用方法について説明しています。このガイドでは、`OpenSC<https://github.com/OpenSC/OpenSC>`__のツールを使用しています。お使いのオペレーティングシステムでの使用方法については、それぞれのドキュメントを参照してください。

重要

このドライバは、まだ初期の概念実証の実装であり、TLSサーバーの運用に必要な機能のみを実装しています。

インストール#

プリコンパイルされたライブラリのインストール#

リポジトリの`リリースページ<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ から、最新のリリースを含むアーカイブをダウンロードします。タイトルにあなたのオペレーティングシステムの名前が含まれているリリースアーカイブを使用してください。
ダウンロードしたアーカイブから、お好みのアーカイビングプログラムでファイルを展開する。
解凍したライブラリを、お使いのOSのそれぞれのパスにコピーします。パスは、OpenSCのインストールや設定によって異なります。

ソースコードからのコンパイル#

重要

本ドライバは、公式Goコンパイラでのみコンパイル可能です。GNU Goコンパイラ(GCC-Go)は使用しないでください。<https://go.dev/doc/install>`インストール方法については、彼らのウェブサイト`__を参照してください。

リポジトリの`リリースページ<https://github.com/Nitrokey/nethsm-pkcs11/releases>`__ から最新のリリースを含むアーカイブをダウンロードします。タイトルに Source code が含まれるリリースアーカイブを使用してください。
ダウンロードしたアーカイブから、お好みのアーカイビングプログラムでファイルを展開する。
解凍したソースコードのあるディレクトリで、以下のコマンドを実行し、ライブラリをコンパイルします。
./build.sh
./build.sh
解凍したライブラリを、お使いのOSのそれぞれのパスにコピーします。パスは、OpenSCのインストールや設定によって異なります。

構成#

設定ファイル p11nethsm.conf が必要で、PKCS#11ドライバとNetHSM間の接続を設定するために使用します。

設定ファイルの例は次のようになります。

YAML 1.1
---
p11nethsm:
  logfile: /tmp/p11nethsm.log
  maxsessioncount: 5
  debug: true
  slots:
  - label: NetHSM1
    description: NetHSM Zone A
    url: "https://nethsmdemo.nitrokey.com/api/v1"
    # certSHA256:
    #   - "0C:66:DC:EB:4D:12:C3:24:FC:82:F4:1D:4C:16:44:12:1D:00:79:FF:36:96:65:E2:21:C4:36:94:F7:8E:22:89"
    user: "operator"
    password: "env:NETHSM_PASS"

環境に応じて設定ファイル p11nethsm.conf を変更します。

設定ファイルには複数のスロットを含めることができ、slot`配列の中に記述します。スロットは複数のNetHSMのデプロイメントを表します。スロットの `label フィールドには、一意の名前を指定する必要があります。url`, user, password の各キーは必須です。セキュリティ上の理由から、パスワードは環境変数で渡すことが推奨されます。この場合、 env:NETHSM_PASS が password キーに渡され、 NETHSM_PASS はパスワードを含む環境変数の名前になります。TLS 証明書がオペレーティングシステムの証明書ストアに含まれる認証局 (CA) によって署名されていない場合、 certSHA256 キーが設定される必要があります。

設定ファイルは、以下のパス、またはアプリケーションを実行するディレクトリに保存する必要があります。

$HOME/.nitrokey。
/etc/nitrokey/ です。

キーマネージメント#

情報#

cryptokiのバージョン、およびPKCS#11ドライバの情報を表示します。

$ pkcs11-tool --module p11nethsm.so --show-info

Cryptoki version 2.40
Manufacturer     Nitrokey GmbH
Library          NetHSM PKCS#11 module (ver 0.1)
Using slot 0 with a present token (0x0)

スロット一覧#

利用可能なスロットの情報です。リストされるスロットは`p11nethsm.conf` 設定ファイルにあるスロットアレイの設定に依存します。スロットの設定についてより詳しく知るには、`設定<pkcs11_with_pkcs11-tool.html#configuration>`_ の章を参照してください。

$ pkcs11-tool --module p11nethsm.so --list-slots

Available slots:
Slot 0 (0x0): NetHSM Zone A
  token label        : NetHSM1
  token manufacturer : Nitrokey GmbH
  token model        : NetHSM
  token flags        : rng, token initialized, PIN initialized, readonly
  hardware version   : 0.1
  firmware version   : 0.1
  serial num         : 0
  pin min/max        : 3/256

注釈

もし、あなたの設定が複数のスロットをサポートしているなら、正しいスロットを使うために pkcs11-tool のコマンドに --slot <arg> オプションを追加しなければならないかもしれません。

鍵の生成#

キーペアを生成し、NetHSMに保存します。

注釈

PKCS#11 ドライバは、現在この機能をサポートしていません。鍵ペアは、nitropy または REST API リクエストで生成することができます。鍵の生成方法の詳細については、`鍵の生成<../operation.html#generate-key>`_ の章を参照してください。

リストキー#

NetHSM の*Key Store* にあるキーと証明書に関する情報を表示します。

$ pkcs11-tool --module p11nethsm.so --list-objects

Using slot 0 with a present token (0x0)
Private Key Object; RSA
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      decrypt, sign
  Access:     sensitive, always sensitive, never extractable
Public Key Object; RSA 0 bits
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      none
  Access:     none

リードキー#

NetHSM上の*Key Store* 、鍵や証明書を読み取ることができます。NetHSMから秘密鍵を読み取ることはできません。

鍵ペアの公開鍵は、以下のように読み取ることができる。

$ pkcs11-tool --module p11nethsm.so --read-object --type pubkey --label myFirstKey -o public.key

鍵ペアの証明書は、以下のように読み取ることができます。

$ pkcs11-tool --module p11nethsm.so --read-object --type cert --label myFirstKey -o public.key

返される証明書または公開鍵は、ASN.1 エンコードされています。DER形式のデータが含まれているため、dumpasn1 ツールでデコードすることができます。DER形式は、OpenSSLでPEM形式に変換することができます。

書き込みキー#

NetHSM上の*Key Store* 、鍵や証明書を書き込む。

鍵ペアの秘密鍵は、次のように書くことができる。

$ pkcs11-tool --module p11nethsm.so --write-object secret.key --type privkey --label myFirstKey

鍵ペアの公開鍵は、以下のように書くことができる。

$ pkcs11-tool --module p11nethsm.so --write-object public.key --type pubkey --label myFirstKey

鍵ペアの証明書は、次のように書くことができる。

$ pkcs11-tool --module p11nethsm.so --write-object cert.pub --type cert --label myFirstKey

主要業務#

エンクリプト#

NetHSMは非対称鍵でデータを暗号化することはできませんが、暗号化に使用できる公開鍵は提供されます。公開鍵の取得方法については、Show Key Details<operation.html#show-key-details>`__の章を参照するか、`Read Keys <pkcs11_with_pkcs11.html#read-keys> の章にあるように鍵を取得するようにしてください。この例では、公開鍵が public.pem ファイルに格納されていると仮定しています。

データはOpenSSLで以下のように暗号化することができます。

$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin \
   -inkey public.pem \
   -pkeyopt rsa_padding_mode:oaep \
   -pkeyopt rsa_oaep_md:sha512 \
   -pkeyopt rsa_mgf1_md:sha512 \
   -out encrypted.data

デクリプト#

NetHSMは、NetHSM上の*Key Store* に保存されている秘密鍵のデータを復号化することができます。この例では、前の章`Encrypt<pkcs11_with_pkcs11-tool.html#encrypt>`__ の暗号化されたメッセージを使用します。

$ pkcs11-tool --module p11nethsm.so --decrypt \
   --mechanism RSA-PKCS-OAEP \
   --input-file encrypted.data \
   --label myFirstKey \
   --hash-algorithm SHA512

NetHSM rulez!

サイン#

NetHSMは、NetHSM上の*Key Store*に保存されている秘密鍵のデータに署名することができます。RSAおよびECDSAの鍵による署名の場合、最初にダイジェストを計算する必要があります。

ダイジェストを計算するためには、まずデータが必要です。メッセージは以下のように作成されます。

$ echo 'NetHSM rulez!' | pkcs11-tool --module p11nethsm.so \
   --sign \
   --mechanism SHA512-RSA-PKCS-PSS \
   --output-file sig.data \
   --label myFirstKey

作成された署名は、OpenSSLで以下のように検証することができます。

$ echo 'NetHSM rulez!' | openssl dgst -keyform PEM \
   -verify public.pem \
   -sha512 \
   -sigopt rsa_padding_mode:pss \
   -sigopt rsa_pss_saltlen:-1 \
   -signature sig.data