npm package: @hmscore/hms-js-fido
Description: HMS JS FIDO
Latest version: 5.2.0-300

# JSB FIDO

## Contents

- [1. Introduction](#1-introduction)
- [2. Installation Guide](#2-installation-guide)
  - [Creating a Project in App Gallery Connect](#creating-a-project-in-appgallery-connect)
  - [Configuring the Signing Certificate Fingerprint](#configuring-the-signing-certificate-fingerprint)
  - [React-Native Integration](#react-native-integration)
  - [Cordova Integration](#cordova-integration)
  - [Ionic Integration](#ionic-integration)
    - [Ionic with Cordova Runtime](#ionic-with-cordova-runtime)
    - [Ionic with Capacitor Runtime](#ionic-with-capacitor-runtime)
  - [Configure Permissions](#configure-permissions)
- [3. API Reference](#3-api-reference)
  - [HMSFIDO](#hmsfido)
  - [Data Types](#data-types)
  - [Constants](#constants)
  - [Result Codes](#result-codes)
- [4. Configuration and Description](#4-configuration-and-description)
- [5. Questions or Issues](#5-questions-or-issues)
- [6. Licensing and Terms](#6-licensing-and-terms)

## 1. Introduction

JSSDK enables communication between HUAWEI FIDO Kit and React Native, Cordova and Ionic platforms. This plugin exposes all capabilities provided by HUAWEI FIDO Kit. Detailed information about data types, constants and methods provided by this document.

## 2. Installation Guide

### Creating a Project in AppGallery Connect

Creating an app in AppGallery Connect is required in order to communicate with the Huawei services. To create an app, perform the following steps:

**Step 1.** Sign in to [AppGallery Connect](https://developer.huawei.com/consumer/en/service/josp/agc/index.html?ha_source=hms1) and select **My projects**.

**Step 2.** Select your project from the project list or create a new one by clicking the **Add Project** button.

**Step 3.** Go to **Project Setting** > **General information**, and click **Add app**.
If an app exists in the project and you need to add a new one, expand the app selection area on the top of the page and click **Add app**.

**Step 4.** On the **Add app** page, enter the app information, and click **OK**.

- A signing certificate fingerprint is used to verify the authenticity of an app when it attempts to access an HMS Core service through the HMS Core SDK. Before using HMS Core (APK), you must locally generate a signing certificate fingerprint and configure it in AppGallery Connect. Ensure that the JDK has been installed on your computer.

### Configuring the Signing Certificate Fingerprint

**Step 1.** Obtain the signature file that generated in [Generating a Signing Certificate](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html?ha_source=hms1#2) section.

**Step 2.** Go to **Project Setting > General information**. In the **App information** field, click the icon next to SHA-256 certificate fingerprint, and enter the obtained **SHA256 certificate fingerprint**.

**Step 3.** After completing the configuration, click check mark.

### React-Native Integration

**Step 1:** Sign in to [AppGallery Connect](https://developer.huawei.com/consumer/en/service/josp/agc/index.html?ha_source=hms1) and select **My projects**.

**Step 2:** Find your app project, and click the desired app name.

**Step 3:** Go to **Project Setting** > **General information**. In the **App information** section, click **agconnect-service.json** to download the configuration file.

**Step 4:** Create a React Native project if you do not have one.

**Step 5:** Copy the **agconnect-service.json** file to the **android/app** directory of your React Native project.

**Step 6:** Copy the signature file that generated in [Generating a Signing Certificate](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html?ha_source=hms1#2) section, to the android/app directory of your React Native project.

**Step 7:** Check whether the **agconnect-services.json** file and signature file are successfully added to the **android/app** directory of the React Native project.

**Step 8:** Open the **build.gradle** file in the **android** directory of your React Native project.

- Go to **buildscript** then configure the Maven repository address and agconnect plugin for the HMS SDK.

```groovy
buildscript {
  repositories {
    google()
    jcenter()
    maven { url 'https://developer.huawei.com/repo/' }
  }

  dependencies {
    /*
      * <Other dependencies>
      */
    classpath 'com.huawei.agconnect:agcp:1.4.2.301'
  }
}
```

- Go to **allprojects** then configure the Maven repository address for the HMS SDK.

```groovy
allprojects {
  repositories {
    /*
      * <Other repositories>
      */
    maven { url 'https://developer.huawei.com/repo/' }
  }
}
```

**Step 9:** Open the **build.gradle** file in the **android/app** directory of your React Native project.

- Package name must match with the **package_name** entry in **agconnect-services.json** file.

```groovy
defaultConfig {
  applicationId "<package_name>"
  minSdkVersion 19
  /*
   * <Other configurations>
   */
}
```

```groovy
android {
  /*
   * <Other configurations>
   */

  signingConfigs {
    config {
      storeFile file('<keystore_file>.jks')
      storePassword '<keystore_password>'
      keyAlias '<key_alias>'
      keyPassword '<key_password>'
    }
  }

  buildTypes {
    debug {
      signingConfig signingConfigs.config
    }
    release {
      signingConfig signingConfigs.config
      minifyEnabled enableProguardInReleaseBuilds
      ...
    }
  }
}
```

**Step 10:** Open the **build.gradle** file in the **android/app** directory of your React Native project.

- Configure build dependencies.

```groovy
buildscript {
  ...
  dependencies {
    /*
    * <Other dependencies>
    */
    implementation ('com.huawei.hms:rn-adapter:5.2.0.300'){
        exclude group: 'com.facebook.react'
    }
    ...
  }
}
```

**Step 11:** Import the following class to the **MainApplication.java** file of your project.

```java
import com.huawei.hms.jsb.adapter.rn.RnJSBReactPackage;
```

Then, add the **RnJSBReactPackage()** to your **getPackages** method. In the end, your file will be similar to the following:

```java
@Override
protected List<ReactPackage> getPackages() {
    List<ReactPackage> packages = new PackageList(this).getPackages();
    packages.add(new RnJSBReactPackage()); // <-- Add this line
    return packages;
}
...
```

**Step 12:** Download js-sdk using command below.

```bash
npm i @hmscore/hms-js-fido
```

**Step 13:** Import **HMSFIDO** in App.js as following line.

```js
import HMSFIDO from "@hmscore/hms-js-fido";
```

**Step 14:** Don't forget to add init function before calling HMSFIDO functions.

```js
HMSFIDO.init(NativeModules, DeviceEventEmitter);
```

**Step 15:** Run your project.

- Run the following command to the project directory.

```bash
react-native run-android
```

### Cordova Integration

**Step 1:** Install Cordova CLI if haven't done before.

```bash
npm install -g cordova
```

**Step 2:** Create a new Cordova project or use the existing one.

- To create new Cordova project, you can use **`cordova create path [id [name [config]]] [options]`** command. For more details please follow [CLI Reference - Apache Cordova](https://cordova.apache.org/docs/en/latest/reference/cordova-cli/index.html#cordova-create-command).

**Step 3:** Update the widget **`id`** property which is specified in the **`config.xml`** file. It must be same with **package_name** value of the **`agconnect-services.json`** file.

**Step 4:** Add the **Android platform** to the project if haven't done before.

```bash
cordova platform add android
```

**Step 5:** Download plugin using command below.

```bash
cordova plugin add @hmscore/hms-js-fido
```

**Step 6:** Copy **`agconnect-services.json`** file to **`<project_root>/platforms/android/app`** directory.

**Step 7:** Add **`keystore(.jks)`** and **`build.json`** files to your project's root directory.

- You can refer to 3rd and 4th steps of [Generating a Signing Certificate](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html?ha_source=hms1#2) Codelab tutorial page for generating keystore file.

- Fill **`build.json`** file according to your keystore information. For example:

  ```json
  {
    "android": {
      "debug": {
        "keystore": "<keystore_file>.jks",
        "storePassword": "<keystore_password>",
        "alias": "<key_alias>",
        "password": "<key_password>"
      },
      "release": {
        "keystore": "<keystore_file>.jks",
        "storePassword": "<keystore_password>",
        "alias": "<key_alias>",
        "password": "<key_password>"
      }
    }
  }
  ```

**Step 8:** Import the following class to the **MainActivity.java** file of your project. You can find this file in **`platforms/android/app/src/main/java/<your_package_name>`** directory.

```java
import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit;
```

**Step 9:** In the same file, add **CordovaJSBInit.initJSBFramework(this)** line after the **super.onCreate(savedInstanceState)** method call.

- In the end, your file will be similar to the following:

  ```java
  ...

  import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit;

  public class MainActivity extends CordovaActivity
  {
      @Override
      public void onCreate(Bundle savedInstanceState)
      {
          super.onCreate(savedInstanceState);
          CordovaJSBInit.initJSBFramework(this);

          ...
      }
      ...
  }
  ```

**Step 10:** Run the app

```bash
cordova run android
```

### Ionic Integration

Install Ionic CLI and other required tools if haven't done before.

```bash
npm install -g @ionic/cli cordova-res native-run
```

#### Ionic with Cordova Runtime

**Step 1:** Enable the **Cordova integration** if haven't done before.

```bash
ionic integrations enable cordova
```

**Step 2:** Update the widget **`id`** property which is specified in the **`config.xml`** file. It must be same with **package_name** value of the **`agconnect-services.json`** file.

**Step 3:** Add the **Android platform** to the project if haven't done before.

```bash
ionic cordova platform add android
```

**Step 4:** Install `HMS FIDO Plugin` to the project.

```bash
ionic cordova plugin add @hmscore/hms-js-fido
```

**Step 5:** Copy **`agconnect-services.json`** file to **`<project_root>/platforms/android/app`** directory.

**Step 6:** Add **`keystore(.jks)`** and **`build.json`** files to your project's root directory.

- You can refer to 3rd and 4th steps of [Generating a Signing Certificate](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html?ha_source=hms1#2) Codelab tutorial page for generating keystore file.

- Fill **`build.json`** file according to your keystore information. For example:

  ```json
  {
    "android": {
      "debug": {
        "keystore": "<keystore_file>.jks",
        "storePassword": "<keystore_password>",
        "alias": "<key_alias>",
        "password": "<key_password>"
      },
      "release": {
        "keystore": "<keystore_file>.jks",
        "storePassword": "<keystore_password>",
        "alias": "<key_alias>",
        "password": "<key_password>"
      }
    }
  }
  ```

**Step 7:** Import the following class to the **MainActivity.java** file of your project. You can find this file in **`platforms/android/app/src/main/java/<your_package_name>`** directory.

```java
import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit;
```

**Step 8:** In the same file, add **CordovaJSBInit.initJSBFramework(this)** line after the **super.onCreate(savedInstanceState)** method call.

- In the end, your file will be similar to the following:

  ```java
  ...

  import com.huawei.hms.jsb.adapter.cordova.CordovaJSBInit;

  public class MainActivity extends CordovaActivity
  {
      @Override
      public void onCreate(Bundle savedInstanceState)
      {
          super.onCreate(savedInstanceState);
          CordovaJSBInit.initJSBFramework(this);

          ...
      }
      ...
  }
  ```

**Step 9:** Run the application.

```bash
ionic cordova run android --device
```

#### Ionic with Capacitor Runtime

**Step 1:** Enable the **Capacitor integration** if haven't done before.

```bash
ionic integrations enable capacitor
```

**Step 2:** Initialize **Capacitor** if haven't done before. It must be same with **package_name** value of the **`agconnect-services.json`** file.

```bash
npx cap init [appName] [appId]
```

- For more details please follow [Initialize Capacitor with your app information](https://capacitorjs.com/docs/getting-started/with-ionic#initialize-capacitor-with-your-app-information).

**Step 3:** Install `HMS FIDO plugin` to the project.

```bash
npm install @hmscore/hms-js-fido
```

**Step 4:** Build Ionic app to generate resource files.

```bash
ionic build
```

**Step 5:** Add the **Android platform** to the project.

```bash
npx cap add android
```

**Step 6:** Copy **`keystore(.jks)`** and **`agconnect-services.json`** files to **`<project_root>/android/app`** directory.

- You can refer to 3rd and 4th steps of [Generating a Signing Certificate](https://developer.huawei.com/consumer/en/codelab/HMSPreparation/index.html?ha_source=hms1#2) Codelab tutorial page for generating keystore file.

**Step 7:** Open the **`build.gradle`** file in the **`<project_root>/android/app`** directory.

- Add `signingConfigs` entry to the **android** section and modify it according to your keystore.

- Enable `signingConfig` configuration for **debug** and **release** flavors.

```groovy
...

android {

    ...

    // Modify signingConfigs according to your keystore
    signingConfigs {
        config {
            storeFile file('<keystore_file>.jks')
            storePassword '<keystore_password>'
            keyAlias '<key_alias>'
            keyPassword '<key_password>'
        }
    }
    buildTypes {
        debug {
            signingConfig signingConfigs.config // Enable signingConfig for debug flavor
        }
        release {
            signingConfig signingConfigs.config // Enable signingConfig for release flavor
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}
...

apply plugin: 'com.huawei.agconnect' // Apply com.huawei.agconnect plugin. This line must be added to the end of the file.


```

**Step 8:** Open the **`build.gradle`** file in the **`<project_root>/android`** directory. Add **Huawei's maven repositories** and **agconnect classpath** to the file.

```groovy
buildscript {
    repositories {
        /*
            <Other repositories>
        */
        maven { url 'https://developer.huawei.com/repo/' }
    }
    dependencies {
        /*
            <Other dependencies>
        */
        classpath 'com.huawei.agconnect:agcp:1.4.2.301'
    }
}

/*
    <Other build.gradle entries>
*/

allprojects {
    repositories {
        /*
            <Other repositories>
        */
        maven { url 'https://developer.huawei.com/repo/' }
    }
}
```

**Step 9:** Import the following class to the **MainActivity.java** file of your project. You can find this file in **`android/app/src/main/java/<your_package_name>`** directory.

```java
import com.huawei.hms.js.fido.HMSFIDO;
```

**Step 10:** In the same file, add **add(HMSFIDO.class);** line to the **ArrayList**.

- In the end, your file will be similar to the following:

```java
...

import com.huawei.hms.js.fido.HMSFIDO;

public class MainActivity extends BridgeActivity
{
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        // Initializes the Bridge
        this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
            // Additional plugins you've installed go here
            add(HMSFIDO.class);
        }});
        ...
    }
    ...
}
```

**Step 11:** Updates dependencies, and copy any web assets to your project.

```bash
npx cap sync
```

**Step 12:** Open the project in Android Studio and run it.

```bash
npx cap open android
```

## 3. API Reference

### **HMSFIDO**

#### Public Method Summary

| Method                                                       | Return Type                                                  | Description                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| [getRegistrationIntent(fido2RegistrationReq,callback)](#getregistrationintentfido2registrationreqcallback) | Promise<[Result](#result)\<[Fido2RegistrationRes](#fido2registrationres)>> | The api, obtains Fido2Intent for a common app to start registration. |
| [getAuthenticationIntent(fido2AuthenticationReq,callback)](#getauthenticationintentfido2authenticationreqcallback) | Promise<[Result](#result)\<[Fido2AuthenticationRes](#fido2authenticationres)>> | The api, obtains Fido2Intent for a common app to start authentication. |


### 3.1.2 Public Methods

#### Public Methods

##### getRegistrationIntent(fido2RegistrationReq,callback)

The api, obtains Fido2Intent for a common app to start registration.

| Parameter            | Type                                          | Description                                                  |
| -------------------- | --------------------------------------------- | ------------------------------------------------------------ |
| fido2RegistrationReq | [Fido2RegistrationReq](#fido2registrationreq) | Configuration object for registration.                       |
| callback             | function                                      | A callback function which will be called when registration update is occurred |

| Return Type                                                  | Description                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| Promise<[Result](#result)\<[Fido2RegistrationRes](#fido2registrationres)>> | Returns the Fido2RegistrationRes object on success, throws Exception otherwise. |


###### Sample Code

```js
import HMSFIDO from "@hmscore/hms-js-fido";

const fido2RegistrationReq = {
    nativeOptions: {
        originFormat: HMSFIDO.OriginFormat.ANDROID,
        biometricPromptInfo: null,
        icon: null,
    },
    message: {
        attestation: null,
        authenticatorSelection: {
            authenticatorAttachment: HMSFIDO.Attachment.PLATFORM,
            requireResidentKey: true,
            userVerification: null,
        },
        challenge: [100, 2, 74, -8, -126, 37, 105, 18, -122, -125, 36, 127, -1, 78, -121, -13],
        extensions: {
            hms_ra_c_pacl_01: ["01020304-0506-0708-0102-030405060708"],
            uvi: true,
            hms_r_pa_cibbe_01: true
        },
        pubKeyCredParams: [{
            alg: HMSFIDO.Algorithm.ES256,
            type: HMSFIDO.PublicKeyCredentialType.PUBLIC_KEY
        }, {
            alg: HMSFIDO.Algorithm.RS256,
            type: HMSFIDO.PublicKeyCredentialType.PUBLIC_KEY
        }],
        rp: {
            id: "com.huawei.hms.fido2.test",
            name: "com.huawei.hms.fido2.test",
            icon: null
        },
        excludeList: [
            {
                id: [100, 2, 74, -8, -126, 37, 105, 18, -122, -125, 36, 127, -1, 78, -121, -13],
                type: HMSFIDO.PublicKeyCredentialType.PUBLIC_KEY,
                transports: [
                    HMSFIDO.AuthenticatorTransport.USB,
                    HMSFIDO.AuthenticatorTransport.NFC,
                    HMSFIDO.AuthenticatorTransport.BLE
                ]
            }
        ],
        timeoutSeconds: 60,
        user: {
            displayName: "fidoCp",
            id: [102, 105, 100, 111, 67, 112],
            name: "fidoCp"
        },
        tokenBinding: {
            id:"number",
            status:HMSFIDO.TokenBindingStatus.PRESENT
        }
    },
    appName:"appName",
    operation: HMSFIDO.Operation.REG,
    tokenBinding: {
        id:"number",
        status:HMSFIDO.TokenBindingStatus.PRESENT
    }
};

HMSFIDO.getAuthenticationIntent(
  fido2AuthenticationReq,
  (callbackObj) => {
    console.log(JSON.stringify(callbackObj))
  })
  .then((fido2AuthenticationRes) => console.log(JSON.stringify(fido2AuthenticationRes)))
  .catch((err) => console.log(JSON.stringify(err)));
```

##### getAuthenticationIntent(fido2AuthenticationReq,callback)

The api, obtains Fido2Intent for a common app to start authentication.

| Parameter              | Type                                              | Description                                                  |
| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
| fido2AuthenticationReq | [Fido2AuthenticationReq](#fido2authenticationreq) | FIDO2 authentication request options.                        |
| callback               | function                                          | A callback function which will be called when authentication update is occurred |

| Return Type                                                  | Description                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| Promise<[Result](#result)\<[Fido2AuthenticationRes](#fido2authenticationres)>> | Returns the Fido2AuthenticationRes object on success, throws Exception otherwise. |


###### Sample Code

```js
import HMSFIDO from "@hmscore/hms-js-fido";

const fido2AuthenticationReq = {
    nativeOptions: {
        originFormat: HMSFIDO.OriginFormat.ANDROID,
        biometricPromptInfo: null,
        icon: null,
    },
    message: {
        challenge: [100, 2, 74, -8, -126, 37, 105, 18, -122, -125, 36, 127, -1, 78, -121, -13],
        extensions: {
            hms_ra_c_pacl_01: ["01020304-0506-0708-0102-030405060708"],
            uvi: true,
            hms_r_pa_cibbe_01: true
        },
        rpId: "com.huawei.hms.fido2.test",
        timeoutSeconds: 60,
        allowList: [
            {
                id: [100, 2, 74, -8, -126, 37, 105, 18, -122, -125, 36, 127, -1, 78, -121, -13],
                type: HMSFIDO.PublicKeyCredentialType.PUBLIC_KEY,
                transports: [
                    HMSFIDO.AuthenticatorTransport.USB,
                    HMSFIDO.AuthenticatorTransport.NFC,
                    HMSFIDO.AuthenticatorTransport.BLE
                ]
            }
        ],
    },
    appName:"appName",
    tokenBinding: {
        id:"number",
        status:HMSFIDO.TokenBindingStatus.PRESENT
    },
    operation: HMSFIDO.Operation.SIGN,
};

HMSFIDO.getRegistrationIntent(
  fido2RegistrationReq,
  (callbackObj) => {
    console.log(JSON.stringify(callbackObj))
  })
  .then((fido2RegistrationRes) => console.log(JSON.stringify(fido2RegistrationRes)))
  .catch((err) => console.log(JSON.stringify(err)));
```

### Data Types

#### Overview

| Type                                                         | Description                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| [Result](#result)                                            | Refers to a standard rotating object for each API.           |
| [Fido2RegistrationRes](#fido2registrationres)                | The api, obtains Fido2Intent for a common app to start registration. |
| [Fido2AuthenticationRes](#Fido2RegistrationRes)              | The api, obtains Fido2Intent for a common app to start authentication. |
| [Fido2RegistrationReq](#Fido2RegistrationReq)                | FIDO2 registration request options.                          |
| [Fido2AuthenticationReq](#Fido2AuthenticationReq)            | FIDO2 a authanticate options.                                |
| [CallbackObj](#CallbackObj)                                  | A callback function which will be called when register or authanticate is occurred |
| [RegistrationMessage](#RegistrationMessage)                  | Register message.                                            |
| [AuthenticationMessage](#AuthenticationMessage)              | Authentication message.                                      |
| [Allow](#allow)                                              | Credential parameter to be used for FIDO2 registration or authentication. |
| [NativeOptions](#nativeoptions)                              | FIDO2 registration options.                                  |
| [BiometricPromptInfo](#BiometricPromptInfo)                  | Platform authenticator prompt information.                   |
| [TokenBinding](#tokenbinding)                                | Token binding protocol, which is used for communication between the client and relying party. |
| [AuthenticatorSelectionCriteria](#AuthenticatorSelectionCriteria) | Configuration items related to the authenticator, which are specified by the **WebAuthn** relying party. |
| [Extension](#extension)                                      | Extensions.                                                  |
| [PublicKeyCredentialParameters](#AuthenticatorSelectionCriteria) | Additional parameters provided when a credential is created. |
| [PublicKeyCredentialRpEntity](#PublicKeyCredentialRpEntity)  | Relying party attributes provided when a credential is created. |

#### Result

| Name | Type | Description |
|-------|------|------------|
|status| string | Result status. |
|resultCode| number |Result code.|
|data| object |Result object according to the API.|

#### Fido2RegistrationRes

| Name              | Type     | Description                                                  |
| ----------------- | -------- | ------------------------------------------------------------ |
| attestationObject | number[] | Obtains authentication information returned by the authenticator. |
| clientDataJson    | number[] | Obtains JSON data returned by the client.                    |
| credentialId      | number[] | Obtains a credential ID.                                     |

#### Fido2AuthenticationRes

| Name              | Type     | Description                                                  |
| ----------------- | -------- | ------------------------------------------------------------ |
| authenticatorData | number[] | Obtains authentication information returned by the authenticator and directly passes the information to the server. |
| clientDataJson    | number[] | Obtains JSON data returned by the client.                    |
| credentialId      | number[] | Obtains a credential ID.                                     |
| signature         | number[] | Obtains the final signature of the authenticator. A cryptographic signature that proves that they have credentials. |

#### Fido2RegistrationReq

| Name          | Type                                        | Description                                                  |
| ------------- | ------------------------------------------- | ------------------------------------------------------------ |
| nativeOptions | [NativeOptions](#nativeoptions)             | Sets the authentication prompt information.                  |
| message       | [RegistrationMessage](#registrationmessage) | Sets RegistrationMessage object.                             |
| operation     | [Operation](#operation)                     | Specifies the Api to be invoked. Must be [HMSFIDO.Operation.REG](#operation) |
| tokenBinding  | [TokenBinding](#tokenbinding)                | Sets the token binding protocol.                             |

#### Fido2AuthenticationReq

| Name          | Type                                            | Description                                                  |
| ------------- | ----------------------------------------------- | ------------------------------------------------------------ |
| nativeOptions | [NativeOptions](#nativeoptions)                 | Sets the authentication prompt information.                  |
| message       | [AuthenticationMessage](#authenticationmessage) | Sets the AuthenticationMessage object.                       |
| operation     | [Operation](#operation)                         | Specifies the api to be invoked. Must be [HMSFIDO.Operation.SIGN](#operation) |
| tokenBinding  | [TokenBinding](#tokenbinding)                   | Sets the token binding protocol.                             |

#### CallbackObj

| Name  | Type    | Description     |
| ----- | ------- | --------------- |
| value | boolean | Callback value. |

#### RegistrationMessage

| Name                   | Type                                                         | Description                                                  |
| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| attestation            | [AttestationConveyancePreference](#attestationconveyancepreference) | Sets the preference for passing a credential.                |
| authenticatorSelection | [AuthenticatorSelectionCriteria](#authenticatorselectioncriteria) | Sets configuration items related to the authenticator, which are specified by the **WebAuthn** relying party. |
| challenge              | number[]                                                     | Sets a challenge.                                            |
| extensions             | [Extension](#extension)                                      | Sets extensions.                                             |
| pubKeyCredParams       | [PublicKeyCredentialParameters[]](#publickeycredentialparameters) | Sets an array of additional credential parameters.           |
| rp                     | [PublicKeyCredentialRpEntity](#publickeycredentialrpentity)  | Sets relying party attributes for creating a credential.     |
| timeoutSeconds         | number                                                       | Sets a timeout interval.                                     |
| user                   | [PublicKeyCredentialUserEntity](#publickeycredentialparameters) | Sets user account information.                               |

#### AuthenticationMessage

| Name           | Type                    | Description              |
| -------------- | ----------------------- | ------------------------ |
| rpId           | string                  | Sets a request ID.       |
| challenge      | number[]                | Sets a challenge.        |
| allowList      | [Allow](#allow)[]       | Sets a trustlist.        |
| extensions     | [Extension](#extension) | Sets extensions.         |
| timeoutSeconds | number                  | Sets a timeout interval. |

#### Allow

| Name       | Type     | Description                                                  |
| ---------- | -------- | ------------------------------------------------------------ |
| id         | number[] | Obtains a credential id.                                     |
| type       | string   | Obtains a credential type.  Value: [HMSFIDO.PublicKeyCredentialType.PUBLIC_KEY](#publickeycredentialtype) |
| transports | string[] | Obtains an authenticator access type array. Values: [HMSFIDO.AuthenticatorTransport.USB](#authenticatortransport) , [HMSFIDO.AuthenticatorTransport.NFC](#authenticatortransport), [HMSFIDO.AuthenticatorTransport.BLE](#authenticatortransport) |

#### NativeOptions

| Name                | Type                                        | Description                                         |
| ------------------- | ------------------------------------------- | --------------------------------------------------- |
| originFormat        | string                                      | Origin format.                                      |
| biometricPromptInfo | [BiometricPromptInfo](#biometricpromptinfo) | Sets the platform authenticator prompt information. |
| icon                | string                                      | Relying party icon.                                 |

#### BiometricPromptInfo

| Name        | Type   | Description                                                  |
| ----------- | ------ | ------------------------------------------------------------ |
| title       | string | Title of the fingerprint or 3D facial authentication popup.  |
| description | string | Description of the fingerprint or 3D facial authentication popup. |

#### TokenBinding

| Name              | Type                | Description                                                  |
| ----------------- | ------------------- | ------------------------------------------------------------ |
| status            | string              | Token binding status of the client. The states are as follows:  [HMSFIDO.TokenBindingStatus.PRESENT](#tokenbindingstatus): The client is communicating with the relying party. [HMSFIDO.TokenBindingStatus.STATUS](#tokenbindingstatus): Token binding is supported, but the client is not communicating with the relying party currently. |
| id                | string              | Token binding ID.                                            |

#### AuthenticatorSelectionCriteria

| Name                    | Type    | Description                                                  |
| ----------------------- | ------- | ------------------------------------------------------------ |
| authenticatorAttachment | string  | Obtains the used authenticator type.   Values: [HMSFIDO.Attachment.PLATFORM](#attachment), [HMSFIDO.Attachment.CROSS_PLATFORM](#attachment) |
| requireResidentKey      | boolean | Checks whether the authenticator needs to store credentials. |
| userVerification        | string  | Obtains the setting that specifies whether to verify the user identity. |

#### Extension

| Name                   | Type     | Description                                                  |
| ---------------------- | -------- | ------------------------------------------------------------ |
| hms_ra_c_pacl_01       | string[] | Multi-platform authenticator selection strategy              |
| uvi                    | boolean  | Identify fingerprint ID                                      |
| hms_r_pa_cibbe_01      | boolean  | Whether the authentication credential becomes invalid when the biometrics change |

#### PublicKeyCredentialParameters

| Name               | Type                | Description                                                  |
| ------------------ | ------------------- | ------------------------------------------------------------ |
| type          | string       | Sets a credential type.  Values: [HMSFIDO.PublicKeyCredentialType.PUBLIC_KEY](#publickeycredentialtype) |
| alg           | string       | Sets the supported algorithm.  Values: [HMSFIDO.Algorithm.ES256](#algorithm), [HMSFIDO.Algorithm.ES384](#algorithm), [HMSFIDO.Algorithm.ES512](#algorithm), [HMSFIDO.Algorithm.RS256](#algorithm), [HMSFIDO.Algorithm.RS384](#algorithm), [HMSFIDO.Algorithm.RS512](#algorithm), [HMSFIDO.Algorithm.PS256](#algorithm), [HMSFIDO.Algorithm.PS384](#algorithm), [HMSFIDO.Algorithm.PS512](#algorithm), [HMSFIDO.Algorithm.ECDH](#algorithm) |

#### PublicKeyCredentialRpEntity

| Name        | Type          | Description         |
| ----------- | ------------- | ------------------- |
| id          | string        | Relying party ID.   |
| name        | string        | Relying party name. |
| icon        | string        | Relying party icon. |

#### PublicKeyCredentialUserEntity

| Name           | Type   | Description   |
| -------------- | ------ | ------------- |
| id             | string | User Id.      |
| name           | string | User name.    |
| dislayName     | string | Display name. |

### Constants

#### Overview

| Type                                                   | Description                                                  |
| ------------------------------------------------------ | ------------------------------------------------------------ |
| [OriginFormat](#OriginFormat)                          | Origin format.                                               |
| [Operation](#Operation)                                | It is the parametre that specifies which api to call.        |
| [TokenBindingStatus](#TokenBindingStatus)              | Communication status between the client and relying party.   |
| [AttestationConveyancePreference](#TokenBindingStatus) | Credential passing preferences, which are used for reference by the WebAuthn relying party when the credential is created. |
| [Attachment](#Attachment)                              | Authenticator types.                                         |
| [Fido2Extension](#Fido2Extension)                      | Extensions.                                                  |
| [PublicKeyCredentialType](#PublicKeyCredentialType)    | Credential type                                              |
| [Algorithm](#Algorithm)                                | Supported algorithms.                                        |
| [AuthenticatorTransport](#AuthenticatorTransport)      | Authenticator access types, including USB, NFC, and Bluetooth. |
| [ResultCodes](#ResultCodes)                            | Result codes.                                                |

#### OriginFormat

| Name | Value | Description |
|-------|------|-------------|
| HMSFIDO.OriginFormat.HTML | "HTML" | Standard HTML format. |
| HMSFIDO.OriginFormat.ANDROID | "ANDROID" | Android format. |

#### Operation

| Name                   | Value  | Description           |
| ---------------------- | ------ | --------------------- |
| HMSFIDO.Operation.REG  | "reg"  | Standard HTML format. |
| HMSFIDO.Operation.SIGN | "sign" | Android format.       |

#### TokenBindingStatus

| Name                               | Value     | Description                                                  |
| ---------------------------------- | --------- | ------------------------------------------------------------ |
| HMSFIDO.TokenBindingStatus.PRESENT | "PRESENT" | The client is communicating with the relying party.          |
| HMSFIDO.TokenBindingStatus.STATUS  | "STATUS"  | Token binding is supported, but the client is not communicating with the relying party currently. |

#### AttestationConveyancePreference

| Name                                             | Value      | Description                                                  |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------ |
| HMSFIDO.AttestationConveyancePreference.NONE     | "NONE"     | The relying party does not require the authenticator to provide an attestation file. This is the default value. |
| HMSFIDO.AttestationConveyancePreference.DIRECT   | "DIRECT"   | The relying party requires that an attestation file generated by the authenticator be provided. |
| HMSFIDO.AttestationConveyancePreference.INDIRECT | "INDIRECT" | The relying party prefers to providing an attestation file that can be verified but allows the customer to decide how to obtain such a file. The client may replace the attestation file generated by the authenticator with the attestation file generated by the anonymous CA to protect user privacy, or assist the relying party in attestation verification in a heterogeneous ecosystem. |

#### Attachment

| Name                              | Value            | Description                                                  |
| --------------------------------- | ---------------- | ------------------------------------------------------------ |
| HMSFIDO.Attachment.PLATFORM       | "PLATFORM"       | Platform authenticator, such as a fingerprint or facial feature authenticator. |
| HMSFIDO.Attachment.CROSS_PLATFORM | "CROSS_PLATFORM" | Cross-platform authenticator, also called roaming authenticator, such as a Bluetooth, NFC, or USB authenticator |

#### Fido2Extension

| Name                                     | Value               | Description                                                  |
| ---------------------------------------- | ------------------- | ------------------------------------------------------------ |
| HMSFIDO.Fido2Extension.HMS_RA_C_PACL_01  | "hms_ra_c_pacl_01"  | Policy for selecting a platform authenticator. This field is valid for both registration and authentication APIs. |
| HMSFIDO.Fido2Extension.W3C_WEBAUTHN_UVI  | "uvi"               | Indicates whether to identify the fingerprint ID. This field is valid for both registration and authentication APIs is supported only by the fingerprint platform authenticator. |
| HMSFIDO.Fido2Extension.HMS_R_PA_CIBBE_01 | "hms_r_pa_cibbe_01" | Indicates whether the authentication credential expires when the fingerprint or facial feature is recorded. This parameter is valid only for the registration API and platform authenticators (fingerprint and 3D facial feature). |

#### PublicKeyCredentialType

| Name                                       | Value        | Description |
| ------------------------------------------ | ------------ | ----------- |
| HMSFIDO.PublicKeyCredentialType.PUBLIC_KEY | "PUBLIC_KEY" | Public Key. |

#### Algorithm

| Name                    | Value   | Description      |
| ----------------------- | ------- | ---------------- |
| HMSFIDO.Algorithm.ES256 | "ES256" | ES256 algorithm. |
| HMSFIDO.Algorithm.ES384 | "ES384" | ES384 algorithm. |
| HMSFIDO.Algorithm.ES512 | "ES512" | ES512 algorithm. |
| HMSFIDO.Algorithm.RS256 | "RS256" | RS256 algorithm. |
| HMSFIDO.Algorithm.RS384 | "RS384" | RS384 algorithm. |
| HMSFIDO.Algorithm.RS512 | "RS512" | RS512 algorithm. |
| HMSFIDO.Algorithm.PS256 | "PS256" | PS256 algorithm. |
| HMSFIDO.Algorithm.PS384 | "PS384" | PS384 algorithm. |
| HMSFIDO.Algorithm.PS512 | "PS512" | PS512 algorithm. |
| HMSFIDO.Algorithm.ECDH  | "ECDH"  | ECDH v           |

#### AuthenticatorTransport

| Name                               | Value | Description                         |
| ---------------------------------- | ----- | ----------------------------------- |
| HMSFIDO.AuthenticatorTransport.USB | "USB" | USB authenticator.                  |
| HMSFIDO.AuthenticatorTransport.NFC | "NFC" | NFC authenticator.                  |
| HMSFIDO.AuthenticatorTransport.BLE | "BLE" | Bluetooth low energy authenticator. |

### Result Codes

| Result Code | Descriptive Name                                             |
| ----------- | ------------------------------------------------------------ |
| 0           | SUCCESS                                                      |
| -1          | Common error code upon a failure.                            |
| 50001       | FIDO Kit is not started.Please try again.                    |
| 50002       | A child account is signed in, which does not support FIDO Kit.Switch to another HUAWEI ID. |
| 50003       | Failed to authenticate the HUAWEI ID.Sign in with the HUAWEI ID again. |
| 30008       | Failed to obtain the HUAWEI ID information.Sign in with the HUAWEI ID again. |
| 60053       | The product has been consumed and cannot be consumed again.  |
| 60054       | The FIDO service is not supported in the current locale      |
| 60055       | Children account do not support FIDO service                 |
| 60056       | The user triggers risk control, and the transaction is rejected. |
| 6003        | StatusCode.CERT_FINGERPRINT_ERROR                            |
| 1217        | ERRORCODE.AUTH_FAILED                                        |
| 700111      | UPGRADE_FAILED                                               |


## 4. Configuration and Description

### Configuring Obfuscation Scripts

#### React Native

In order to prevent error while release build, you may need to add following lines in **`proguard-rules.pro`** file.

```text
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keep class com.hianalytics.android.**{*;}
-keep class com.huawei.updatesdk.**{*;}
-keep class com.huawei.hms.**{*;}
-repackageclasses
```

#### Cordova

Before building the APK, configure the obfuscation configuration file to prevent the HMS Core SDK from being obfuscated.

**NOTE**: This step is required only if you want to minify and obfuscate your app. By default obfuscation is disabled in Cordova and Ionic apps.

The obfuscation is done by **`ProGuard`.** By default, in Cordova and Ionic apps ProGuard is disabled. Even though ProGuard is not available, ProGuard support can be added through 3rd party ProGuard plugins. If ProGuard is enabled in your project, the Huawei Cordova FIDO plugin's ProGuard rules need to be added to your project. These rules are as follows:

```text
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keep class com.huawei.hianalytics.**{*;}
-keep class com.huawei.updatesdk.**{*;}
-keep class com.huawei.hms.**{*;}
-repackageclasses
```

---

## 5. Questions or Issues

If you have questions about how to use HMS samples, try the following options:

- [Stack Overflow](https://stackoverflow.com/questions/tagged/huawei-mobile-services) is the best place for any programming questions. Be sure to tag your question with **huawei-mobile-services**.
- [Huawei Developer Forum](https://forums.developer.huawei.com/forumPortal/en/home?fid=0101187876626530001&ha_source=hms1) HMS Core Module is great for general questions, or seeking recommendations and opinions.
- [Huawei Developer Docs](https://developer.huawei.com/consumer/en/doc/overview/HMS-Core-Plugin?ha_source=hms1) is place to official documentation for all HMS Core Kits, you can find detailed documentations in there.

---

## 6. Licensing and Terms

Huawei JS SDK is licensed under [Apache 2.0 license](LICENCE).