Openloop PIV/PKCS#11

使い方ガイド — pkcs11-tool, SSH, Firefox

概要

OpenloopはPIV（Personal Identity Verification, NIST SP 800-73）スマートカードインターフェースを実装しています。 PKCS#11共有ライブラリ（libopenloop-pkcs11）はOpenloop Connectに同梱されており、 SSH認証、TLSクライアント証明書、その他のPKCS#11対応アプリケーションで利用できます。

前提条件: Openloop Connectが起動している必要があります。PKCS#11ライブラリは ConnectのWebSocketリレー（localhost:21320）を介してデバイスと通信します。

ライブラリパス

PKCS#11ライブラリはOpenloop Connectに同梱されています。パスはOSによって異なります。

OS	パス
macOS	`/Applications/Openloop Connect.app/Contents/Resources/pkcs11/libopenloop-pkcs11.dylib`
Windows	`C:\Program Files\Openloop Connect\resources\pkcs11\libopenloop-pkcs11.dll`
Linux	`/opt/Openloop Connect/resources/pkcs11/libopenloop-pkcs11.so`

以下の例ではシェル変数を使用します:

# macOS
MODULE="/Applications/Openloop Connect.app/Contents/Resources/pkcs11/libopenloop-pkcs11.dylib"

pkcs11-tool

OpenSCのコマンドラインツール。brew install opensc 等でインストールできます。

スロット・トークン一覧

pkcs11-tool --module "$MODULE" -T

オブジェクト一覧

pkcs11-tool --module "$MODULE" -O

鍵ペア生成

# P-256 をスロット 9A（Authentication）に生成
pkcs11-tool --module "$MODULE" --keypairgen \
  --key-type EC:prime256v1 \
  --id 01 --label "PIV AUTH"

# Ed25519 をスロット 9A に生成
pkcs11-tool --module "$MODULE" --keypairgen \
  --key-type EC:edwards25519 \
  --id 01 --label "PIV AUTH"

署名テスト

# テストデータを作成し、スロット 9A の鍵で署名
echo "test data" | openssl dgst -sha256 -binary > /tmp/hash.bin
pkcs11-tool --module "$MODULE" --sign \
  --mechanism ECDSA \
  --id 01 \
  --input-file /tmp/hash.bin \
  --output-file /tmp/sig.bin

鍵の削除

pkcs11-tool --module "$MODULE" --delete-object \
  --type privkey --id 01

SSH認証

OpenloopをPKCS#11経由でSSHハードウェアキーとして使用します。

公開鍵の取得

# デバイスからSSH公開鍵を取得
ssh-keygen -D "$MODULE"

# ファイルに保存してサーバーの ~/.ssh/authorized_keys に追加
ssh-keygen -D "$MODULE" >> ~/.ssh/authorized_keys

単発の認証

ssh -I "$MODULE" user@hostname

永続的な設定（~/.ssh/config）

# ~/.ssh/config に追加して自動的にPKCS#11を使用
Host myserver
    HostName 192.168.1.100
    User ubuntu
    PKCS11Provider /Applications/Openloop Connect.app/Contents/Resources/pkcs11/libopenloop-pkcs11.dylib

# または全ホストに適用:
Host *
    PKCS11Provider /Applications/Openloop Connect.app/Contents/Resources/pkcs11/libopenloop-pkcs11.dylib

macOS: システムSSHではなくHomebrew版OpenSSH（brew install openssh）を使用してください。 macOSのシステムSSHはPKCS#11を正しくサポートしない場合があります。/opt/homebrew/bin/ssh を使用してください。

デバッグ

# PKCS#11ライブラリのデバッグ出力を有効化
OPENLOOP_PKCS11_DEBUG=1 ssh-keygen -D "$MODULE"

# SSH接続の詳細ログ
ssh -vvv -I "$MODULE" user@hostname

PIV PIN管理

OpenloopはPIV PINによるデュアルモード署名をサポートしています。PINの設定状態により署名フローが変わります。

デュアルモード署名

OpenloopのPIV実装は2つの署名モードを持ちます。PINの設定・送信状態により自動的に切り替わります。

モード	条件	動作
`確認画面`	PINが未設定 or PIN未送信	デバイスに署名確認画面が表示され、ユーザーが物理的に承認
`ブラインド署名`	PINが設定済みかつ PIN検証済み	確認画面なしで即座に署名（PINが認証の代わり）

PINの初期設定

# 新しいPINを設定（6-8文字）
pkcs11-tool --module "$MODULE" --login --init-pin \
  --new-pin 123456

PINの変更

# 既存のPINを変更
pkcs11-tool --module "$MODULE" --login --change-pin \
  --pin 123456 --new-pin 654321

PINの削除

PINを削除するには、デバイスのUIから行います。Security画面で対象スロットを選択し、削除ボタンを使用してPINをクリアします。PINを削除すると確認画面モードに戻ります。

SSH with PIN

# PINを指定してSSH接続（ブラインド署名モード）
ssh -o "PKCS11Provider=$MODULE" \
    -o "PKCS11Pin=123456" \
    user@hostname

永続的なSSH設定（~/.ssh/config）

# ~/.ssh/config にPIN付きで設定
Host myserver
    HostName 192.168.1.100
    User ubuntu
    PKCS11Provider /Applications/Openloop Connect.app/Contents/Resources/pkcs11/libopenloop-pkcs11.dylib
    PKCS11Pin 123456

セキュリティ: PINを~/.ssh/configに記載する場合は、ファイルのパーミッションが chmod 600 であることを確認してください。また、SSH agentを使用する場合は ssh-add -s "$MODULE" でPINを一度入力すれば、以降の接続でPIN入力は不要です。

Firefox TLSクライアント認証

PKCS#11モジュールをFirefoxに登録して、mTLSクライアント証明書認証を利用します。

PKCS#11モジュールの登録

Firefoxの設定を開く
プライバシーとセキュリティに移動
証明書セクションのセキュリティデバイス...をクリック
読み込むをクリック
モジュール名: Openloop
モジュールファイル名: libopenloop-pkcs11.dylib を参照（上記ライブラリパスを参照）
OKをクリック

確認

セキュリティデバイスダイアログでOpenloopモジュールを展開
トークン情報が表示されるスロットを確認
証明書を表示をクリック（設定 > 証明書 > 証明書を表示）
あなたの証明書タブにOpenloopの証明書が表示されます

mTLS認証フロー

クライアント証明書を要求するWebサイトにアクセスすると、Firefoxが自動的に Openloopデバイスから証明書を選択するよう促します。署名操作には User Presence（デバイスへの物理的なタッチ）が必要です。

自動登録: macOSでは、Openloop Connectが ~/Library/Application Support/Mozilla/PKCS11Modules/openloop_pkcs11.json にマニフェストを配置することで、PKCS#11モジュールをFirefoxに自動登録できます。自動登録が有効な場合、手動での登録は不要です。

PIVスロット一覧

スロット	名前	用途
`9A`	PIV Authentication	SSH、一般的な認証。最も使用頻度が高い。
`9C`	Digital Signature	文書署名、S/MIME。常にPINが必要。
`9D`	Key Management	暗号化/復号化、鍵共有。
`9E`	Card Authentication	物理アクセス、非接触認証。PIN不要。

対応アルゴリズム

アルゴリズム	PIV ID	備考
`P-256`	0x11	NIST P-256（secp256r1）によるECDSA。広くサポートされている。
`Ed25519`	0x22	Curve25519によるEdDSA。SSHにはOpenSSH 8.5以上が必要。