Android SDK

The Arculus FIDO SDK for Android provides a simple API for FIDO2 authentication using NFC-enabled Arculus cards. The SDK handles all complexity of attestation object creation, cryptographic operations, and server communication.

Key Features:

• Simple 4-method API

• Callback-based async operations

• Automatic NFC lifecycle management

• Built-in attestation payload construction

• No Activity transitions required

Obtaining the SDK

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

Component	Description
ArculusFidoSDK-release.aar	The main SDK library (AAR format)
Sample Applications	Complete Android sample apps demonstrating SDK usage
API Documentation	JavaDoc documentation for all public APIs

The AAR library is self-contained and includes all necessary dependencies (Kotlin runtime, AndroidX libraries, and the bundled Java SDK). See 5.3 Android Sample Applications for complete sample code.

2.4.1 Installation

Requirements

• Android SDK 26+ (Android 8.0 Oreo)

• Android Studio Arctic Fox or later

• Physical device with NFC (Emulator not supported)

Adding the AAR Library

1. Copy ArculusFidoSDK-release.aar (or ArculusFidoSDK.aar) to your project's libs/ directory

2. Add dependencies to build.gradle (app module):

dependencies {
    // Arculus FIDO SDK AAR (includes all required dependencies)
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    
    // Note: The AAR is self-contained and includes:
    // - Java SDK fat JAR (with gson, commons-text, jna, jna-platform)
    // - Kotlin stdlib and parcelize runtime
    // - AndroidX dependencies (appcompat, material, core-ktx)
    // 
    // No additional dependencies are required unless you need:
    // - Kotlin coroutines (for async operations)
    // - Guava (for additional utilities)
    // 
    // If you need these, add them explicitly:
    // implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.0'
    // implementation 'com.google.guava:guava:31.1-jre'
}

1. Add NFC permission to AndroidManifest.xml:

<uses-permission android:name="android.permission.NFC" />

Note: The Arculus FIDO SDK AAR is self-contained and includes all necessary dependencies:

• Java SDK fat JAR (bundled internally) includes: gson, commons-text, jna, jna-platform

• Kotlin runtime (kotlin-stdlib, kotlin-parcelize-runtime) is included

• AndroidX libraries (appcompat, material, core-ktx) are included

You only need to add additional dependencies if your application requires specific versions or additional libraries like Kotlin coroutines or Guava.

Basic Setup

import co.arculus.fido.android.ArculusFidoAsync;
import co.arculus.android.ArculusFidoResultCallback;
import co.arculus.fido.ArculusFidoServer;

public class MainActivity extends AppCompatActivity implements ArculusFidoResultCallback {
    private ArculusFidoAsync arculusFido = null;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // Initialize SDK
        arculusFido = ArculusFidoAsync.createInstance(this, this);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // Clean up SDK resources
        ArculusFidoAsync.destroyInstance();
    }
}

2.4.2 Registration Flow

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

The Android 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 Android app communicates directly with the FIDO2 server.

API Signature

public void 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() {
    ArculusFidoServer fidoServer = new ArculusFidoServer("fido.example.com");
    fidoServer.setBeginRegistrationPath("fidoapi/certify/attestation/options", null);
    fidoServer.setCompleteRegistrationPath("fidoapi/certify/attestation/result", null);
    
    // Optional: Add authentication header
    fidoServer.setRequestProperty("Authorization", "Basic dXNlcjpwYXNz");
    
    String deviceInfo = "{\"deviceinfo\": \"Samsung Galaxy S24\", \"serial\": \"XYZ-123\"}";
    
    arculusFido.register(
        fidoServer,
        "123456",                    // pin
        "[email protected]",          // username
        "John's Android",            // displayname
        "example.com",               // relyingParty
        false,                       // resetDevice
        deviceInfo                   // registrationInfo
    );
}

@Override
public void registerResult(String response) {
    runOnUiThread(() -> {
        // Response: {"status": "ok", "errorMessage": "", "responseCode": 200}
        Log.d("FIDO", "Registration: " + response);
        showMessage("Registration: " + response);
    });
}

Backend-Proxied Pattern

In backend-proxied deployments, the Android app communicates with backend services that proxy FIDO2 requests.

Why Use Backend-Proxied?

Choose the backend-proxied pattern when:

Requirement	Benefit
Security isolation	FIDO2 server is not directly accessible from the internet
Business logic	Add custom validation, logging, or processing before/after FIDO2 operations
Audit trails	Centralized logging and monitoring of all authentication events
Session management	Backend controls session cookies and can integrate with existing auth systems
Rate limiting	Backend can implement throttling and abuse prevention

Trade-off: Backend-proxied requires implementing a 3-phase flow (begin → card operation → complete) instead of direct SDK calls, but provides greater control and security.

Session Cookies (Important)

FIDO2 authentication is a two-step process (begin + complete). The server uses session cookies to link these steps:

1. Begin call: Server generates a challenge and stores it in a session, returning a session cookie

2. Complete call: Server retrieves the challenge using the session cookie to verify the response

Without proper cookie handling:

• The "complete" call won't find the challenge from the "begin" call

• You'll get "Session expired" (E0024R) errors

Ensure your HTTP client stores cookies from the "begin" response and sends them with the "complete" request.

API Signature

public String registerCardOnly(
    String pin,
    String username,
    String displayName,
    String rpId,
    String challenge,
    String origin
)

Parameters

Parameter	Type	Description
pin	String	6+ digit PIN for the card
username	String	User identifier (e.g., email)
displayName	String	Human-readable name
rpId	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 FidoOptionsHelper.

Phase 1: Get Challenge from Backend

// Initialize backend client (see Backend Integration Helpers for implementation)
BackendApiClient backendClient = new BackendApiClient(appConfig);
String username = sessionManager.getUsername();
String displayName = username; // Use username as displayName, or provide custom value
String rpId = appConfig.getRpId();

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)
ArculusFidoAsync arculusFido = ArculusFidoAsync.createInstance(context, callback);
String cardResponseJson = arculusFido.registerCardOnly(
    pin, 
    username, 
    displayName,  // Display name for the user
    rpId, 
    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: The registerCardOnly() method performs only card operations and does not communicate with the FIDO2 server. 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.4.3 Authentication Flow

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

The Android 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 Android app communicates directly with the FIDO2 server.

API Signature

public void 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() {
    ArculusFidoServer fidoServer = new ArculusFidoServer("fido.example.com");
    fidoServer.setBeginAuthenticatePath("fidoapi/certify/assertion/options", null);
    fidoServer.setCompleteAuthenticatePath("fidoapi/certify/assertion/result", null);
    
    arculusFido.authenticate(
        fidoServer,
        "123456",                    // pin
        "[email protected]",          // username
        "John's Android",            // displayName
        "example.com"                // relyingParty
    );
}

@Override
public void authenticateResult(String response) {
    runOnUiThread(() -> {
        // Response: {"status": "ok", "errorMessage": "", "responseCode": 200}
        Log.d("FIDO", "Authentication: " + response);
        showMessage("Authentication: " + response);
    });
}

Backend-Proxied Pattern

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

API Signature

public String authenticateCardOnly(
    String pin,
    String username,
    String rpId,
    ArculusFidoOptionsAuthorizationResponse optionsResponse
)

Parameters

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

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(appConfig);
String username = sessionManager.getUsername();
String rpId = appConfig.getRpId();

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;

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 = 
    FidoOptionsHelper.createFromBackendResponse(
        fidoServerResponse, 
        challenge, 
        rpId, 
        fido2ServerOrigin
    );

// Perform card-only authentication (no server communication)
ArculusFidoAsync arculusFido = ArculusFidoAsync.createInstance(context, callback);
String cardResponseJson = arculusFido.authenticateCardOnly(
    pin, 
    username, 
    rpId, 
    optionsResponse
);

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

Phase 3: Complete Authentication with Backend

// Send card response to backend for FIDO2 server validation
// Note: Session cookies are automatically included from Phase 1
JsonObject completeResponse = backendClient.authenticateComplete(
    cardResponseData, 
    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 does not communicate with the FIDO2 server. All FIDO2 server communication is handled by your backend services.

Authentication Sequence Diagrams

Client-Direct Pattern

Backend-Proxied Pattern

2.4.4 Reset Flow

Set PIN (Reset Card)

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

public void setPin(String pin)

Example:

public void resetCard() {
    arculusFido.setPin("654321");
}

@Override
public void setPinResult(String response) {
    runOnUiThread(() -> {
        showMessage("Set PIN: " + response);
    });
}

Change PIN (Preserve Data)

Changes the PIN while preserving all credentials on the card.

public void changePin(String oldPin, String newPin)

Example:

public void updatePin() {
    arculusFido.changePin("123456", "654321");
}

@Override
public void changePinResult(String response) {
    runOnUiThread(() -> {
        showMessage("Change PIN: " + response);
    });
}

2.4.5 Error Handling

Callback Interface

Implement ArculusFidoResultCallback to receive all operation results:

public interface ArculusFidoResultCallback {
    default void registerResult(String response) {}
    default void authenticateResult(String response) {}
    default void changePinResult(String response) {}
    default void setPinResult(String response) {}
}

Response Format

All callbacks receive a JSON string:

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

Or on failure:

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

Error Handling Example

@Override
public void registerResult(String response) {
    runOnUiThread(() -> {
        try {
            JSONObject json = new JSONObject(response);
            String status = json.optString("status", "");
            String errorMessage = json.optString("errorMessage", "");
            int responseCode = json.optInt("responseCode", 0);
            
            if ("ok".equals(status)) {
                showSuccess("Registration successful!");
                return;
            }
            
            // Handle specific error codes
            if (responseCode >= 600 && responseCode <= 617) {
                // Card communication errors
                showError("Please hold your card steady and try again");
            } else if (responseCode == 401) {
                showError("Authentication failed: " + errorMessage);
            } else if (responseCode == 403) {
                showError("User not found. Please register first.");
            } else if (responseCode == 408) {
                showError("Session expired. Please try again.");
            } else {
                showError("Error: " + errorMessage);
            }
            
        } catch (JSONException e) {
            showError("Invalid response format");
        }
    });
}

Common Error Codes

Code	Description	Resolution
600	Tag lost	Hold card steady during NFC
602	No credentials	Register card first
608	PIN failed	Check PIN is correct
611	Set PIN failed	Retry operation
615	NFC not available	Use device with NFC
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 port
ArculusFidoServer fidoServer = new ArculusFidoServer("fido.example.com", (short) 5001);

// With custom endpoints
ArculusFidoServer fidoServer = new ArculusFidoServer(
    "fido.example.com",
    "custom/registration/begin",
    "custom/registration/complete",
    "custom/authentication/begin",
    "custom/authentication/complete"
);

// 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\": \"Pixel 8\"}");

Server Methods

Method	Description
setBeginRegistrationPath(path, params)	Set registration options endpoint
setCompleteRegistrationPath(path, params)	Set registration result endpoint
setBeginAuthenticatePath(path, params)	Set authentication options endpoint
setCompleteAuthenticatePath(path, params)	Set authentication result endpoint
setRequestProperty(key, value)	Add custom HTTP header
setDeviceinfo(json)	Set device metadata for registration

Complete Sample Application

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