FIDO2 APIs for Native iOS Applications

Ideem's FIDO2 Authenticator interfaces can be used to integrate with an existing Relying Party infrastructure, where you host the Relying Party server and manage the storage of credential_ids and public keys associated with enrollments, generate challenges, and verify signed challenges.

These interfaces allow you to determine if a user has already been enrolled (cryptographically bound to the device), create an enrollment if they have not, or verify them. FIDO2 Authenticator WebAuthn functions can be used to provide a silent second factor after strong authentication, as well as reverification when needed for transactions requiring step up authentication.

Interface Definitions

Jump to: Swift, Objective-C

Getting the version number of the SDK library: FIDO2Client.versionString

To retrieve the version number of the SDK library use the class property FIDO2Client.versionString. It will return the version number in semantic versioning format, major.minor.patch.

Swift

Retrieving Enrollment Status (Attestation): FIDO2Client.webauthnRetrieve()

There are two versions of this method: one for retrieving credentials for the current user, and another for retrieving credentials for a specific user.

For Current User

The webauthnRetrieve(completion:) method checks if the current user has previously registered credentials on this device and retrieves the enrollment status.

Usage

client.webauthnRetrieve { data, metadata, error in
    if let data = data {
        // Process attestation data
        if let rawId = data["rawId"] as? String {
            // Use the credential ID
        }
    } else if let error = error {
        // Handle error
    }
}

Parameters

Returns
The completion handler provides the following parameters:

For Specific User

The webauthnRetrieve(forUser:completion:) method checks if a specific user has previously registered credentials on this device and retrieves the enrollment status.

Usage

let userId = "user123" // Unique identifier for the user
client.webauthnRetrieve(forUser: userId) { data, metadata, error in
    if let data = data {
        // Process attestation data for specific user
        if let rawId = data["rawId"] as? String {
            // Use the credential ID for this specific user
        }
    } else if let error = error {
        // Handle error
    }
}

Parameters

Returns
The completion handler provides the following parameters:

Enrolling (Attestation): FIDO2Client.webauthnCreate()

The webauthnCreate(options:completion:) method initiates the creation of a new credential object, using the specified PublicKeyCredentialCreationOptions. The generated credential object can be stored securely for future authentication.

The response follows the PublicKeyCredential format from the WebAuthn standard.

Refer to Mozilla's online documentation on PublicKeyCredentialCreationOptions or to the W3C standard Options for Credential Creation. For response format, see the W3C standard PublicKeyCredential interface.

Usage

// Create options dictionary following FIDO2 WebAuthn standard
let options: [String: Any] = [
    "rp": [
        "id": "example.com",
        "name": "Example Service"
    ],
    "user": [
        "id": "user-unique-id-as-base64",
        "name": "username",
        "displayName": "User's Display Name"
    ],
    "challenge": "base64-encoded-challenge",
    "pubKeyCredParams": [
        ["type": "public-key", "alg": -7] // ES256
    ]
    // Additional optional parameters
]

client.webauthnCreate(options: options) { data, metadata, error in
    if let data = data {
        // Handle successful creation, access attestationObject and clientDataJSON
        if let rawId = data["rawId"] as? String {
            // Store credential ID for future authentications
        }
    } else if let error = error {
        // Handle error
    }
}

Parameters

Returns
The completion handler provides the following parameters:

Verifying (Assertion): FIDO2Client.webauthnGet()

The webauthnGet(options:completion:) method retrieves a credential object based on the specified PublicKeyCredentialRequestOptions. This object can be used to authenticate the user.

The response follows the AuthenticatorAssertionResponse format from the WebAuthn standard.

Refer to Mozilla's online documentation on PublicKeyCredentialRequestOptions or to the W3C standard Options for Assertion Generation. For response format, see the W3C standard AuthenticatorAssertionResponse interface.

Usage

// Create options dictionary following FIDO2 WebAuthn standard
let options: [String: Any] = [
    "challenge": "base64-encoded-challenge",
    "rpId": "example.com",
    "allowCredentials": [
        [
            "type": "public-key",
            "id": "previously-stored-credential-id"
        ]
    ],
    "timeout": 60000
]

client.webauthnGet(options: options) { data, metadata, error in
    if let data = data {
        // Handle successful assertion
        if let authenticatorData = data["authenticatorData"] as? String,
           let signature = data["signature"] as? String {
            // Verify the signature and authenticator data
        }
    } else if let error = error {
        // Handle error
    }
}

Parameters

Returns
The completion handler provides the following parameters:

Unbinding: FIDO2Client.unbind()

There are two versions of this method: one for removing all FIDO2 credentials for the current user, and another for removing credentials for a specific user.

For Current User

The unbind() method removes all FIDO2 credentials and state for the current user from the device.

Usage

client.unbind()

Parameters
None.

Returns
None. |

For Specific User

The unbind(user:) method removes FIDO2 credentials and state for a specific user from the device.

Usage

let userId = "user123" // Unique identifier for the user
client.unbind(user: userId);

Parameters

Returns
None. |

Objective-C

Retrieving Enrollment Status (Attestation): FIDO2Client.webauthnRetrieve()

There are two versions of this method: one for retrieving credentials for the current user, and another for retrieving credentials for a specific user.

For Current User

To check if the current user has previously registered credentials on this device and retrieve the enrollment status, use the webauthnRetrieveWithCompletion: method.

Usage

[client webauthnRetrieveWithCompletion:^(NSDictionary * _Nullable data, NSDictionary<NSString *, NSString *> * _Nullable metadata, ZSMError * _Nullable error) {
    if (data) {
        // Process attestation data
    } else if (error) {
        // Handle error
    }
}];

Parameters

Returns
The callback function receives the following parameters:

For Specific User

To check if a specific user has previously registered credentials on this device and retrieve the enrollment status, use the webauthnRetrieveForUser:withCompletion: method.

Usage

NSString *userId = @"user123"; // Unique identifier for the user
[client webauthnRetrieveForUser:userId withCompletion:^(NSDictionary * _Nullable data, NSDictionary<NSString *, NSString *> * _Nullable metadata, ZSMError * _Nullable error) {
    if (data) {
        // Process attestation data for specific user
    } else if (error) {
        // Handle error
    }
}];

Parameters

Returns
The callback function receives the following parameters:

Enrolling (Attestation): FIDO2Client.webauthnCreate()

To initiate the creation of a new credential object, use the webauthnCreateWithOptions:completion: method. This function uses a dictionary containing the PublicKeyCredentialCreationOptions to generate the credential object, which can be stored securely for future authentication.

The response follows the PublicKeyCredential format from the WebAuthn standard.

Refer to Mozilla's online documentation on PublicKeyCredentialCreationOptions or to the W3C standard Options for Credential Creation. For response format, see the W3C standard PublicKeyCredential interface.

Usage

// Create options dictionary following FIDO2 WebAuthn standard
NSDictionary *creationOptions = @{
    @"rp": @{
        @"id": @"example.com",
        @"name": @"Example Service"
    },
    @"user": @{
        @"id": @"user-unique-id-as-base64",
        @"name": @"username",
        @"displayName": @"User's Display Name"
    },
    @"challenge": @"base64-encoded-challenge",
    @"pubKeyCredParams": @[
        @{@"type": @"public-key", @"alg": @(-7)} // ES256
    ]
    // Additional optional parameters
};

[client webauthnCreateWithOptions:creationOptions completion:^(NSDictionary * _Nullable data, NSDictionary<NSString *, NSString *> * _Nullable metadata, ZSMError * _Nullable error) {
    if (data) {
        // Handle successful creation
        NSString *rawId = data[@"rawId"];
        if (rawId) {
            // Store credential ID for future authentications
        }
    } else if (error) {
        // Handle error
    }
}];

Parameters

Returns
The promise resolves with the following parameters:

Verifying (Assertion): FIDO2Client.webauthnGet()

To retrieve a credential object, use the webauthnGetWithOptions:completion: method. This method utilizes a dictionary containing the PublicKeyCredentialRequestOptions to authenticate the user.

The response follows the AuthenticatorAssertionResponse format from the WebAuthn standard.

Refer to Mozilla's online documentation on PublicKeyCredentialRequestOptions or to the W3C standard Options for Assertion Generation. For response format, see the W3C standard AuthenticatorAssertionResponse interface.

Usage

// Create options dictionary following FIDO2 WebAuthn standard
NSDictionary *requestOptions = @{
    @"challenge": @"base64-encoded-challenge",
    @"rpId": @"example.com",
    @"allowCredentials": @[
        @{
            @"type": @"public-key",
            @"id": @"previously-stored-credential-id"
        }
    ],
    @"timeout": @60000
};

[client webauthnGetWithOptions:requestOptions completion:^(NSDictionary * _Nullable data, NSDictionary<NSString *, NSString *> * _Nullable metadata, ZSMError * _Nullable error) {
    if (data) {
        // Handle successful assertion
        NSString *authenticatorData = data[@"authenticatorData"];
        NSString *signature = data[@"signature"];
        if (authenticatorData && signature) {
            // Verify the signature and authenticator data
        }
    } else if (error) {
        // Handle error
    }
}];

Parameters

Returns
The promise resolves with the following parameters:

Unbinding: FIDO2Client.unbind()

There are two versions of this method: one for removing all FIDO2 credentials for the current user, and another for removing credentials for a specific user.

For Current User

To remove all FIDO2 credentials and state for the current user from the device, use the unbindWithCompletion: method.

Usage

[clientt unbind];

Parameters
None. |

Returns
None. |

For Specific User

To remove FIDO2 credentials and state for a specific user from the device, use the unbindForUser:withCompletion: method.

Usage

NSString *userId = @"user123"; // Unique identifier for the user
[client unbindForUser:userId];

Parameters

Returns
None.