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