CLI Testing Tool

The Arculus FIDO2 CLI (Command Line Interface) is a desktop testing tool for validating Arculus FIDO2 card functionality and testing integration with FIDO2 servers. It provides a command-line interface to perform all FIDO2 operations including registration, authentication, PIN management, and credential management.

Note: This tool is intended for testing and development purposes only. It requires a desktop NFC card reader that supports the PC/SC interface. Arculus has tested with with the following NFC card readers:

• HID OmniKey 5422 HID

• LIBO NFC Smart ACR122U RFI

Overview

The CLI tool allows you to:

• Test FIDO2 registration and authentication flows

• Manage PINs (set, change, check retries)

• List and manage credentials on the card

• Test against local or remote FIDO2 servers

• Validate card functionality before integrating the SDK into your application

• Debug FIDO2 operations with detailed logging

Prerequisites

Hardware Requirements

• Desktop NFC Card Reader: A PC/SC-compatible NFC reader (e.g., HID Global OMNIKEY 5422)

• Arculus FIDO2 Card: An Arculus FIDO2 hardware security key

Software Requirements

• PC/SC Support:

  • Windows: Built-in (no additional installation needed)

  • macOS: Built-in (no additional installation needed)

  • Linux: Install pcsclite from your package manager or from source

Obtaining the CLI Tool

Contact your Arculus representative to obtain the CLI tool distribution package. The package includes:

• ArculusFidoCli.jar - Main CLI executable

• Convenience scripts (.sh for Linux/macOS, .bat for Windows)

• Required dependencies

Installation

Extract the Distribution Package

# Extract the CLI distribution package
unzip ArculusFidoCli-<OS>-<ARCH>-<VERSION>.tar.gz
cd ArculusFidoCli-<OS>-<ARCH>-<VERSION>

Verify PC/SC Reader Detection

Before using the CLI, verify that your card reader is detected:

./arculusFido.sh --listCardReaders

Expected output:

{
  "status": "ok",
  "errorMessage": "",
  "responseCode": "200",
  "resultData": {
    "readers": [
      "HID Global OMNIKEY 5422 Smartcard Reader 0"
    ]
  }
}

Note: On Windows, the CLI must be run as Administrator, as FIDO2 CTAP card interactions are blocked for normal user accounts for security reasons.

Basic Usage

The CLI tool uses the arculusFido.sh (or arculusFido.bat on Windows) script with a --command parameter to specify the operation.

Common Parameters

Most commands support these common parameters:

Parameter	Description	Default
--command=<command>	Command to execute (required)	None
--pin=<PIN>	6+ digit numeric PIN	123456
--address=<address>	FIDO2 server address	127.0.0.1
--port=<port>	FIDO2 server port	5001
--relyingParty=<rpId>	Relying party ID	localhost
--username=<username>	User identifier	[email protected]
--displayName=<name>	Display name	Test User
--preferredReader=<name>	PC/SC reader name	Auto-detect
--ignoreSSLCertValidation=<true|false>	Ignore SSL cert validation (testing only)	false
--sdk	Output raw SDK results only	false

Server Address Format: The --address parameter can be:

• IP address: 127.0.0.1

• Hostname: localhost

• URL with protocol: https://myserver.com (port defaults to 443)

• URL without protocol: myserver.com (uses specified port)

Commands

Device Information

Get Version

Get the version information from the Arculus FIDO2 card:

./arculusFido.sh --command=version

Or use the convenience script:

./version.sh

Get Device Info

Get detailed device information:

./arculusFido.sh --command=deviceInfo

Or use the convenience script:

./deviceInfo.sh

PIN Management

Set PIN

Set a PIN on the card. Note: Setting a PIN also resets the device to a clean state.

./arculusFido.sh --command=setpin --pin=123456

Or use the convenience script:

./setpin.sh --pin=123456

PIN Requirements: PIN must be numeric and between 4 and 12 digits.

Change PIN

Change an existing PIN. Note: This does NOT reset the device.

./arculusFido.sh --command=changepin --pin=123456 --newPin=111111

Or use the convenience script:

./change_pin.sh --pin=123456 --newPin=111111

Check PIN Retries

Get the number of PIN retries remaining:

./arculusFido.sh --command=pinRetries

Or use the convenience script:

./pin_retries.sh

Device Management

Reset Device

Reset the Arculus FIDO2 device to a clean state (removes all credentials):

./arculusFido.sh --command=reset

Or use the convenience script:

./reset_device.sh

Registration

Register a user and create a FIDO2 credential on both the card and the FIDO2 server:

./arculusFido.sh --command=register \
  --address=127.0.0.1 \
  --port=5001 \
  --relyingParty=localhost \
  --pin=123456 \
  [email protected] \
  --displayName="My Name" \
  --registrationInfo='{"deviceInfo":"myiPhone","serial":"ABCDEF"}'

Parameters:

• --pin: Card PIN (required)

• --username: User identifier (required)

• --displayName: Human-readable name (required)

• --address: FIDO2 server address

• --port: FIDO2 server port

• --relyingParty: Relying party ID (domain)

• --registrationInfo: Optional JSON object with device metadata

• --resetOnRegister: Reset device before registering (optional)

Example with HTTPS:

./arculusFido.sh --command=register \
  --address=https://myserver.com \
  --port=5001 \
  --relyingParty=mycompanyauth.com \
  --pin=485623 \
  [email protected] \
  --displayName="My User"

Or use the convenience script:

./register.sh --address=127.0.0.1 --port=5001 --relyingParty=localhost --pin=123456 [email protected] --displayName="MyName"

Authentication

Authenticate a user with an existing FIDO2 credential:

./arculusFido.sh --command=authenticate \
  --address=127.0.0.1 \
  --port=5001 \
  --relyingParty=localhost \
  --pin=123456 \
  [email protected] \
  --displayName="My Name"

Parameters:

• --pin: Card PIN (required, unless --nopin is used)

• --username: User identifier (required)

• --displayName: Human-readable name (required)

• --address: FIDO2 server address

• --port: FIDO2 server port

• --relyingParty: Relying party ID (domain)

• --nopin: Authenticate without PIN (if card allows)

Example with HTTPS:

./arculusFido.sh --command=authenticate \
  --address=https://myserver.com \
  --port=8081 \
  --relyingParty=mycompanyauth.com \
  --pin=485623 \
  [email protected]

Or use the convenience script:

./authenticate.sh --address=127.0.0.1 --port=5001 --relyingParty=localhost --pin=123456 [email protected] --displayName="MyName"

Credential Management

List Credentials for Relying Party

List all credentials on the card for a specific relying party:

./arculusFido.sh --command=listcredentials \
  --pin=123456 \
  --relyingParty=localhost

Or use the convenience script:

./listallcredentials.sh --pin=123456 --relyingParty=localhost

List All Credentials

List all credentials on the card across all relying parties:

./arculusFido.sh --command=listallcredentials --pin=123456

Or use the convenience script:

./listallcredentials.sh --pin=123456

List All Relying Parties

List all relying party domains that have credentials on the card:

./arculusFido.sh --command=listallrps --pin=123456

Or use the convenience script:

./listallrps.sh --pin=123456

Delete Credential

Delete a specific credential from the card:

./arculusFido.sh --command=deletecredential \
  --address=127.0.1 \
  --port=5001 \
  --relyingParty=mycompanyauth.com \
  [email protected] \
  --pin=123456

Or use the convenience script:

./delete_credential.sh --address=127.0.0.1 --port=5001 --relyingParty=mycompanyauth.com [email protected] --pin=123456

Advanced Options

Server Configuration

For testing with non-Arculus FIDO2 servers (e.g., StrongKey, ImproveId), use the --server-config parameter:

./arculusFido.sh --command=register \
  --server-config='{"type":"StrongKey","config":{"svcusername":"svcfidouser","svcpassword":"Abcd1234!"}}' \
  --address=https://sk.arculus.co \
  --port=8181 \
  [email protected] \
  --relyingParty=arculus.co

Custom API Paths

For servers with custom API paths, configure them in the server config:

./arculusFido.sh --command=register \
  --server-config='{
    "type":"ArculusFido",
    "config":{
      "BeginRegistrationPath":"/proxyserv/authorize/fidoapi/register/begin",
      "CompleteRegistrationPath":"/proxyserv/authorize/fidoapi/register/complete",
      "BeginAuthenticatePath":"/proxyserv/authorize/fidoapi/authenticate/begin",
      "CompleteAuthenticatePath":"/proxyserv/authorize/fidoapi/authenticate/complete",
      "BasicAuthorization":{"username":"admin","password":"mypassword"}
    }
  }' \
  --address=https://myserver.com \
  [email protected]

SDK Mode Output

Use --sdk to get raw SDK output (useful for scripting):

./arculusFido.sh --command=register --sdk --pin=123456 [email protected]

This suppresses all logging and outputs only the raw SDK response JSON.

Logging

Control log verbosity with --logLevel:

./arculusFido.sh --command=register --logLevel=2 --pin=123456 [email protected]

Log levels:

• 0 = Verbose

• 1 = Debug

• 2 = Info

• 3 = Warning

• 4 = Error

Testing Workflows

Complete Test Sequence

Run all commands in sequence (version, reset, set PIN, register, authenticate):

./arculusFido.sh --command=all \
  --address=127.0.0.1 \
  --port=5001 \
  --pin=123456 \
  [email protected] \
  --displayName="Test User" \
  --relyingParty=localhost

Or use the convenience script:

./run_all_tests.sh --address=127.0.0.1 --port=5001 --pin=123456 [email protected] --displayName="Test User" --relyingParty=localhost

Local Development Testing

Test against a local FIDO2 server:

# Start your local FIDO2 server first (see 3.3 Local Development)

# Register a test user
./register.sh --address=127.0.0.1 --port=5001 --relyingParty=localhost --pin=123456 [email protected] --displayName="Test User"

# Authenticate the test user
./authenticate.sh --address=127.0.0.1 --port=5001 --relyingParty=localhost --pin=123456 [email protected] --displayName="Test User"

Or use the convenience script for localhost:

./all_tests_on_localhost.sh

Response Format

The CLI tool returns JSON responses in the following format:

Success Response:

{
  "status": "ok",
  "errorMessage": "",
  "responseCode": "200",
  "resultData": {
    // Command-specific data
  }
}

Error Response:

{
  "status": "failed",
  "errorMessage": "E0024R: Session expired",
  "responseCode": "408"
}

For detailed error code meanings, see 2.8 Error Codes.

Use Cases

Development Testing

Use the CLI tool during development to:

• Verify card functionality before SDK integration

• Test FIDO2 server connectivity

• Validate registration and authentication flows

• Debug credential management operations

Integration Validation

Before deploying to production:

• Test registration with your production server configuration

• Verify authentication flows work correctly

• Validate multi-tenant scenarios (if applicable)

• Test error handling and edge cases

Troubleshooting

Use the CLI tool to diagnose issues:

• Verify card is detected and functional

• Test PIN operations

• Check credential storage on the card

• Validate server connectivity and responses

Limitations

• Desktop Only: Requires PC/SC-compatible NFC reader (not available for mobile platforms)

• Testing Tool: Intended for development and testing, not production use

• Windows Admin: On Windows, must run as Administrator

• Single Card: Tests one card at a time