iOS SDK

The Arculus FIDO SDK for iOS 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

• Async/await support

• Automatic NFC session management

• Built-in attestation payload construction

Obtaining the SDK

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

Component	Description
ArculusFidoSDKFramework.xcframework	The main SDK framework for iOS
ArculusFidoSDK (Swift Package)	Swift Package Manager distribution (Xcode 16+)
Sample Applications	Complete iOS sample apps demonstrating SDK usage
API Documentation	SwiftDoc documentation for all public APIs

The SDK is distributed as either a zipped XCFramework or a Swift binary package. See 5.2 iOS Sample Applications for complete sample code.

2.3.1 Installation

Requirements

• iOS 14.0+

• Xcode 14.0+ (Xcode 16+ recommended for Swift Package Manager support)

• Physical device with NFC (Simulator not supported)

Installation Methods

The Arculus FIDO SDK for iOS can be integrated using either XCFramework (manual) or Swift Package Manager (Xcode 16+).

Method 1: XCFramework (Manual Integration)

1. Download the ArculusFidoSDKFramework.zip

2. Unzip the archive to reveal ArculusFidoSDKFramework.xcframework

3. Drag the .xcframework folder into your Xcode project's Frameworks directory

4. Configure Build Phases:

   • Go to your target's Build Phases

   • Under Embed Frameworks, click +

   • Add ArculusFidoSDKFramework.xcframework

5. Import in code:

import ArculusFidoSDKFramework

Method 2: Swift Package Manager (Xcode 16+)

1. Add Package Dependency:

   • In Xcode, go to File → Add Package Dependencies...

   • Enter the package URL or local path to ArculusFidoSDK binary Swift package

   • Select the version or branch you want to use

2. Import in code:

import ArculusFidoSDK

Note: The Swift Package Manager option uses a binary Swift package that wraps the XCFramework. Both methods require the same Build Phases configuration (Embed Frameworks) for device builds.

Basic Setup

import UIKit
import ArculusFidoSDKFramework

class ViewController: UIViewController {
    private var arculusFido: ArculusFido = ArculusFido()

    override func viewDidLoad() {
        super.viewDidLoad()
        // SDK is ready to use
    }
}

2.3.2 Registration Flow

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

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

API Signature

public func registerUser(
    fidoServer: ArculusFidoServer,
    pin: String,
    username: String,
    displayName: String,
    relyingParty: String,
    resetDevice: Bool = false,
    registrationInfo: String? = nil
) async -> String

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	Bool	If true, resets card and sets PIN
registrationInfo	String?	Optional device metadata JSON

Example

func register() {
    Task {
        let fidoServer = ArculusFidoServer(domain: "fido.example.com")
        fidoServer.registrationBeginEndpoint = "fidoapi/certify/attestation/options"
        fidoServer.registrationCompleteEndpoint = "fidoapi/certify/attestation/result"
        
        let result = await arculusFido.registerUser(
            fidoServer: fidoServer,
            pin: "123456",
            username: "[email protected]",
            displayName: "John's iPhone",
            relyingParty: "example.com",
            resetDevice: false,
            registrationInfo: "{\"deviceinfo\": \"iPhone 15 Pro\"}"
        )
        
        // Parse result JSON
        print(result)
    }
}

Backend-Proxied Pattern

In backend-proxied deployments, the iOS 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 func registerCardOnly(
    pin: String,
    username: String,
    displayName: String,
    rpId: String,
    challenge: String,
    origin: String
) async throws -> String

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 createOptionsResponseFromBackend().

Phase 1: Get Challenge from Backend

// Initialize backend client (see Backend Integration Helpers for implementation)
let backendClient = BackendApiClient(baseUrl: "https://your-backend.com")

// Call your backend API to initiate registration
let backendResponse = try await backendClient.registerBegin(
    username: username,
    displayName: displayName,  // Use username as displayName, or provide custom value
    rpId: rpId
)

// Extract challenge and FIDO2 server response from backend
guard let fidoServerResponse = backendResponse["fidoServerResponse"] as? [String: Any],
      let challenge = fidoServerResponse["challenge"] as? String,
      let fido2ServerOrigin = backendResponse["fido2ServerOrigin"] as? String else {
    // Handle error
    return
}
// 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)
let cardResponseJson = try await arculusFido.registerCardOnly(
    pin: pin,
    username: username,
    displayName: displayName,  // Display name for the user
    rpId: rpId,
    challenge: challenge,   // Base64-encoded challenge from backend
    origin: fido2ServerOrigin  // Origin URL for clientDataJSON (typically FIDO2 server URL)
)

// Parse card response
let cardResponseData = try JSONSerialization.jsonObject(with: cardResponseJson.data(using: .utf8)!) as! [String: Any]

Phase 3: Complete Registration with Backend

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

// Check if registration succeeded
let success = completeResponse["status"] as? String == "success"

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.3.3 Authentication Flow

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

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

API Signature

public func authenticateUser(
    fidoServer: ArculusFidoServer,
    pin: String,
    username: String,
    displayName: String,
    relyingParty: String
) async -> String

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

func authenticate() {
    Task {
        let fidoServer = ArculusFidoServer(domain: "fido.example.com")
        fidoServer.authorizationBeginEndpoint = "fidoapi/certify/assertion/options"
        fidoServer.authorizationCompleteEndpoint = "fidoapi/certify/assertion/result"
        
        let result = await arculusFido.authenticateUser(
            fidoServer: fidoServer,
            pin: "123456",
            username: "[email protected]",
            displayName: "John's iPhone",
            relyingParty: "example.com"
        )
        
        print(result)
    }
}

Backend-Proxied Pattern

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

API Signature

public func authenticateCardOnly(
    pin: String,
    username: String,
    rpId: String,
    optionsResponse: ArculusFidoOptionsAuthorizationResponse
) async throws -> String

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
let backendResponse = try await backendClient.authenticateBegin(
    username: username,
    rpId: rpId
)

// Extract challenge and FIDO2 server response from backend
guard let fidoServerResponse = backendResponse["fidoServerResponse"] as? [String: Any],
      let challenge = fidoServerResponse["challenge"] as? String,
      let fido2ServerOrigin = backendResponse["fido2ServerOrigin"] as? String else {
    // Handle error
    return
}
let sessionId = backendResponse["sessionId"] as? String
// 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)
let optionsResponse = try createOptionsResponseFromBackend(
    fidoServerResponse: fidoServerResponse,
    challenge: challenge,
    rpId: rpId,
    fido2ServerOrigin: fido2ServerOrigin
)

// Perform card-only authentication (no server communication)
let cardResponseJson = try await arculusFido.authenticateCardOnly(
    pin: pin,
    username: username,
    rpId: rpId,
    optionsResponse: optionsResponse
)

// Parse card response
let cardResponseData = try JSONSerialization.jsonObject(with: cardResponseJson.data(using: .utf8)!) as! [String: Any]

Phase 3: Complete Authentication with Backend

// Send card response to backend for FIDO2 server validation
// Note: Session cookies are automatically included from Phase 1
let completeResponse = try await backendClient.authenticateComplete(
    cardResponseData: cardResponseData,
    sessionId: sessionId,
    username: username
)

// Check if authentication succeeded
let success = completeResponse["status"] as? String == "success"

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.3.4 Reset Flow

Set PIN (Reset Card)

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

public func setPin(pin: String) async throws -> String

Example:

func resetCard() {
    Task {
        let result = await arculusFido.setPin(pin: "654321")
        print(result)
    }
}

Change PIN (Preserve Data)

Changes the PIN while preserving all credentials on the card.

public func changePin(oldPin: String, newPin: String) async -> String

Example:

func updatePin() {
    Task {
        let result = await arculusFido.changePin(oldPin: "123456", newPin: "654321")
        print(result)
    }
}

2.3.5 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

func handleResult(response: String) {
    guard let data = response.data(using: .utf8),
          let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
        showError("Invalid response format")
        return
    }
    
    let status = json["status"] as? String ?? ""
    let errorMessage = json["errorMessage"] as? String ?? ""
    let responseCode = json["responseCode"] as? Int ?? 0
    
    if status == "ok" {
        showSuccess("Operation completed successfully")
        return
    }
    
    // Handle specific error codes
    switch responseCode {
    case 600...617:
        // Card communication errors
        showError("Please hold your card steady and try again")
    case 401:
        showError("Authentication failed: \(errorMessage)")
    case 403:
        showError("User not found. Please register first.")
    case 408:
        showError("Session expired. Please try again.")
    default:
        showError("Error: \(errorMessage)")
    }
}

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:

// Basic initialization
let server = ArculusFidoServer(domain: "fido.example.com")

// With custom port
let server = ArculusFidoServer(displayName: "fido.example.com", port: 5001)

// With custom endpoints
let server = ArculusFidoServer(
    domain: "fido.example.com",
    beginRegistrationPath: "custom/register/begin",
    completeRegistrationPath: "custom/register/complete",
    beginAuthenticationPath: "custom/auth/begin",
    completeAuthenticationPath: "custom/auth/complete"
)

// Set custom headers
server.setRequestProperty(key: "Authorization", value: "Bearer token123")

Server Properties

Property	Type	Description
registrationBeginEndpoint	String	Registration options endpoint
registrationCompleteEndpoint	String	Registration result endpoint
authorizationBeginEndpoint	String	Authentication options endpoint
authorizationCompleteEndpoint	String	Authentication result endpoint

Complete Sample Application

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