Skip to main contentSkip to footer
Search
LY Corporation Tech Blog

We are promoting the technology and development culture that supports the services of LY Corporation and LY Corporation Group (LINE Plus, LINE Taiwan and LINE Vietnam).

This post is also available in the following languages. Japanese, Korean

Introduction to the FIDO2 Client SDK Open Source

Hello, we're Doyeon Kim and Younghyun Kim from the Security R&D team, responsible for developing the FIDO2 client.

FIDO, based on public key cryptography, is an authentication standard that's easy and secure for users compared to password or SMS OTP authentication, and easy to deploy and maintain from a service perspective. FIDO credentials never leave the user's device and aren't stored on the server, protecting against phishing and all forms of credential theft and replay attacks.

Before merging with LINE Corporation to form LY Corporation, Yahoo! JAPAN Corporation joined the FIDO Alliance in 2014 and became a member of the board in 2019. LINE Corporation also joined the board in 2017 and has since participated in various FIDO-related events, including interoperability testing events for FIDO servers. In 2021, the Security R&D team became the first service provider in the world to obtain FIDO Universal Server certification and open-sourced our FIDO2 server. We introduced this in our articles "FIDO at LINE: A First Step to a World Without Passwords" and "FIDO at LINE: FIDO2 server as an open-source project". In this article, we want to introduce our newly open-sourced FIDO2 client SDK, which follows the Web Authentication (WebAuthn) standard. This SDK makes it easier to implement FIDO2 authentication on the client side.

Introducing FIDO

FIDO (Fast Identity Online) is a new authentication standard designed to replace traditional knowledge-based authentication methods like passwords. It proposes an authentication method that leverages possession-based authentication.

Traditional knowledge-based authentication relies on shared knowledge between the user and the server, such as passwords. This method is inconvenient for users, who must remember their passwords, and is highly vulnerable to security breaches if an attacker guesses the user's password or if the server-stored passwords are leaked.

Possession-based authentication, on the other hand, performs authentication based on a device that the user possesses. FIDO's authentication technology uses the user's device as an authenticator. The user's authentication information (for example, biometric data) is stored only on the device and isn't transmitted to the server, significantly enhancing security from the server's perspective. Users don't need to remember passwords and can authenticate securely and easily using information that only they possess.

Differences between FIDO1 and FIDO2

The differences between FIDO1 and FIDO2 are as follows:

  • FIDO1 includes two protocols: UAF (Universal Authentication Framework) and U2F (Universal 2nd Factor). UAF is a protocol that provides passwordless authentication, while U2F is a protocol that adds a security element to existing password-based authentication.
  • FIDO2 is an extended version of FIDO1 and includes WebAuthn and CTAP (Client to Authenticator Protocol). FIDO2 enhances integration with web applications and supports a wider variety of authentication methods.

Let's take a closer look at the newly included WebAuthn and CTAP in FIDO2.

WebAuthn

WebAuthn is a web authentication standard developed by the Web Authentication Working Group under the W3C (World Wide Web Consortium). It supports secure management of user authentication information and enables passwordless authentication in web applications. The functionalities provided by WebAuthn are as follows:

  • Registration: The user registers their device with the web application. During this process, a public key and a private key are generated. The public key is stored on the server, while the private key is stored only on the device.
  • Authentication: When the user logs in to the web application, the device uses the private key to generate a signature and sends it to the server. The server verifies the signature using the public key and authenticates the user.

WebAuthn can be used not only on the web but also in a native application. It's possible to implement WebAuthn-compliant authentication using authentication APIs provided by platforms like iOS and Android.

CTAP

CTAP is a protocol developed by the FIDO Alliance for communication between client and authenticator, and it has two versions:

  • CTAP1: Based on the U2F protocol, it provides two-factor authentication. It's compatible with existing FIDO U2F devices.
  • CTAP2: As part of FIDO2, it supports passwordless authentication and works together with WebAuthn to provide various authentication methods.

FIDO2 client SDK introduction

We implemented a FIDO2 client SDK to make it easier to apply passwordless authentication to services. Our SDK adheres to the latest security standards and follows the WebAuthn Level 2 specification to ensure compatibility with certified FIDO2 servers.

There are two reasons why we adopted Level 2 instead of the ongoing Level 3 specification at W3C. First, the Level 3 specification is still in draft status and hasn't been officially finalized. In contrast, Level 2 has already been adopted as an official recommendation by W3C, making it more stable. Additionally, the Passkey introduced in Level 3 allows keys to be synchronized within the same account. However, there may be cases where business logic requires preventing this synchronization, and currently, there's no way to control this synchronization with the Passkey-related APIs provided by each platform.

For these reasons, we're currently following the Level 2 specification. Once the Level 3 specification is officially finalized and a solution for the Passkey synchronization issue is provided, we'll consider updating our specification accordingly.

Now, let's take a closer look at the FIDO2 client SDK. The FIDO2 client SDK is optimized for use in native applications running on mobile devices. It's implemented in Kotlin for Android and Swift for iOS to ensure ease of use on each platform, resulting in the following advantages:

  • Platform optimization: By developing the FIDO2 client SDK in Kotlin and Swift, it can be easily and efficiently invoked within native applications. It also provides an optimized authentication experience for each platform by directly utilizing the features available on mobile devices (for example, Face ID, Touch ID).
  • Ease of development: By using the SDK, developers don't need to implement the transfer protocol between the client and the authenticator or the CTAP interface separately, making development relatively simple and fast. This allows developers to integrate passwordless authentication into their services with less effort.
  • Flexibility: If specialized authentication logic is required for each service, customization can be easily achieved. This allows for meeting various business requirements and improving the user experience.
  • Security: The SDK utilizes secure areas within the device (for example, iOS Secure Enclave, ARM TrustZone, Android StrongBox) to securely process biometric data.

Below is a simplified diagram of the overall structure of the FIDO2 client SDK.

  • PublicKeyCredential: This interface is used for user registration creating new public key credentials (asymmetric key pair and related information) and user authentication using public key credentials for authentication. Developers can use this interface to implement user registration and authentication features that comply with the WebAuthn standard in their services.
  • Authenticator: This interface verifies the user's identity and, for verified users, creates new public key credentials or uses existing public key credentials.
  • Trusted Execution Environment (TEE): A secure execution environment within the device that's hardware-isolated from a security perspective. It stores the private key of the public key credential.
  • FIDO2 Server: A server that performs various verifications required during the user registration and authentication process. It stores the public key of the public key credential.
  • User: The individual using the service provides device credentials (biometrics, passcodes, PINs, or patterns) used for device authentication but not stored on the server.

The operation process can be briefly described as follows:

  1. PublicKeyCredential requests and receives a challenge from the FIDO2 server to prevent replay attacks.
  2. PublicKeyCredential internally calls the Authenticator.
  3. Authenticator verifies the user's identity using device credentials.
  4. Once the user identity verification is complete, the TEE generates or uses the public key credentials. During this process, the private key is used to sign the data required for user registration and authentication, including the challenge.
  5. PublicKeyCredential receives the signed data from the Authenticator and requests verification from the FIDO2 server.
  6. The FIDO2 server verifies the signed data using the stored public key.

Next, let's take a closer look at the main interfaces of the FIDO2 client SDK, PublicKeyCredential and Authenticator.

PublicKeyCredential

PublicKeyCredential is an implementation of the PublicKeyCredential interface from the WebAuthn Level 2 specification, using asymmetric key pairs as credentials instead of passwords. Through this interface, credentials can be created to register users, and the created credentials can be used to authenticate users.

The PublicKeyCredential interface supports two methods defined in the WebAuthn Level 2 specification for user registration and authentication: the create and get methods. The create method performs user registration and generates new credentials through the authenticator. The get method performs user authentication using the credentials created by the create method. These two methods not only implement the basic logic specified in the WebAuthn Level 2 specification but also communicate with the FIDO2 server to verify the credentials.

In the FIDO2 client SDK, the RelyingParty interface is provided to allow service developers to apply custom logic when calling the FIDO2 server's API. Service developers need to implement the RelyingParty interface to ensure proper API calls to the FIDO2 server.

We have implemented Biometric and DeviceCredential, both of which follow the PublicKeyCredential interface for different authenticators. Biometric uses the BiometricAuthenticator and relies solely on biometric information for user identity verification. DeviceCredential uses the DeviceCredentialAuthenticator and utilizes device credentials such as biometric information or passcodes for user identity verification. Each authenticator will be explained in detail below.

Authenticator

Authenticator is an implementation of the authenticator model from the WebAuthn Level 2 specification. It's a key component that calls the authentication module implemented in the OS to verify whether the current user attempting user registration or authentication is legitimate or not.

Authenticator performs several important roles during the user registration and authentication process:

  • Credential creation and storage: When a user registers for a new service, a unique credential is generated. This credential consists of a public and private key pair generated within the TEE. The public key is stored on the server after server verification, while the private key is stored only in the TEE.
  • Storing credential-related information: To manage credentials, related information such as the public key credential source and the signature counter are stored. The FIDO2 client SDK provides the CredentialSourceStorage interface to allow service developers to choose an appropriate storage solution. Service developers must implement a storage solution that follows the CredentialSourceStorage interface to ensure that the public key credential source and signature counter are correctly stored and managed.
  • User identity verification: The authenticator verifies the user's identity by requiring user information such as biometric data or a passcode from the user.
  • Generating authenticator data: During the user registration process, the authenticator generates an attestation object signed with the private key. During the user authentication process, it generates an assertion object, also signed with the private key. Both objects are sent to the FIDO2 server for verification using the public key.

To perform these roles, the Authenticator supports two methods corresponding to the Authenticator Operations in the WebAuthn Level 2 specification: makeCredential and getAssertion. The makeCredential method is called within the create method of PublicKeyCredential, and the getAssertion method is called within the get method of PublicKeyCredential. The specific operation of each method can be found in their respective links.

The FIDO2 client SDK currently supports BiometricAuthenticator, which supports biometric authentication, and DeviceCredentialAuthenticator, which supports device credential authentication. Let's take a look at the characteristics of each method.

Biometric authentication

This authentication method uses the only biometric features of mobile devices (for example, Face ID and Touch ID). In this method, adding a new biometric template invalidates the existing credentials. For example, if a credential is registered when fingerprint 1 is added to the device, and then a new fingerprint 2 is added to the device, the existing credentials become invalid. As a result, the previously registered credential can't be used for authentication, and re-registration of the credential is required.

Device credential authentication

This authentication method uses device credentials such as biometrics or passcode. It provides a more flexible authentication method compared to biometric authentication alone. If the device doesn't support biometric authentication, the user can enter a passcode. Even on devices that support biometric authentication, if biometric authentication fails, a passcode can be entered as a second attempt. It's also possible to use device credentials interchangeably. For example, even if a credential is registered using a fingerprint, both the fingerprint and other device credentials can be used for authentication. Additionally, this method isn't affected by the addition of new biometric templates, and the added templates are compatible with the existing authentication information. For instance, if a credential is registered when fingerprint 1 is added to the device, and then a new fingerprint 2 is added, both fingerprint 1 and fingerprint 2 can be used to authenticate with the existing credential.

FIDO2 client open-source introduction

Following the open-sourcing of the LINE FIDO2 server, the Security R&D team has decided to also open-source the newly developed FIDO2 client SDK and the demo app code for testing. We hope that these activities will ultimately contribute to the development of the FIDO ecosystem. Here is a brief introduction to the open-sourced SDK and demo app.

FIDO2 client SDK

The GitHub repositories for the Security R&D team's open-source FIDO2 client SDK are as follows:

Both versions are licensed under Apache-2.0.

To use the FIDO2 client SDK, service developers need to implement the CredentialSourceStorage and RelyingParty interfaces provided by the SDK. For more detailed information, please refer to the README.md file in the open-source repositories.

Demo application

To help service developers understand how to use the FIDO2 client SDK and integrate it more easily into their services, we have open-sourced demo apps that include user registration and authentication features, along with the SDKs for each platform. Below are the GitHub repositories for the demo apps on each platform:

Both versions are licensed under Apache-2.0.

In the demo app, you can find examples of how to implement the CredentialSourceStorage and RelyingParty interfaces, which service developers need to implement when using the FIDO2 client SDK.

To run the demo app, you need to have a FIDO2 server running that interacts with the app. If you want to use the FIDO2 open-source server provided by our team, please refer to the README.md file.

Conclusion

The FIDO2 client SDK and demo apps that we've open-sourced are part of our efforts to advance the FIDO ecosystem. If you encounter any issues or have suggestions for improvements related to the open-source code, please feel free to leave them on the GitHub issue tracker. Your feedback is greatly appreciated.

Our team plans to continuously improve the project in collaboration with the open-source community. We'll strive to provide better solutions through the addition of new features, performance improvements, and bug fixes. We look forward to your interest, participation, and contributions. Thank you.