Introduction

This guide provides developer-focused technical details on how to integrate the OneSpan FIDO Authenticator Specific Modules into a FIDO application and a FIDO Server. It also provides information on how to configure a FIDO Server.

Intended readership

This document is intended for:

  • Intermediate Android developers with a strong working knowledge of Java, Android Studio, Gradle, and the Android APIs
  • Intermediate iOS developers with a strong working knowledge of Objective-C, Swift, C++, Xcode, and the iOS APIs

In addition, familiarity with the use of REST APIs, HTTP, and TLS is recommended.

Providing feedback

Every effort has been made to ensure the accuracy and usefulness of this guide. However, as the reader, you are our most important critic and commentator. We appreciate your judgment and would like you to write us your opinions, suggestions, critiques, questions, and ideas. Please send your commentary to: [email protected].

To recognize the particular guide you are referring to, please include the following information in your subject header: FIDO-ASM-SDK-IG-5.0.0-en2024-06-03

Please note that product support is not offered through the above email address.

Version information

This guide covers the following versions:

  • 4.27.1 - OneSpan FIDO UAF SDK for Android and iOS
  • 7.0.2 - libraries from Nok Nok Labs

For best results, ensure that you are using the supported versions.

Terms, definitions, and abbreviations

The following glossary of technical terms helps you understand the concepts and reference information in this document. For more information about FIDO terminology, refer to the glossary of the FIDO Alliance.

  • Symmetric key-block cipher. Uses the Data Encryption Standard (DES) cipher three times to encrypt its data.
  • The Digipass secret key in a decimal or hexadecimal character string format, encrypted with the customer master key in the static vector. It is one of the following: 20 decimal digits for a single-length secret key; the second part of the key is derived from the first part. 40 decimal digits for a double-length secret key. 16 hexadecimal characters for a single-length secret key; the second part of the key is derived from the first part. 32 hexadecimal characters for a double-length secret key. To prevent it from alteration the activation code ends with a checksum on one digit.
  • Secret data string of up to 64 alphanumeric characters shared between the customer (server) and the user prior to registration; used to protect the transfer of sensitive data during the Digipass activation process. Sometimes also referred to as customer historical secret.
  • Android Debug Bridge
  • Symmetric key encryption algorithm. A block cipher with a fixed block size of 128 bits, and a key size of 128, 192, or 256 bits.
  • See Advanced Encryption Standard
  • Also Nonce
  • Authenticator Specific Module; interface used by the FIDO Client, in charge of discovering an available authenticator on the user's device.
  • Attestation is used to cryptographically prove that a user has a specific device model at registration time. It is a keypair burned into the device at manufacturing time that is specific to a device model. During registration the generated credentials are signed with the attestation private key and the service that registers the user can verify that the credentials came from the device.
  • Data used by the user to identify to a server to receive the Digipass activation data.
  • Unique identifier of a basic service set; 48-bit label that conforms to MAC-48 conventions.
  • Provides facilities to use fingerprint recognition to increase user convenience during the identification process while retaining a secure solution. It also provides methods to test whether fingerprint recognition is supported by the platform and has been enabled by the user before actually verifying fingerprints.
  • Basic service set identifiers
  • Provides facilities to aggregate information from various mobile sources for risk evaluation of mobile transactions by OneSpan Risk Analytics.
  • Customer historical secret; also Activation password.
  • Operation mode of block ciphers. CTR uses the AES block cipher to create a stream cipher. Data is encrypted and decrypted by XORing with the key stream produced by AES encrypting sequential counter block values.
  • Cyclic redundancy check.
  • Specific colorful cryptogram, similar to a QR code; used for visual transaction signing.
  • Counter mode
  • OneSpan customer who licenses OneSpan Mobile Security Suite and distributes it to the user.
  • Also Activation password
  • 32-hexadecimal-character string. This string is unique for each customer and is generated (random/fixed) during production by OneSpan logistics. The master key is also known as “serial code”. It is a Triple DES key embedded in the static vector. See also Static vector.
  • Data verification method to detect errors and accidental changes to raw data.
  • Optional code used to carry platform-specific data from client to server in the standard licensing model; part of the Digipass binding feature.It contains a Digipass response based on one of the Digipass cryptographic application key and bits extracted from the fingerprint of the platform where Digipass is running.
  • Facilitates Digipass application development; it provides a function to generate a unique identifier for a given mobile device, the device fingerprint. The SDK can be used on a variety of devices and various supported platforms.
  • Mandatory code used to carry platform-specific data from client to server in the premium licensing model.It contains a Digipass response based on one of the Digipass cryptographic application key and bits extracted from the fingerprint of the platform where Digipass is running.
  • A unique identifier; it is a hexadecimal string of 64 characters. It is a securely computed SHA-256 hash of the device-specific data and hardcoded salts.
  • The process in which the Digipass serial number, parameter set, secret, and initial seed value for future OTP or e-signature generation are provided. Activation is successful when the first Digipass response is validated on the server. Once the client activation is completed, the Digipass instance is ready to generate Digipass responses. See also Digipass instance.
  • The association of a unique Digipass key, serial number, sequence number, a static vector, and a Digipass secret.
  • Also Digipass key
  • 128-bit secret key used by the Digipass algorithm to generate one-time passwords or e-signatures. The key is provided to the Digipass instance through the activation code. See also Activation code, Digipass instance.
  • Also Digipass serial number.
  • The Digipass password protects the Digipass key against unauthorized use. The password is used to encrypt the key in the dynamic vector. The password is also known as user password, static password, or PIN. See also Dynamic vector.
  • Contains functions to activate the Digipass license, generate one-time passwords and e-signatures, establish a secure channel between Digipass and a server, and enable user-password management.
  • The unique identifier of a Digipass license. It consists of a 3-alphanumeric-character prefix set in the static vector, and a 7-digit suffix. The suffix can be provided in the XFAD or by the user during Digipass activation. See also XFAD, Digipass serial number prefix, Digipass serial number suffix.
  • Consists of the first three characters of the Digipass serial number. The serial number prefix is unique per customer.
  • Consists of the last seven decimal digits of the Digipass serial number. The serial number suffix is unique per user.
  • Implements the DSAPP protocol to securely transfer the server-side generated Digipass software activation data to the Digipass software client. The SDK encrypts the activation data before transferring it to the client application and decrypts it again.
  • Data field
  • Dynamic vector
  • Digipass-specific binary data. It is created after successful activation. It is updated by the OneSpan Digipass SDK at runtime.It contains the following: Digipass status Serial number suffix PIN information Encrypted Digipass secret Status of the cryptographic Digipass applications Last-time-used value of the cryptographic Digipass applications Last-event-used value of the cryptographic Digipass applications
  • Number to uniquely identify mobile devices.
  • Event reactivation counter encrypted with the activation password or a session key. See also activation password.
  • Full activation data encrypted with the activation password or a session key. See also activation password, full activation data.
  • See User
  • Electronic serial number
  • This is the value to initialize the event-based Digipass counter. It should be provided to the OneSpan Digipass SDK during the re-activation process to synchronize the event counter between the Digipass data on the server-side and the Digipass instance on the client side. See also Digipass instance, Digipass SDK.
  • An (application) facet is how an application is implemented on various platforms. For example, the application MyBank may have an Android app, an iOS app, and a Web app. These are all facets of the MyBank application.
  • Platform-specific identifier of an application facet that allows a user to use different application facets of a Relying Party with the same authenticator and key. During the registration operation, a new private key is created by the user's authenticator and the public key is sent to the Relying Party. Note that each of these keys is associated to a specific AppID.
  • Full activation data
  • The FIDO (Fast IDentity Online) Alliance is an organization whose main goal is to reduce the user’s reliance on passwords. It proposes several frameworks that enable passwordless authentication.
  • Leverages FIDO protocols and allows you to integrate mobile device biometric security capabilities into your application to enable strong authentication with primary and second factor authentication using biometrics and hardware authenticators.
  • A FIDO authenticator is responsible for user verification and maintaining the cryptographic material required by FIDO authentication on behalf of the relying party authentication.
  • Software associated with a FIDO authenticator that provides a uniform interface between the hardware and FIDO Client software.
  • Software responsible for processing FIDO messages, and coordinating between an application and FIDO authenticators. The FIDO UAF App SDK includes an embedded FIDO Client. The FIDO UAF App SDK can also use an external FIDO Client that may be preloaded on a device by the manufacturer.
  • FIDO supports the protocol specifications published by the FIDO Alliance. UAF provides strong authentication backed by biometrics, U2F provides two-factor token-based authentication that strengthens password-based logins, FIDO2 supports registration and authentication with web browsers that implement the Web Authentication API as defined by the W3C.
  • Application that implements FIDO protocols. This can be a separate application which communicates with the relying party application over HTTP or other transport protocols.
  • FIDO UAF aims to substitute password authentication. It provides passwordless and multi-factor authentication with compliant authenticators.
  • Enables your mobile app to communicate with the FIDO components on the device such as the client and FIDO ASMs.
  • FIDO2 is a standard for strong authentication in the web. FIDO2 is comprised of the WebAuthn specification and the corresponding Client-to-Authenticator Protocols (CTAP). It allows users to use their devices and authenticators to authenticate to online services without the need for entering a password. It can be accomplished both on their desktop and mobile environments.
  • Serves to finalize the activation. The full activation data includes the parameter settings for the OneSpan Digipass SDK activation, the Digipass key, and and the Digipass serial number. It is the concatenation of the static vector, the activation code, and the serial number suffix. If the activation code is encrypted by an activation password and/or a nonce, it becomes encrypted full activation data (XFAD). See also activation code, Digipass SDK, encrypted full activation data, nonce, serial number suffix.
  • Provides a native component for a mobile application to integrate QR code and Cronto image capture.
  • Facilitates the Digipass application development by providing you with the image scanning functionality to capture QR codes and Cronto images.
  • International Mobile Equipment Identity
  • International Mobile Equipment Identity; unique number to identify valid devices. Used by GSM networks.
  • Method to hide the root status of an iOS device and to conceal that the mobile device is compromised.
  • Key checksum value
  • Checksum of the key value; used to compare keys without knowing their actual values.
  • Message authentication code.
  • An attack where the communication of two parties is intercepted by an attacker.
  • Mobile Equipment Identifier
  • Man-in-the-middle-attack.
  • Security technology that integrates directly into applications to provide proactive security against a wide range of attacks (tampering, debugging, code injection, code modification, data theft from the app). It performs different security checks and protects applications against attacks during runtime.
  • Globally unique number to facilitate universal mobile equipment identifidcation.
  • Set of communication protocols between two devices over a short distance.
  • Also Permanent storage
  • A 64–hexadecimal-character random number generated by the OneSpan Digipass SDK host platform. It is part of the one-time-activation process and ensures that no other SDK-integrated instance can register with the same data.
  • Unique hexadecimal string with a maximum length of 2064 characters. The Notification SDK assigns this identifier to the client application - it is unique to the client device, regardless of the platform. It must be sent to the back end for later use.
  • Provides facilities to send push notifications to mobile applications via Apple, Google, and Microsoft cloud notification services, and provides an abstraction layer for the interactions between client and server.
  • Open reference architecture for strong authentication.
  • OATH Challenge-Response Algorithm, a multi-factor authentication algorithm for Challenge/Response authentication.
  • A password that is valid for only one authentication process. OTPs can be used only once, and each authentication process requires a new OTP.
  • A centralized authentication solution that offers strong authentication and validation of transaction signatures. It verifies authentication requests from individuals trying to access the corporate network or business applications.
  • API-based authentication platform that serves as back-end for Digipass strong authentication and e-signatures.
  • Enables mobile developers to integrate the main features of OneSpan Mobile Security Suite in their mobile application; the SDK provides facilities to orchestrate the mobile application and authenticate users after risk evaluation on the server-side.
  • An origin indicates where a request originated from. An origin should not include any path information, and it should use the https protocol.
  • One-time password.
  • Storage that can retrieve persistent information which was previously stored in the app keychain using the Secure Storage SDK (Write Storage API). Can retrieve stored information even after having been power cycled. Also non-volatile storage.
  • Data specific to the platform hosting the OneSpan Digipass SDK.
  • Optional process after the client activation.
  • Push notifications are clickable pop-up messages that are displayed outside an app. They are pushed from the server the app uses to the user's device.
  • User password
  • Two-dimensional bar code composed of black modules that are arranged in a square grid on a white background.
  • The process of generating Digipass activation data on the server-side.
  • A web site or other entity that uses a FIDO protocol to directly authenticate users (i.e., performs peer-entity authentication). Note that if FIDO is composed with federated identity management protocols (e.g. SAML, OpenID Connect etc.), the identity provider will also be playing the role of a FIDO Relying Party.
  • A relying party identifier is a valid domain string identifying the Relying Party on whose behalf a given registration or authentication ceremony is being performed. As the registration ceremony is generating credentials on the client side (authenticator) these are scoped to the Relying Party that was conducting the registration ceremony.
  • Return host code
  • Fraud detection and management system. It identifies risk at critical steps, predicts risk levels, and takes action when suspicious activites are identified. It is a product for monitoring online banking applications and payment processing which helps to protect against online banking fraud.
  • Method to hide the root status of an Android device and to conceal that the mobile device is compromised.
  • Detects if an application is running on a rooted/jailbroken device based on residual traces of the rooting method.
  • Signature confirmation code
  • Ensures the confidentiality, integrity, and non-repudiation of data exchanged between a client and a server. The data are encrypted and signed with a key changed during the activation process. The protected data are embedded in a Secure Channel message for the transport process.
  • Used to format the transaction message body before encryption by OneSpan Authentication Server or OneSpan Authentication Server Framework (server SDK), and parse the transaction message body before decryption by the Digipass SDK (client SDK).
  • Augmented protocol to exchange keys securely and password-authenticated.
  • Provides a generic API to securely store data on a mobile device and masking the way the information is stored on the platform.
  • This is the unique identifier of a Digipass instance from a Digipass license. It consists of two numeric characters from 01 to 99.
  • Also Digipass serial number
  • The validation of the first Digipass response generated after client activation. The server activation is part of the post-activation process.
  • Identifier or network name for a group of wirless network devices.
  • Cryptographic hash algorithm. Used in the Chinese National Standard.
  • Secure Remote Password protocol
  • Service set identifier
  • The Digipass parameter set, i.e. customer-specific binary configuration data. It contains the Digipass serial number prefix, the customer master key and the parameter settings of the cryptographic application(s). It can be provided independently in clear text format, or as part of the FAD. See also Customer master key; FAD.
  • Time interval when the time seed is constant.
  • Also Digipass key
  • Time-based one-time password.
  • The end user of a Digipass instance (for instance a bank’s customer).
  • Storage that is non-persistent and keeps stored information as long as the app lifecycle is not fully terminated. Requires power to maintain the stored information.
  • With the White-Box Cryptography SDK, secret cryptographic keys are kept hidden in the source code even during runtime. The SDK enables developers to convert key values with the White-Box Table Generator into obfuscated source code which can be integrated into their application, instead of adding hardcoded key values in the source code.
  • Encrypted event reactivation counter
  • Encrypted full activation data