目次

1. はじめに
2. パスキー（FIDO2/CTAP2）
3. PIV/PKCS#11
4. PKCS#11ライブラリパス
5. SSH公開鍵認証
6. Firefox TLSクライアント認証
7. pkcs11-tool リファレンス
8. PIVスロット・アルゴリズム一覧
9. トラブルシューティング
10. 参考資料

1. はじめに

Openloopは暗号資産ハードウェアウォレットとしてだけでなく、セキュリティキーとしても機能します。1台のデバイスで以下の2つのセキュリティ機能を提供します。

この2つの機能は用途が重複せず、相互補完の関係にあります。

前提条件

Openloopのパスキーは 2つの経路 (transport) で利用できます。それぞれ前提条件が異なります。

PIV/PKCS#11 については Openloop Connect（デスクトップアプリ）の起動が必要です。PKCS#11ライブラリはConnectに同梱されています。

2. パスキー（FIDO2/CTAP2）

2.1 概要

OpenloopはFIDO2/CTAP2準拠のセキュリティキーとして動作します。パスワードに代わる安全な認証手段として、対応するWebサイトやサービスで利用できます。

▲ 認証ステータス: 現時点で Openloop は FIDO Alliance の FIDO Certified Authenticator 認証 (FIDO2 Certified) を取得していません。仕様準拠のCTAP2/WebAuthn 実装ではありますが、FIDO Alliance 公式認証および AAGUID 登録 (FIDO Metadata Service) については、将来的な取得を検討する可能性があります。

▲ ファクトリーリセットについて: ファクトリーリセットを実行すると、すべてのFIDO2パスキーおよびPIV鍵が完全に削除されます。パスキーはリカバリーフレーズでは復元できません。各サービスでのセキュリティキー再登録が必要です。

2.2 2つのトランスポート (USB / BLE) — 重要

OpenloopのパスキーはUSBとBLEで動作経路がまったく異なります。混同しやすいので最初に明確化します。

🔌 USB CTAPHID 経路 (デスクトップ)

[PC ブラウザ] ──── USB HID (CTAPHID) ──── [Openloop デバイス]
              ↑
              OS標準のセキュリティキー機能で動作
              Openloop Connect は不要

• OSが標準で提供 するセキュリティキー機能 (Windows: webauthn.dll、macOS / Linux: ブラウザ内蔵)
• ブラウザのpicker/プロンプトには「セキュリティキーを挿入」「Use a security key」等が表示される
• Openloop Connect のインストール不要
• USB ケーブル接続 + デバイスのボタン押下で認証

📶 BLE (Openloop Connect 経由) 経路 (モバイル)

[iOS/Android ブラウザ]
   ↓ navigator.credentials API
[OS Credential Manager]
   ↓ Provider 選択 (ユーザー操作)
[Openloop Connect アプリの Credential Provider Extension/Service]
   ↓ BLE
[Openloop デバイス]

• iOS Credential Provider Extension / Android Credential Provider Service として Openloop Connect が独自実装
• ブラウザの passkey ピッカーに以下のように表示される:
  • iOS: 「Openloop Connect」(※iOS仕様により containing app 名が表示される。実際はBLE経由で動作)
  • Android: 「Openloop Connect」(BLE経由)
• 必須: Openloop Connect モバイルアプリ + BLE ペアリング済み Openloop デバイス
• USB ケーブル不要、デバイスはBluetooth到達範囲にあれば良い

▲ iOS 注意: ピッカーに「Openloop Connect」と表示されるが、通信は USB ではなく BLE で行われます。iOS の仕様上、Extension の表示名は親アプリ名 (Openloop Connect) に固定されるため、BLE 経由で動作することがUI上分かりにくい点に注意してください。

2.3 Transport別 RP挙動 — 重要 (Google等)

ほとんどの RP (Relying Party、=Webサイト) では 1回の登録で USB/BLE どちらの transport でも使用可能 です。しかし一部のRP (代表例: Google) は厳格な transports hint フィルタリングを行うため、USB登録 credential は USB経路でのみ、BLE登録 credential は BLE経路でのみ 使えます。

影響する具体例

両transport で使いたい場合 (Google等)

同じ Openloop デバイス で USB と BLE の2回 passkey 登録 することで、両 transport で使える状態にできます。Openloop は同じハードウェアでも transport ごとに異なる credential ID を生成するため、サーバ側に独立した2つのcredentialとして登録されます。

Google アカウント設定:
  ├─ セキュリティキー欄: USB登録分 (PC/Mac で利用)
  └─ パスキー欄: BLE登録分 (iPhone/Android で利用)

2.4 Openloopでの有効化

パスキー機能はデフォルトで無効になっています。USB / BLE どちらを使う場合でも以下の手順で有効化してください。

共通: パスキー機能の有効化

1. Openloopデバイスの 設定 > パスキー を開く
2. パスキー を ON に設定

USB CTAPHID 経路を使う場合

3. 設定 > USB設定 を開く
4. USB HID を ON に設定

BLE (Openloop Connect) 経路を使う場合

3. 設定 > Bluetooth を開く
4. Bluetooth を ON に設定
5. iOS / Android で Openloop Connect アプリを起動、デバイスをペアリング・選択

2.5 Resident Key と Non-Resident Key

パスキーのクレデンシャルには2種類あります。

Webサイトがどちらを要求するかは、登録時の residentKey パラメータで決まります。近年のパスキー対応サービス（Google、Microsoft、GitHub等）はResident Keyを要求するのが一般的です。

ℹ デバイスに保存されたResident Keyの一覧は、設定 > パスキー > クレデンシャル一覧 で確認・削除できます。Non-Resident Keyはデバイスに状態を持たないため一覧には表示されません。

2.6 パスキーの登録 — USB CTAPHID 経路 (デスクトップ)

PC のブラウザから Openloop を USB セキュリティキーとして登録します。

1. Webサイトのセキュリティ設定で「セキュリティキーを追加」等を選択
2. ブラウザがセキュリティキーの挿入を求めるダイアログを表示
3. OpenloopをUSBで接続（または既に接続済み）
4. Openloopのデバイス画面に登録リクエストが表示される
5. 内容を確認し、承認をタッチ
6. デバイスPINの入力を求められる場合があります（User Verification設定による）

2.7 パスキーによる認証 — USB CTAPHID 経路

登録済みのWebサイトにPCのブラウザからログインする際に使用します。

1. Webサイトのログイン画面で「セキュリティキーでログイン」等を選択
2. OpenloopをUSBで接続
3. Openloopのデバイス画面に認証リクエストが表示される
4. 承認をタッチ

2.8 パスキーの登録 — BLE (Openloop Connect 経由) (モバイル)

iPhone / Android のブラウザから、Openloop Connect 経由で BLE 接続した Openloop に passkey を登録します。

事前準備

1. Openloop Connect モバイルアプリをインストール (App Store / Google Play)
2. アプリを起動し、Openloop デバイスと BLE ペアリング + デバイス選択 (Connectのデバイス管理画面)
3. Openloop デバイスで 設定 > Bluetooth が ON になっていることを確認

ℹ 複数デバイス使用時: 複数の Openloop を Connect に登録している場合、パスキーの登録・認証は Connect で現在選択中のデバイス に対して行われます（OS の picker には「Openloop Connect」としか表示されず、どのデバイスかは選べません）。別のデバイスを使いたいときは、登録・認証の前に Connect のデバイス管理画面で選択を切り替えてください。

登録手順

1. iOS Safari / Android Chrome で対象サイトを開く
2. パスキー登録メニュー (例: Google: 「パスキーを作成」)
3. OS の Credential Manager picker が表示される:
   • iOS: 「Openloop Connect」を選択 (※ BLE で動作するが picker 表示は「Connect」)
   • Android: 「Openloop Connect」を選択
4. Connect が BLE で Openloop と通信開始、デバイス画面に登録リクエスト表示
5. デバイスの 承認 ボタンを押下
6. 登録完了

2.9 パスキーによる認証 — BLE (Openloop Connect 経由)

1. ブラウザで対象サイトのログイン画面 → パスキー認証選択
2. OS picker で Openloop Connect 選択
3. Connect が BLE で Openloop と通信、デバイス画面に認証リクエスト表示
4. デバイスの 承認 ボタンを押下
5. ログイン完了

ℹ transport icon表示: Openloop デバイスのパスキー一覧画面では、各 credential の左に 🔌(USB) または 📶(Bluetooth) アイコンが表示され、どちらの経路で登録されたかを区別できます。

2.10 クレデンシャルの管理

登録したパスキーはOpenloopデバイス上で管理できます。

• 一覧表示: 設定 > パスキー > クレデンシャル一覧
  • 各 credential に transport アイコン (🔌 USB / 📶 Bluetooth) 表示
• 個別削除: クレデンシャルを選択して削除
• 全削除（デバイス操作）: 設定 > パスキー > パスキーリセット
• 全削除（ホストから / CTAP2 Reset）: PC・ブラウザ側からも FIDO2 を初期化できます（USB 接続時のみ。実行時はデバイス画面に確認が表示されるので承認）。全クレデンシャルと FIDO PIN が消去されます。
  • Chrome / Edge: 設定 > プライバシーとセキュリティ > セキュリティキーの管理 > リセット（chrome://settings/securityKeys）
  • CLI（libfido2）: fido2-token -R <device>

▲ パスキーリセット（デバイス操作・ホスト操作のいずれも）を実行すると、すべてのクレデンシャルが削除されます。各Webサイトで再登録が必要になります。

2.11 対応ブラウザ・プラットフォーム

USB CTAPHID 経路

• Windows: 全ブラウザでWebAuthn登録・認証が正常動作（OS標準webauthn.dll経由）
• macOS Chrome: 登録・認証は正常動作
• macOS Safari/Firefox: 登録・認証は正常動作。ユーザーがデバイス側で承認しなかった場合、ブラウザが応答待ちを続ける場合があります（プラットフォーム側の制限）。ブラウザの「キャンセル」ボタンで復帰可能。

BLE (Openloop Connect 経由) 経路

▲ iOS の場合、ブラウザの passkey ピッカーには「Openloop Connect」と表示されますが、これは iOS Extension仕様の親アプリ名固定 (CFBundleDisplayName 無視) によるもので、実際の通信は BLE で行われます。

2.12 対応サービスの例

パスキーに対応する主要なWebサイト・サービス:

• Google アカウント
• Microsoft アカウント
• GitHub
• Cloudflare
• AWS (IAM)
• 1Password
• その他、FIDO2/WebAuthn対応の多数のサービス

ℹ 対応サービスの最新リストは passkeys.directory で確認できます。

3. PIV/PKCS#11

3.1 概要

OpenloopはPIV（Personal Identity Verification, NIST SP 800-73）スマートカードインターフェースを実装しています。PKCS#11共有ライブラリを通じて、SSH認証やTLSクライアント認証など、パスキーではカバーできないユースケースに対応します。

3.2 アーキテクチャ

SSH / Firefox / pkcs11-tool
  ↓ PKCS#11 C API
libopenloop-pkcs11 (.dylib / .dll / .so)
  ↓ PIV APDU → WebSocket (ws://127.0.0.1:21320)
Openloop Connect (APDUの透過転送)
  ↓ USB HID
Openloop デバイス (PIVハンドラ → SE050で署名)

PKCS#11ライブラリはOpenloop Connect経由でデバイスと通信するため、PIV/PKCS#11機能を使用する際はOpenloop Connectが起動している必要があります。

3.3 PIV/PKCS#11の有効化

設定 > パスキー・PIV > PIV ON でPIVを有効化します。OFFにするとPKCS#11のスロットが非表示になります。

また、以下の設定も確認してください:

1. Openloop Connectをインストール・起動する
2. Openloopデバイスの 設定 > USB設定 > USB HID を ON に設定
3. OpenloopをUSBで接続し、ConnectがデバイスをDevice Connectedと表示することを確認

3.4 PIV PIN 設定

PIV PINはオプションです。PINを設定するとUSB経由のPIN認証が有効になり、PIN送信時は確認画面なしで署名されます（ブラインド署名）。PINを設定しない場合は、従来通りデバイス画面での確認操作が必要です。

デュアルモード

OpenloopのPIV実装は、PIN送信の有無に応じて2つの動作モードを提供します。

ℹ 1つのデバイスで両方のモードを使い分けることができます。PINを送信するかどうかはクライアント側（SSH設定等）で制御します。

PIN設定方法

# PINの初期設定
pkcs11-tool --module "$MODULE" --login --init-pin --new-pin 123456

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

PINの削除

PINを削除するには、以下のいずれかの方法を使用します:

• デバイスUI: 設定 > パスキー・PIV > PIV PIN の🗑ボタンをタッチ
• USB APDU: RESET RETRY COUNTERコマンドを送信

PINロック時の対処

PINを8回連続で間違えるとロックされます。ロック状態になった場合は、デバイスUIの🗑ボタンでPINを削除し、再設定してください。

SSH使用例（PIN付き）

# PIN付きでSSH接続
ssh -o "PKCS11Provider=$MODULE" -o "PKCS11Pin=123456" user@host

▲ PINをコマンドラインに直接記述すると、シェル履歴やプロセス一覧に残る可能性があります。セキュリティが重要な環境では、ssh-agentの利用やPIN未送信モード（デバイス確認画面フロー）を検討してください。

3.5 鍵共有（ECDH）— C_DeriveKey

スロット 9D（Key Management） の P-256 の鍵で、相手の公開鍵との間の共有秘密（32バイト）を求められます。秘密鍵はデバイスの外に出ません。PKCS#11 の C_DeriveKey（機構 CKM_ECDH1_DERIVE。CKM_ECDH1_COFACTOR_DERIVE でも P-256 は同じ結果）を使います。

承認の規則

承認の規則は署名と同じです（3.4 PIV PIN 設定を参照）。

• PINを入力している場合（USBで認証済み）: デバイスの確認画面なしで、自動的に鍵共有します
• PINを設定していない、または入力していない場合: デバイスの画面に「PIV鍵共有を許可しますか？」と表示されます。承認すると鍵共有されます

OpenSSL の pkcs11-provider での例

OpenSSL に pkcs11-provider を読み込める状態で、次のとおり実行します。$MODULE は第4章のライブラリのパスです。

# 相手の鍵ペアを作る（相手が別の人や別のプログラムの場合は、その公開鍵を使います）
openssl ecparam -name prime256v1 -genkey -noout -out peer.pem
openssl ec -in peer.pem -pubout -out peer_pub.pem

# デバイスの 9D の秘密鍵と相手の公開鍵から、共有秘密（32バイト）を求める
PKCS11_PROVIDER_MODULE="$MODULE" openssl pkeyutl -provider pkcs11 -provider default -derive \
  -inkey 'pkcs11:token=Openloop%20PIV%200x9D;type=private' \
  -peerkey peer_pub.pem -out shared.bin

PINを入力するときは、-inkey のURIの末尾に ;pin-value=<PIN> を付けます（コマンドラインに残る点は3.4の注意と同じです）。

▲ 共有秘密はそのまま暗号鍵として使わず、HKDF などの鍵導出関数を通してから使ってください。

4. PKCS#11ライブラリパス

PKCS#11ライブラリはOpenloop Connectに同梱されています。アプリインストールパス配下の pkcs11/ フォルダ内です:

アプリのインストール先 <app> はインストール方法により異なります:

以降の例では、macOS DMG 版の完全パスをシェル変数に設定して使用します:

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

5. SSH公開鍵認証

OpenloopをPKCS#11経由でSSHハードウェアキーとして使用します。秘密鍵はデバイスのSE050セキュアエレメント内に保管され、外部に取り出すことはできません。

5.1 鍵の準備

PIVスロット（デフォルト: 9A Authentication）に鍵ペアを生成します。鍵の生成方法は以下のいずれかです:

• デモページ: PIV Demo のWebインターフェースから生成
• pkcs11-tool: コマンドラインから生成（第7章参照）

5.2 公開鍵の取得

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

# ファイルに保存
ssh-keygen -D "$MODULE" > ~/openloop_key.pub

取得した公開鍵をリモートサーバーの ~/.ssh/authorized_keys に追加してください。

5.3 SSH接続

# 単発の接続
ssh -I "$MODULE" user@hostname

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

毎回 -I オプションを指定する代わりに、~/.ssh/config に設定を記述できます。

# 特定のホストに適用
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

5.5 SSH実装の互換性とOpenSSH推奨

OpenloopのPIV/PKCS#11はP-256、Ed25519、RSA-2048の3つのアルゴリズムをサポートしています（RSA-2048対応）。SSH実装によってPKCS#11経由で利用できるアルゴリズムが異なります。

▲ OpenSSH（Homebrew版）の使用を強く推奨します。 macOSのシステムSSH（Apple版）はPKCS#11経由でのECDSA/EdDSAサポートが不完全です。RSA-2048鍵を使用すれば互換性の問題を回避できます。

# Homebrew OpenSSHのインストール
brew install openssh

# Homebrew版を使用（フルパス指定）
/opt/homebrew/bin/ssh -I "$MODULE" user@hostname

# バージョン確認（8.5以上であることを確認）
/opt/homebrew/bin/ssh -V

# ~/.ssh/config で IgnoreUnknown UseKeychain を追加
# （Homebrew SSHが認識しない macOS 独自オプションの警告を抑制）

5.6 デバッグ

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

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

6. Firefox TLSクライアント認証

なぜFirefoxか

主要ブラウザの中で、Firefoxは唯一、外部PKCS#11モジュールの読み込みをサポートしているブラウザです。ChromeやEdge、SafariはOS標準のキーチェーン/証明書ストアのみを使用し、サードパーティのPKCS#11ライブラリを直接読み込む機能を提供していません。そのため、OpenloopのPKCS#11ライブラリを使ったTLSクライアント認証はFirefoxで利用します。

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

6.1 PKCS#11モジュールの登録

1. Firefoxの 設定 を開く
2. プライバシーとセキュリティ に移動
3. 証明書 セクションの セキュリティデバイス… をクリック
4. 読み込む をクリック
5. モジュール名: Openloop と入力
6. モジュールファイル名: 上記のライブラリパスを参照して選択
7. OK をクリック

6.2 確認方法

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

6.3 mTLS認証フロー

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

6.4 自動登録（macOS）

macOSでは、Openloop Connectが以下のパスにマニフェストを配置することで、PKCS#11モジュールをFirefoxに自動登録できます:

~/Library/Application Support/Mozilla/PKCS11Modules/openloop_pkcs11.json

自動登録が有効な場合、手動での登録は不要です。

7. pkcs11-tool リファレンス

OpenSCのpkcs11-toolコマンドを使って、デバイスの鍵やオブジェクトを操作できます。

インストール

# macOS
brew install opensc

# Ubuntu/Debian
sudo apt install opensc

# Windows
# OpenSCインストーラーからインストール: https://github.com/OpenSC/OpenSC/releases

スロット・トークン一覧

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

オブジェクト一覧

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

鍵ペア生成

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

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

--id にはPIVスロットの番号（9a／9c／9d／9e）をそのまま指定します。ラベルは指定しても無視され、デバイスが PIV AUTH 0x9A のような値を返します。

署名テスト

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

鍵の削除

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

8. PIVスロット・アルゴリズム一覧

8.1 PIVスロット

8.2 対応アルゴリズム

8.3 PKCS#11オブジェクトID マッピング

9. トラブルシューティング

パスキーが認識されない

• デバイスの 設定 > USB設定 > USB HID が ON になっているか確認
• デバイスの 設定 > パスキー が ON になっているか確認
• USBケーブルがデータ通信対応か確認（充電専用ケーブルでは動作しません）
• デバイスを再接続してみてください

PKCS#11ライブラリが見つからない

• Openloop Connectがインストールされているか確認
• ライブラリパスが正しいか確認（第4章参照）

ssh-keygen -D で鍵が表示されない

• Openloop Connectが起動しているか確認
• デバイスがConnectに接続されているか確認（Device Connected表示）
• PIVスロットに鍵が生成されているか確認（pkcs11-tool -O で確認）
• macOSではHomebrew版OpenSSHを使用しているか確認

Firefox でモジュールが読み込めない

• Openloop Connectが起動しているか確認
• ライブラリファイルのパスが正しいか確認
• Firefoxを再起動してみてください

署名時にタイムアウトする

• デバイス画面に署名確認ダイアログが表示されていないか確認
• User Presence（物理タッチ）が必要な操作では、デバイスへのタッチが必要です

デバッグログの取得

PKCS#11ライブラリのデバッグ出力を有効にすることで、通信の詳細を確認できます:

OPENLOOP_PKCS11_DEBUG=1 ssh-keygen -D "$MODULE"

10. 参考資料

FIDO2 / WebAuthn

PIV / PKCS#11

Openloop関連