Contents

1. Introduction
2. Passkeys (FIDO2/CTAP2)
3. PIV/PKCS#11
4. PKCS#11 library paths
5. SSH public-key authentication
6. Firefox TLS client authentication
7. pkcs11-tool reference
8. PIV slots & algorithms
9. Troubleshooting
10. References

1. Introduction

Openloop works not only as a crypto-asset hardware wallet but also as a security key. A single device provides the following two security functions.

These two functions do not overlap in purpose; they complement each other.

Prerequisites

Openloop passkeys can be used over two transports. Each has different prerequisites.

For PIV/PKCS#11, you need Openloop Connect (the desktop app) running. The PKCS#11 library is bundled with Connect.

2. Passkeys (FIDO2/CTAP2)

2.1 Overview

Openloop operates as a FIDO2/CTAP2-compliant security key. As a secure alternative to passwords, you can use it on any supporting website or service.

▲ Certification status: At this time, Openloop has not obtained the FIDO Alliance’s FIDO Certified Authenticator certification (FIDO2 Certified). While it is a spec-compliant CTAP2/WebAuthn implementation, official FIDO Alliance certification and AAGUID registration (FIDO Metadata Service) may be pursued in the future.

▲ About factory reset: Performing a factory reset permanently deletes all FIDO2 passkeys and PIV keys. Passkeys cannot be restored from the recovery phrase. You will need to re-register the security key with each service.

2.2 The two transports (USB / BLE) — important

Openloop passkeys work over entirely different paths for USB and BLE. Because this is easy to confuse, we clarify it up front.

🔌 USB CTAPHID path (desktop)

[PC browser] ──── USB HID (CTAPHID) ──── [Openloop device]
              ↑
              Works through the OS's built-in security-key support
              Openloop Connect is not required

• Uses the security-key support provided by the OS itself (Windows: webauthn.dll; macOS / Linux: built into the browser)
• The browser’s picker/prompt shows something like “Insert your security key” or “Use a security key”
• No Openloop Connect installation required
• Authenticate by connecting the USB cable and pressing the device button

📶 BLE (via Openloop Connect) path (mobile)

[iOS/Android browser]
   ↓ navigator.credentials API
[OS Credential Manager]
   ↓ Provider selection (user action)
[Openloop Connect app's Credential Provider Extension/Service]
   ↓ BLE
[Openloop device]

• Implemented independently by Openloop Connect as an iOS Credential Provider Extension / Android Credential Provider Service
• Appears in the browser’s passkey picker as follows:
  • iOS: “Openloop Connect” (per iOS spec, the containing-app name is displayed; it actually operates over BLE)
  • Android: “Openloop Connect” (over BLE)
• Required: the Openloop Connect mobile app + an Openloop device paired over BLE
• No USB cable needed; the device only has to be within Bluetooth range

▲ iOS note: The picker shows “Openloop Connect,” but communication happens over BLE, not USB. Because iOS fixes an Extension’s display name to the parent app name (Openloop Connect), the fact that it operates over BLE is not obvious from the UI. Keep this in mind.

2.3 Per-transport RP behavior — important (Google, etc.)

For most RPs (Relying Parties, i.e. websites), a single registration can be used over either transport (USB/BLE). However, some RPs (a notable example being Google) apply strict transports hint filtering, so a USB-registered credential works only over USB, and a BLE-registered credential works only over BLE.

Concrete examples affected

If you want to use both transports (Google, etc.)

By registering the passkey twice — once over USB and once over BLE — on the same Openloop device, you can make it usable over both transports. Because Openloop generates a different credential ID per transport even on the same hardware, the two are registered on the server as two independent credentials.

Google account settings:
  ├─ Security keys section: the USB registration (used on PC/Mac)
  └─ Passkeys section: the BLE registration (used on iPhone/Android)

2.4 Enabling it on Openloop

The passkey function is disabled by default. Whether you use USB or BLE, enable it with the steps below.

Common: enable the passkey function

1. On the Openloop device, open Settings > Passkey
2. Set Passkey to ON

If using the USB CTAPHID path

3. Open Settings > USB settings
4. Set USB HID to ON

If using the BLE (Openloop Connect) path

3. Open Settings > Bluetooth
4. Set Bluetooth to ON
5. On iOS / Android, launch the Openloop Connect app and pair/select the device

2.5 Resident Key and Non-Resident Key

There are two kinds of passkey credentials.

Which one a website requires is determined by the residentKey parameter at registration. Recent passkey-capable services (Google, Microsoft, GitHub, etc.) commonly require a Resident Key.

ℹ You can view and delete the list of Resident Keys stored on the device under Settings > Passkey > Credential list. Non-Resident Keys hold no state on the device, so they do not appear in the list.

2.6 Registering a passkey — USB CTAPHID path (desktop)

Register Openloop as a USB security key from a PC browser.

1. In the website’s security settings, choose “Add a security key” or similar
2. The browser shows a dialog asking you to insert the security key
3. Connect Openloop over USB (or it may already be connected)
4. A registration request appears on the Openloop device screen
5. Review the details and touch Approve
6. You may be prompted to enter the device PIN (depending on the User Verification setting)

2.7 Authenticating with a passkey — USB CTAPHID path

Use this when logging in to a registered website from a PC browser.

1. On the website’s login screen, choose “Sign in with a security key” or similar
2. Connect Openloop over USB
3. An authentication request appears on the Openloop device screen
4. Touch Approve

2.8 Registering a passkey — BLE (via Openloop Connect) (mobile)

From an iPhone / Android browser, register a passkey on the Openloop connected over BLE via Openloop Connect.

Preparation

1. Install the Openloop Connect mobile app (App Store / Google Play)
2. Launch the app and pair over BLE with the Openloop device, then select it (in Connect’s device management screen)
3. On the Openloop device, confirm that Settings > Bluetooth is ON

ℹ When using multiple devices: If you have registered multiple Openloop devices in Connect, passkey registration and authentication are performed against the device currently selected in Connect (the OS picker shows only “Openloop Connect” and does not let you choose which device). To use a different device, switch the selection in Connect’s device management screen before registering or authenticating.

Registration steps

1. Open the target site in iOS Safari / Android Chrome
2. Choose the passkey registration menu (e.g. Google: “Create a passkey”)
3. The OS Credential Manager picker appears:
   • iOS: Select “Openloop Connect” (it operates over BLE even though the picker shows “Connect”)
   • Android: Select “Openloop Connect”
4. Connect begins communicating with Openloop over BLE, and a registration request appears on the device screen
5. Press the Approve button on the device
6. Registration complete

2.9 Authenticating with a passkey — BLE (via Openloop Connect)

1. On the target site’s login screen in the browser, choose passkey authentication
2. Select Openloop Connect in the OS picker
3. Connect communicates with Openloop over BLE, and an authentication request appears on the device screen
4. Press the Approve button on the device
5. Login complete

ℹ Transport icon display: On the Openloop device’s passkey list screen, a 🔌 (USB) or 📶 (Bluetooth) icon appears to the left of each credential, so you can tell which transport it was registered over.

2.10 Managing credentials

You can manage registered passkeys on the Openloop device.

• View list: Settings > Passkey > Credential list
  • Each credential shows a transport icon (🔌 USB / 📶 Bluetooth)
• Delete individually: Select a credential and delete it
• Delete all (on the device): Settings > Passkey > Passkey reset
• Delete all (from the host / CTAP2 Reset): You can also initialize FIDO2 from the PC/browser side (over USB only; a confirmation appears on the device screen at execution, so approve it). All credentials and the FIDO PIN are erased.
  • Chrome / Edge: Settings > Privacy and security > Manage security keys > Reset (chrome://settings/securityKeys)
  • CLI (libfido2): fido2-token -R <device>

▲ Performing a passkey reset (either on the device or from the host) deletes all credentials. You will need to re-register with each website.

2.11 Supported browsers & platforms

USB CTAPHID path

• Windows: WebAuthn registration and authentication work normally in all browsers (via the OS’s built-in webauthn.dll)
• macOS Chrome: Registration and authentication work normally
• macOS Safari/Firefox: Registration and authentication work normally. If the user does not approve on the device side, the browser may keep waiting for a response (a platform-side limitation). You can recover with the browser’s “Cancel” button.

BLE (via Openloop Connect) path

▲ On iOS, the browser’s passkey picker shows “Openloop Connect,” but this is because iOS fixes an Extension’s display name to the parent app name (ignoring CFBundleDisplayName); the actual communication happens over BLE.

2.12 Examples of supported services

Major websites and services that support passkeys:

• Google account
• Microsoft account
• GitHub
• Cloudflare
• AWS (IAM)
• 1Password
• and many other FIDO2/WebAuthn-capable services

ℹ You can find the latest list of supporting services at passkeys.directory.

3. PIV/PKCS#11

3.1 Overview

Openloop implements the PIV (Personal Identity Verification, NIST SP 800-73) smart card interface. Through the PKCS#11 shared library, it covers use cases that passkeys cannot, such as SSH authentication and TLS client authentication.

3.2 Architecture

SSH / Firefox / pkcs11-tool
  ↓ PKCS#11 C API
libopenloop-pkcs11 (.dylib / .dll / .so)
  ↓ PIV APDU → WebSocket (ws://127.0.0.1:21320)
Openloop Connect (transparent APDU forwarding)
  ↓ USB HID
Openloop device (PIV handler → signing with SE050)

Because the PKCS#11 library communicates with the device via Openloop Connect, Openloop Connect must be running when you use the PIV/PKCS#11 functions.

3.3 Enabling PIV/PKCS#11

Enable PIV under Settings > Passkey & PIV > PIV ON. Turning it OFF hides the PKCS#11 slots.

Also check the following settings:

1. Install and launch Openloop Connect
2. On the Openloop device, set Settings > USB settings > USB HID to ON
3. Connect Openloop over USB and confirm that Connect shows the device as Device Connected

3.4 PIV PIN setup

The PIV PIN is optional. Setting a PIN enables PIN authentication over USB, and when the PIN is sent, signing happens without a confirmation screen (blind signing). If you do not set a PIN, on-device confirmation is required as before.

Dual mode

Openloop’s PIV implementation offers two operating modes depending on whether the PIN is sent.

ℹ You can use both modes with a single device. Whether the PIN is sent is controlled on the client side (SSH configuration, etc.).

How to set the PIN

# Initial PIN setup
pkcs11-tool --module "$MODULE" --login --init-pin --new-pin 123456

# Change the PIN
pkcs11-tool --module "$MODULE" --login --change-pin --pin 123456 --new-pin 654321

Deleting the PIN

To delete the PIN, use one of the following methods:

• Device UI: Settings > Passkey & PIV > touch the 🗑 button next to PIV PIN
• USB APDU: Send the RESET RETRY COUNTER command

If the PIN is locked

Entering the wrong PIN 8 times in a row locks it. If it becomes locked, delete the PIN with the 🗑 button in the device UI and set it again.

SSH usage example (with PIN)

# SSH connection with a PIN
ssh -o "PKCS11Provider=$MODULE" -o "PKCS11Pin=123456" user@host

▲ Writing the PIN directly on the command line may leave it in the shell history or the process list. In security-critical environments, consider using ssh-agent or the PIN-not-sent mode (the on-device confirmation flow).

4. PKCS#11 library paths

The PKCS#11 library is bundled with Openloop Connect. It is in the pkcs11/ folder under the app installation path:

The app’s install location <app> varies by installation method:

The examples that follow set the full path of the macOS DMG build in a shell variable:

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

5. SSH public-key authentication

Use Openloop as an SSH hardware key via PKCS#11. The private key is kept inside the device’s SE050 secure element and can never be extracted.

5.1 Preparing a key

Generate a key pair in a PIV slot (default: 9A Authentication). Generate the key by either of the following:

• Demo page: Generate it from the web interface at PIV Demo
• pkcs11-tool: Generate it from the command line (see Chapter 7)

5.2 Retrieving the public key

# Retrieve the SSH public key from the device
ssh-keygen -D "$MODULE"

# Save it to a file
ssh-keygen -D "$MODULE" > ~/openloop_key.pub

Add the retrieved public key to the remote server’s ~/.ssh/authorized_keys.

5.3 SSH connection

# A one-off connection
ssh -I "$MODULE" user@hostname

5.4 Persistent configuration (~/.ssh/config)

Instead of specifying the -I option every time, you can write the configuration in ~/.ssh/config.

# Apply to a specific host
Host myserver
    HostName 192.168.1.100
    User ubuntu
    PKCS11Provider /Applications/Openloop Connect.app/Contents/Resources/pkcs11/libopenloop-pkcs11.dylib

# Apply to all hosts
Host *
    PKCS11Provider /Applications/Openloop Connect.app/Contents/Resources/pkcs11/libopenloop-pkcs11.dylib

5.5 SSH implementation compatibility and the OpenSSH recommendation

Openloop’s PIV/PKCS#11 supports three algorithms: P-256, Ed25519, and RSA-2048 (RSA-2048 supported). The algorithms usable over PKCS#11 differ by SSH implementation.

▲ We strongly recommend using OpenSSH (the Homebrew build). The macOS system SSH (the Apple build) has incomplete ECDSA/EdDSA support over PKCS#11. Using an RSA-2048 key avoids the compatibility issues.

# Install Homebrew OpenSSH
brew install openssh

# Use the Homebrew build (specify the full path)
/opt/homebrew/bin/ssh -I "$MODULE" user@hostname

# Check the version (confirm 8.5 or later)
/opt/homebrew/bin/ssh -V

# Add IgnoreUnknown UseKeychain in ~/.ssh/config
# (Suppresses warnings about the macOS-specific option that Homebrew SSH does not recognize)

5.6 Debugging

# Enable debug output from the PKCS#11 library
OPENLOOP_PKCS11_DEBUG=1 ssh-keygen -D "$MODULE"

# Verbose SSH connection log
ssh -vvv -I "$MODULE" user@hostname

6. Firefox TLS client authentication

Why Firefox

Among the major browsers, Firefox is the only one that supports loading an external PKCS#11 module. Chrome, Edge, and Safari use only the OS’s built-in keychain/certificate store and provide no way to load a third-party PKCS#11 library directly. That is why TLS client authentication using Openloop’s PKCS#11 library is done in Firefox.

Register the PKCS#11 module in Firefox to use TLS client-certificate authentication (mTLS).

6.1 Registering the PKCS#11 module

1. Open Firefox Settings
2. Go to Privacy & Security
3. In the Certificates section, click Security Devices…
4. Click Load
5. Module Name: enter Openloop
6. Module filename: browse to and select the library path above
7. Click OK

6.2 How to verify

1. In the Security Devices dialog, expand the Openloop module
2. Confirm the slot that shows token information
3. Click View Certificates (Settings > Certificates > View Certificates)
4. The Openloop certificate appears on the Your Certificates tab

6.3 mTLS authentication flow

When you access a website that requests a client certificate, Firefox automatically prompts you to select the certificate from the Openloop device. The signing operation requires User Presence (a physical touch on the device).

6.4 Automatic registration (macOS)

On macOS, Openloop Connect can automatically register the PKCS#11 module in Firefox by placing a manifest at the following path:

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

When automatic registration is active, manual registration is unnecessary.

7. pkcs11-tool reference

You can use OpenSC’s pkcs11-tool command to work with the device’s keys and objects.

Installation

# macOS
brew install opensc

# Ubuntu/Debian
sudo apt install opensc

# Windows
# Install from the OpenSC installer: https://github.com/OpenSC/OpenSC/releases

List slots and tokens

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

List objects

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

Generate a key pair

# Generate P-256 in slot 9A (Authentication)
pkcs11-tool --module "$MODULE" --keypairgen \
  --key-type EC:prime256v1 \
  --id 01 --label "PIV AUTH"

# Generate Ed25519 in slot 9A
pkcs11-tool --module "$MODULE" --keypairgen \
  --key-type EC:edwards25519 \
  --id 01 --label "PIV AUTH"

Signing test

# Create test data and sign it with the key in slot 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

Deleting a key

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

8. PIV slots & algorithms

8.1 PIV slots

8.2 Supported algorithms

8.3 PKCS#11 object-ID mapping

9. Troubleshooting

The passkey isn’t recognized

• Check that Settings > USB settings > USB HID is ON on the device
• Check that Settings > Passkey is ON on the device
• Check that the USB cable supports data (charge-only cables won’t work)
• Try reconnecting the device

The PKCS#11 library can’t be found

• Check that Openloop Connect is installed
• Check that the library path is correct (see Chapter 4)

ssh-keygen -D shows no keys

• Check that Openloop Connect is running
• Check that the device is connected to Connect (Device Connected shown)
• Check that a key has been generated in the PIV slot (verify with pkcs11-tool -O)
• On macOS, check that you are using the Homebrew build of OpenSSH

Firefox can’t load the module

• Check that Openloop Connect is running
• Check that the library file path is correct
• Try restarting Firefox

Signing times out

• Check whether a signing-confirmation dialog is showing on the device screen
• Operations that require User Presence (a physical touch) need you to touch the device

Collecting debug logs

You can see the details of the communication by enabling debug output from the PKCS#11 library:

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

10. References

FIDO2 / WebAuthn

PIV / PKCS#11

Openloop-related