Desktop SDK

The Arculus FIDO SDK for Desktop provides a Java API for FIDO2 authentication using PC/SC-compatible NFC readers and Arculus cards. The SDK handles all complexity of attestation object creation, cryptographic operations, and server communication.

Key Features:

• Simple synchronous API

• PC/SC reader support (Windows, macOS, Linux)

• Direct FIDO2 server communication or card-only operations

• Built-in attestation payload construction

• Cross-platform support

Obtaining the SDK

Contact your Arculus representative to obtain the Desktop SDK distribution package. The package includes:

Component	Description
ArculusFidoSDK-1.0.0.jar	Core FIDO2 SDK (fat JAR with bundled dependencies)
ArculusPCSC-1.0.0.jar	PC/SC smart card reader interface
Sample Applications	Complete Java desktop apps demonstrating SDK usage
API Documentation	JavaDoc documentation for all public APIs

The Desktop SDK is distributed as JAR files that can be added to any Java 8+ project. See 5.4 Desktop Sample Applications for complete sample code.

2.5.1 Installation

Requirements

• Java 8 or later

• PC/SC-compatible NFC reader (e.g., OMNIKEY 5422, ACR122U)

• Physical Arculus FIDO2 card

• PC/SC libraries installed on your system

Adding the JAR Library

1. Copy the Arculus FIDO SDK JAR files to your project:

   • ArculusFidoSDK-1.0.0.jar - Core FIDO2 operations (fat JAR - includes dependencies)

   • ArculusPCSC-1.0.0.jar - PC/SC smart card reader interface

Note: The ArculusFidoSDK-1.0.0.jar is a "fat JAR" (shadow JAR) that includes all required dependencies internally. This means you may not need to add all dependencies explicitly, depending on your build configuration.

1. Add dependencies to your build configuration (Maven/Gradle):

Maven:

<dependencies>
    <!-- Arculus SDK JARs (proprietary - must be installed locally) -->
    <dependency>
        <groupId>co.arculus</groupId>
        <artifactId>arculus-fido-sdk</artifactId>
        <version>1.0.0</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/lib/ArculusFidoSDK-1.0.0.jar</systemPath>
    </dependency>
    <dependency>
        <groupId>co.arculus</groupId>
        <artifactId>arculus-pcsc</artifactId>
        <version>1.0.0</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/lib/ArculusPCSC-1.0.0.jar</systemPath>
    </dependency>
    
    <!-- 
    Note: ArculusFidoSDK-1.0.0.jar is a fat JAR that includes:
    - gson:2.10.1
    - commons-text:1.10.0
    - jna:5.14.0
    - jna-platform:5.14.0
    
    If you need different versions or want explicit dependency management,
    you can add these dependencies separately:
    -->
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
    </dependency>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-text</artifactId>
        <version>1.10.0</version>
    </dependency>
    <dependency>
        <groupId>net.java.dev.jna</groupId>
        <artifactId>jna</artifactId>
        <version>5.14.0</version>
    </dependency>
    <dependency>
        <groupId>net.java.dev.jna</groupId>
        <artifactId>jna-platform</artifactId>
        <version>5.14.0</version>
    </dependency>
</dependencies>

Gradle:

dependencies {
    // Arculus SDK JARs (proprietary - must be in libs/ directory)
    implementation files('libs/ArculusFidoSDK-1.0.0.jar')
    implementation files('libs/ArculusPCSC-1.0.0.jar')
    
    // 
    // Note: ArculusFidoSDK-1.0.0.jar is a fat JAR that includes:
    // - gson:2.10.1
    // - commons-text:1.10.0
    // - jna:5.14.0
    // - jna-platform:5.14.0
    //
    // If you need different versions or want explicit dependency management,
    // you can add these dependencies separately:
    //
    // implementation 'com.google.code.gson:gson:2.10.1'
    // implementation 'org.apache.commons:commons-text:1.10.0'
    // implementation 'net.java.dev.jna:jna:5.14.0'
    // implementation 'net.java.dev.jna:jna-platform:5.14.0'
}

Dependency Strategy:

• Fat JAR Approach (Recommended for simplicity): The ArculusFidoSDK-1.0.0.jar includes all dependencies. Just add the JAR files and you're ready to go.

• Explicit Dependencies (For version control): If you need specific versions or want to manage dependencies explicitly, add the dependencies listed above. The fat JAR will still work, but your explicit dependencies will take precedence if there are version conflicts.

Basic Setup

import co.arculus.fido.ArculusFido;
import co.arculus.fido.ArculusFidoServer;
import co.arculus.pcsc.PCSC;

public class FidoApp {
    private ArculusFido arculusFido;
    private PCSC pcsc;
    
    public void initialize() throws Exception {
        // List available PC/SC readers
        String[] readers = PCSC.listPCSCReaders();
        if (readers == null || readers.length == 0) {
            throw new Exception("No PC/SC readers found");
        }
        
        // Use first available reader
        String selectedReader = readers[0];
        
        // Initialize PC/SC and Arculus SDK
        pcsc = new PCSC(selectedReader);
        arculusFido = new ArculusFido(pcsc);
    }
}

2.5.2 Registration Flow

Registration creates a new FIDO2 credential and stores it on both the Arculus card and the FIDO server.

The Desktop SDK supports two deployment patterns: client-direct (direct FIDO2 server communication) and backend-proxied (backend services proxy FIDO2 requests).

Client-Direct Pattern

In client-direct deployments, the desktop application communicates directly with the FIDO2 server.

API Signature

public String register(
    ArculusFidoServer fidoServer,
    String pin,
    String username,
    String displayName,
    String relyingParty,
    boolean resetDevice,
    String registrationInfo
)

Parameters

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
relyingParty	String	Relying party ID (domain)
resetDevice	boolean	If true, resets card and sets PIN
registrationInfo	String	Optional device metadata JSON

Example

public void registerUser() throws Exception {
    ArculusFidoServer fidoServer = new ArculusFidoServer(
        "fido.example.com",
        "fidoapi/certify/attestation/options",
        "fidoapi/certify/attestation/result",
        "fidoapi/certify/assertion/options",
        "fidoapi/certify/assertion/result"
    );
    
    // Optional: Add authentication header
    fidoServer.setRequestProperty("Authorization", "Basic dXNlcjpwYXNz");
    
    String deviceInfo = "{\"deviceinfo\": \"Desktop PC\", \"serial\": \"XYZ-123\"}";
    
    String result = arculusFido.register(
        fidoServer,
        "123456",                    // pin
        "[email protected]",          // username
        "John's Desktop",            // displayName
        "example.com",               // relyingParty
        false,                       // resetDevice
        deviceInfo                   // registrationInfo
    );
    
    // Parse result JSON
    // Response: {"status": "ok", "errorMessage": "", "responseCode": 200}
    System.out.println("Registration: " + result);
}

Backend-Proxied Pattern

In backend-proxied deployments, the desktop application communicates with backend services that proxy FIDO2 requests. This provides enhanced security by isolating the FIDO2 server from client applications.

API Signature

public String registerCardOnly(
    String pin,
    String username,
    String displayName,
    String relyingParty,
    String challenge,
    String origin
) throws ArculusFidoException

Parameters

Parameter	Type	Description
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
relyingParty	String	Relying party ID (domain)
challenge	String	Base64-encoded challenge from backend's /register/begin response
origin	String	Origin URL for clientDataJSON (typically FIDO2 server URL)

Note: Unlike authenticateCardOnly(), registerCardOnly() takes challenge and origin directly rather than an optionsResponse object.

Helper Functions: The backend-proxied pattern requires helper classes and functions for backend communication and response transformation. See Backend Integration Helpers for complete implementations of BackendApiClient and createOptionsResponseFromBackend().

Phase 1: Get Challenge from Backend

// Initialize backend client (see Backend Integration Helpers for implementation)
BackendApiClient backendClient = new BackendApiClient(backendUrl);
String displayName = username; // Use username as displayName, or provide custom value
JsonObject backendResponse = backendClient.registerBegin(username, displayName, rpId);

// Extract challenge and FIDO2 server response from backend
JsonObject fidoServerResponse = backendResponse.getAsJsonObject("fidoServerResponse");
String challenge = fidoServerResponse.get("challenge").getAsString();
String fido2ServerOrigin = backendResponse.get("fido2ServerOrigin").getAsString();
// Note: Session cookies are automatically stored by backendClient.registerBegin()

Phase 2: Perform Card Registration

// Perform card-only registration (no server communication)
// registerCardOnly() takes challenge and origin directly (not optionsResponse)
String cardResponseJson = arculusFido.registerCardOnly(
    pin,
    username,
    displayName,  // Display name for the user
    rpId,         // Relying party identifier
    challenge,    // Base64-encoded challenge from backend
    fido2ServerOrigin  // Origin URL for clientDataJSON (typically FIDO2 server URL)
);

// Parse card response
JsonObject cardResponseData = JsonParser.parseString(cardResponseJson).getAsJsonObject();

Phase 3: Complete Registration with Backend

// Send card response to backend for FIDO2 server validation
// Note: Session cookies are automatically included from Phase 1
JsonObject completeResponse = backendClient.registerComplete(
    username, 
    cardResponseData
);

// Check if registration succeeded
boolean success = completeResponse.has("status") && 
    "success".equals(completeResponse.get("status").getAsString());

Note: In backend-proxied deployments, the desktop application performs only card operations. All FIDO2 server communication is handled by your backend services. Unlike authenticateCardOnly(), registerCardOnly() takes challenge and origin directly rather than an optionsResponse object.

Registration Sequence Diagrams

Client-Direct Pattern

Backend-Proxied Pattern

2.5.3 Authentication Flow

Authentication verifies a user's credential stored on the Arculus card.

The Desktop SDK supports two deployment patterns: client-direct (direct FIDO2 server communication) and backend-proxied (backend services proxy FIDO2 requests).

Client-Direct Pattern

In client-direct deployments, the desktop application communicates directly with the FIDO2 server.

API Signature

public String authenticate(
    ArculusFidoServer fidoServer,
    String pin,
    String username,
    String displayName,
    String relyingParty
)

Parameters

Parameter	Type	Description
fidoServer	ArculusFidoServer	Server configuration object
pin	String	Card PIN
username	String	User identifier
displayName	String	Human-readable name
relyingParty	String	Relying party ID (must match registration)

Example

public void authenticateUser() throws Exception {
    ArculusFidoServer fidoServer = new ArculusFidoServer(
        "fido.example.com",
        "fidoapi/certify/attestation/options",
        "fidoapi/certify/attestation/result",
        "fidoapi/certify/assertion/options",
        "fidoapi/certify/assertion/result"
    );
    
    String result = arculusFido.authenticate(
        fidoServer,
        "123456",                    // pin
        "[email protected]",          // username
        "John's Desktop",            // displayName
        "example.com"                // relyingParty
    );
    
    // Parse result JSON
    // Response: {"status": "ok", "errorMessage": "", "responseCode": 200}
    System.out.println("Authentication: " + result);
}

Backend-Proxied Pattern

In backend-proxied deployments, the desktop application communicates with backend services that proxy FIDO2 requests. This provides enhanced security by isolating the FIDO2 server from client applications.

API Signature

public AuthenticateCardSignResponse authenticateCardOnly(
    String pin,
    String username,
    String relyingParty,
    ArculusFidoOptionsAuthorizationResponse optionsResponse
) throws ArculusFidoException

Parameters

Parameter	Type	Description
pin	String	Card PIN
username	String	User identifier
relyingParty	String	Relying party ID (must match registration)
optionsResponse	ArculusFidoOptionsAuthorizationResponse	Pre-constructed options response containing challenge from backend

Returns: AuthenticateCardSignResponse object containing id, rawId, authdataBase64, and signatureBase64.

Note: Unlike registerCardOnly(), authenticateCardOnly() uses an optionsResponse object that must be constructed from the backend's response.

Phase 1: Get Challenge from Backend

// Call your backend API to initiate authentication
BackendApiClient backendClient = new BackendApiClient(backendUrl);
JsonObject backendResponse = backendClient.authenticateBegin(username, rpId);

// Extract challenge and FIDO2 server response from backend
JsonObject fidoServerResponse = backendResponse.getAsJsonObject("fidoServerResponse");
String challenge = fidoServerResponse.get("challenge").getAsString();
String fido2ServerOrigin = backendResponse.get("fido2ServerOrigin").getAsString();
String sessionId = backendResponse.has("sessionId") ? 
    backendResponse.get("sessionId").getAsString() : null;
// Note: Session cookies are automatically stored by backendClient.authenticateBegin()

Phase 2: Perform Card Authentication

// Create options response from backend response
// Helper function implementation: see [Backend Integration Helpers](5.8-backend-integration-helpers.md)
ArculusFidoOptionsAuthorizationResponse optionsResponse = 
    createOptionsResponseFromBackend(
        fidoServerResponse, 
        challenge, 
        rpId, 
        fido2ServerOrigin
    );

// Perform card-only authentication (no server communication)
AuthenticateCardSignResponse cardResponse = arculusFido.authenticateCardOnly(
    pin, 
    username, 
    rpId, 
    optionsResponse
);

// Build FIDO2 authentication response
JsonObject fido2Response = new JsonObject();
fido2Response.addProperty("type", "public-key");
fido2Response.addProperty("id", cardResponse.getId());
fido2Response.addProperty("rawId", cardResponse.getRawId());

JsonObject responseData = new JsonObject();
responseData.addProperty("authenticatorData", cardResponse.getAuthdataBase64());
responseData.addProperty("signature", cardResponse.getSignatureBase64());
responseData.addProperty("clientDataJSON", optionsResponse.getClientDataJSONbase64());

fido2Response.add("response", responseData);

Phase 3: Complete Authentication with Backend

// Send card response to backend for FIDO2 server validation
JsonObject completeResponse = backendClient.authenticateComplete(
    fido2Response, 
    sessionId, 
    username
);

// Check if authentication succeeded
boolean success = completeResponse.has("status") && 
    "success".equals(completeResponse.get("status").getAsString());

Note: The authenticateCardOnly() method performs only card operations and returns an AuthenticateCardSignResponse object containing the real signature and authenticator data. All FIDO2 server communication is handled by your backend services.

Authentication Sequence Diagrams

Client-Direct Pattern

Backend-Proxied Pattern

2.5.4 PIN Management

Set PIN (Reset Card)

Resets the card and sets a new PIN. Warning: This erases all credentials on the card.

public String setPin(String pin)

Example:

public void resetCard() throws Exception {
    String result = arculusFido.setPin("654321");
    // Response: {"status": "ok", "errorMessage": "", "responseCode": 200}
    System.out.println("Set PIN: " + result);
}

Change PIN (Preserve Data)

Changes the PIN while preserving all credentials on the card.

public String changePin(String oldPin, String newPin)

Example:

public void updatePin() throws Exception {
    String result = arculusFido.changePin("123456", "654321");
    // Response: {"status": "ok", "errorMessage": "", "responseCode": 200}
    System.out.println("Change PIN: " + result);
}

2.5.5 Reader Management

List Available Readers

String[] readers = PCSC.listPCSCReaders();
if (readers != null && readers.length > 0) {
    for (String reader : readers) {
        System.out.println("Reader: " + reader);
    }
}

Select Specific Reader

// Reinitialize SDK with selected reader
String selectedReader = "OMNIKEY 5422CL 0";
pcsc = new PCSC(selectedReader);
arculusFido = new ArculusFido(pcsc);

Note: For OMNIKEY readers, prefer the contactless (CL) interface for NFC operations.

2.5.6 Error Handling

Response Format

All methods return a JSON string:

{
  "status": "ok",
  "errorMessage": "",
  "responseCode": 200
}

Or on failure:

{
  "status": "failed",
  "errorMessage": "E2017R: Invalid signature.",
  "responseCode": 401
}

Error Handling Example

try {
    String result = arculusFido.authenticate(fidoServer, pin, username, displayName, rpId);
    
    JsonObject json = JsonParser.parseString(result).getAsJsonObject();
    String status = json.get("status").getAsString();
    String errorMessage = json.get("errorMessage").getAsString();
    int responseCode = json.get("responseCode").getAsInt();
    
    if ("ok".equals(status)) {
        System.out.println("Authentication successful!");
        return;
    }
    
    // Handle specific error codes
    if (responseCode >= 600 && responseCode <= 617) {
        // Card communication errors
        System.out.println("Card error: " + errorMessage);
    } else if (responseCode == 401) {
        System.out.println("Authentication failed: " + errorMessage);
    } else if (responseCode == 403) {
        System.out.println("User not found. Please register first.");
    } else if (responseCode == 408) {
        System.out.println("Session expired. Please try again.");
    } else {
        System.out.println("Error: " + errorMessage);
    }
    
} catch (Exception e) {
    System.err.println("Exception: " + e.getMessage());
    e.printStackTrace();
}

Common Error Codes

Code	Description	Resolution
600	Tag lost	Keep card on reader during operation
602	No credentials	Register card first
608	PIN failed	Check PIN is correct
611	Set PIN failed	Retry operation
615	Reader not available	Check PC/SC reader connection
E2017R	Invalid signature	Credential may be corrupted
E2019R	Unknown credential	User not registered

See 2.7 Error Codes for complete reference.

ArculusFidoServer Class

Configure server connection details:

// Simple constructor (uses default endpoints)
ArculusFidoServer fidoServer = new ArculusFidoServer("fido.example.com");

// With custom endpoints
ArculusFidoServer fidoServer = new ArculusFidoServer(
    "fido.example.com",
    "fidoapi/certify/attestation/options",
    "fidoapi/certify/attestation/result",
    "fidoapi/certify/assertion/options",
    "fidoapi/certify/assertion/result"
);

// Set custom headers (e.g., API key or Basic Auth)
fidoServer.setRequestProperty("Authorization", "Basic dXNlcjpwYXNz");
fidoServer.setRequestProperty("X-API-Key", "your-api-key");

// Set device info for registration
fidoServer.setDeviceinfo("{\"model\": \"Desktop PC\"}");

Server Methods

Method	Description
setRequestProperty(key, value)	Add custom HTTP header
setDeviceinfo(json)	Set device metadata for registration

Helper Classes

ArculusFidoOptionsAuthorizationResponse

Used in backend-proxied deployments to construct options from backend responses:

ArculusFidoOptionsAuthorizationResponse optionsResponse = 
    new ArculusFidoOptionsAuthorizationResponse();
optionsResponse.setChallenge(challenge);
optionsResponse.setRpId(rpId);
optionsResponse.setAllowList(allowList);  // Optional
optionsResponse.setClienthash(clientHash);
optionsResponse.setClientDataJSONbase64(clientDataJSONbase64);
optionsResponse.setRPIDhash(rpIdHash);

AuthenticateCardSignResponse

Returned by authenticateCardOnly() method:

AuthenticateCardSignResponse response = arculusFido.authenticateCardOnly(...);

String id = response.getId();
String rawId = response.getRawId();
String authdataBase64 = response.getAuthdataBase64();
String signatureBase64 = response.getSignatureBase64();

Complete Sample Application

For complete Desktop sample applications demonstrating both client-direct and backend-proxied deployment patterns, see 5.4 Desktop Sample Applications in the Appendix.