PKCS#11 トークンを使い始めるには、秘密鍵、PIN、トークンラベルで初期化します。手順はハードウェアごとに異なるため、ベンダーの指示に従ってください。あわせて module（共有オブジェクトファイル .so）のパスも確認します。デバイスを初期化したあと、次のコマンドでトークンラベルを確認できます。
pkcs11-tool --module <module path> --list-token-slotsインポート（または生成）した秘密鍵のラベルも確認します。次のコマンドを実行し、Private Key Object を探します。
pkcs11-tool --module <module path> --pin <pin> \
--list-token-slots --login --list-objectsこれで、Keyless サーバーで PKCS#11 トークンを使うために必要な情報が揃います。設定ファイルの private_key_stores セクションに追加します。Keyless に公開したい鍵ペアは、PKCS#11 URI ↗ 形式で設定ファイルに指定できます。
PKCS#11 URI は、セミコロンで区切った属性と値の組を 1 階層のパスに並べ、必要に応じてクエリを続けたものです。一般形は次のとおりです。
pkcs11:path-component[?query-component]URI のパス部分はリソースを識別する属性を持ちます。クエリ部分には、パスで識別したリソースを取得するために必要な属性を置けます。パスの属性は ; で区切り、クエリの属性は & で区切ります。属性はすべて URL エンコードします。
Keyless では、次の 3 属性が必須です。
- Module: PKCS#11 モジュールライブラリの場所は
module-pathで指定します。 - Token: PKCS#11 トークンは
serial、slot-id、またはtokenで指定します。 - Slot: PKCS#11 鍵ペアは
idまたはobjectで指定します。
モジュールによっては、開きすぎを防ぐためにクエリ属性 max-sessions が必要です。状況によっては pin-value などの追加属性も必要になります。詳細は PKCS#11 モジュールのドキュメントを参照してください。
各種モジュール上の鍵を指す PKCS#11 URI の例です。
private_key_stores:
- uri: pkcs11:token=SoftHSM2%20RSA%20Token;id=%03?module-path=/usr/lib64/libsofthsm2.so&pin-value=1234
- uri: pkcs11:token=accelerator;object=thaleskey?module-path=/opt/nfast/toolkits/pkcs11/libcknfast.so
- uri: pkcs11:token=YubiKey%20PIV;id=%00?module-path=/usr/lib64/libykcs11.so&pin-value=123456&max-sessions=1
- uri: pkcs11:token=elab2parN;id=%04?module-path=/usr/lib/libCryptoki2_64.so&pin-value=crypto1現時点では、同時に使える PKCS#11 モジュールは 1 つだけです。複数の HSM に鍵がある場合は、p11-glue で 1 つのモジュールにアクセスをまとめる ↗ ことを推奨します。