目录

Authentication Using Passkeys (C/C++)

API Description

The following table lists the main APIs provided by the passkey service.

API Description
FIDO2_ErrorCode HMS_FIDO2_getClientCapability(FIDO2_CapabilityArray ** capability) Queries the client capabilities supported by the current device.
FIDO2_ErrorCode HMS_FIDO2_getPlatformAuthenticator(FIDO2_AuthenticatorMetadataArray **authenticators) Queries the platform authenticator capabilities (face, fingerprint, and PIN) supported by the current device.
FIDO2_ErrorCode HMS_FIDO2_register(const FIDO2_CredentialCreationOptions options, const FIDO2_TokenBinding tokenBinding, const char * origin, FIDO2_PublicKeyAttestationCredential ** publicKeyAttestationCredential ) Registers a passkey.
FIDO2_ErrorCode HMS_FIDO2_authenticate(const FIDO2_CredentialRequestOptions options, const FIDO2_TokenBinding tokenBinding, const char *origin, FIDO2_PublicKeyAssertionCredential **publicKeyAssertionCredential) Performs authentication using a passkey.

Development Procedure

The passkey service provides a FIDO client implementation based on FIDO2 standards. The following only demonstrates the usage of FIDO client APIs. You are responsible for implementing the logic related to the FIDO server. For details, please refer to the FIDO2 standard protocol (see website link disclaimer).

Link the related dynamic library in the CMake script.

target_link_libraries(projectName libfido2_ndk.z.so)

  1. Deploy the FIDO server in accordance with FIDO2 standards.

  2. Register a passkey.

    1. Obtain capability information. Call the HMS_FIDO2_getClientCapability API to obtain the client capability list, and call the HMS_FIDO2_getPlatformAuthenticator API to obtain the platform authenticator capability list. 
      #include "OnlineAuthenticationKit/fido2_api.h"

FIDO2_ErrorCode TestGetClientCapability()
{
    // Obtain the client capability list.
    FIDO2_CapabilityArray *capability = NULL;
    FIDO2_ErrorCode ret = HMS_FIDO2_getClientCapability(&capability);

    // Determine the error type based on the error code and rectify the fault accordingly. For details, please refer to the error code reference.
    if (ret != FIDO2_SUCCESS) {
        HMS_FIDO2_CapabilityArray_Destroy(capability);
        return ret;
    }
    return FIDO2_SUCCESS;
}

FIDO2_ErrorCode GetPlatformAuthenticator()
{
    // Obtain the platform authenticator capability list.
    FIDO2_AuthenticatorMetadataArray *authenticators = NULL;
    FIDO2_ErrorCode ret = HMS_FIDO2_getPlatformAuthenticator(&authenticators);

    // Determine the error type based on the error code and rectify the fault accordingly. For details, please refer to the error code reference.
    if (ret != FIDO2_SUCCESS) {
        HMS_FIDO2_AuthenticatorMetadataArray_Destroy(authenticators);
        return ret;
    }
    return FIDO2_SUCCESS;
}
    2. Access the FIDO server, obtain the registration message, and call the HMS_FIDO2_register API for registration. 
      FIDO2_ErrorCode TestReg()
{
    // Initialize the registration parameters. The init method must be called.
    FIDO2_CredentialCreationOptions options;
    HMS_FIDO2_initCreationOptions(&options);

    // Registration message returned by the FIDO server. The specific message content is determined by you.
    FIDO2_PublicKeyCredentialCreationOptions publicKey;

    // Assemble registration information, including whether user mediation is required and the registration message.
    options.mediation = FIDO2_CONDITIONAL;
    options.publicKey = publicKey;

    // Initialize the tokenBinding parameter. You do not need to assign a value to this parameter, but the init method must be called.
    FIDO2_TokenBinding tokenBinding;
    HMS_FIDO2_initTokenBinding(&tokenBinding);

    // Origin used for testing only. Change it based on your service needs.
    char *origin = "http://www.fidotest.com";

    // Call HMS_FIDO2_register to register a passkey.
    FIDO2_PublicKeyAttestationCredential* publicKeyAttestationCredential = NULL;
    FIDO2_ErrorCode ret = HMS_FIDO2_register(options, tokenBinding, origin, &publicKeyAttestationCredential);

    // Determine the error type based on the error code and rectify the fault accordingly. For details, please refer to the error code reference.
    if (ret != FIDO2_SUCCESS) {
        HMS_FIDO2_PublicKeyAttestationCredential_Destroy(publicKeyAttestationCredential);
        return ret;
    }
    return FIDO2_SUCCESS;
}
    3. Assemble a registration response message based on the registration result (publicKeyAttestationCredential), send the message to the FIDO server for verification, and obtain the registration result message.

  3. Use the password for authentication.

    1. Obtain capability information. Call the HMS_FIDO2_getClientCapability API to obtain the client capability list, and call the HMS_FIDO2_getPlatformAuthenticator API to obtain the platform authenticator capability list. 
      #include "OnlineAuthenticationKit/fido2_api.h"

FIDO2_ErrorCode TestGetClientCapability()
{
    // Obtain the client capability list.
    FIDO2_CapabilityArray *capability = NULL;
    FIDO2_ErrorCode ret = HMS_FIDO2_getClientCapability(&capability);

    // Determine the error type based on the error code and rectify the fault accordingly. For details, please refer to the error code reference.
    if (ret != FIDO2_SUCCESS) {
        HMS_FIDO2_CapabilityArray_Destroy(capability);
        return ret;
    }
    return FIDO2_SUCCESS;
}

FIDO2_ErrorCode GetPlatformAuthenticator()
{
    // Obtain the platform authenticator capability list.
    FIDO2_AuthenticatorMetadataArray *authenticators = NULL;
    FIDO2_ErrorCode ret = HMS_FIDO2_getPlatformAuthenticator(&authenticators);

    // Determine the error type based on the error code and rectify the fault accordingly. For details, please refer to the error code reference.
    if (ret != FIDO2_SUCCESS) {
        HMS_FIDO2_AuthenticatorMetadataArray_Destroy(authenticators);
        return ret;
    }
    return FIDO2_SUCCESS;
}
    2. Access the FIDO server, obtain the authentication message, and call the HMS_FIDO2_authenticate API for authentication. 
      FIDO2_ErrorCode TestAuth()
{
    // Initialize the authentication parameters. The init method must be called.
    FIDO2_CredentialRequestOptions options;
    HMS_FIDO2_initRequestOptions(&options);

    // Authentication message returned by the FIDO server. The specific message content is determined by you.
    FIDO2_PublicKeyCredentialRequestOptions publicKey;

    // Assemble authentication information, including whether user mediation is required and the authentication message.
    options.mediation = FIDO2_CONDITIONAL;
    options.publicKey = publicKey;

    // Initialize the tokenBinding parameter. You do not need to assign a value to this parameter, but the init method must be called.
    FIDO2_TokenBinding tokenBinding;
    HMS_FIDO2_initTokenBinding(&tokenBinding);

    // Origin used for testing only. Change it based on your service needs.
    char *origin = "http://www.fidotest.com";

    // Call HMS_FIDO2_authenticate to authenticate the passkey.
    FIDO2_PublicKeyAssertionCredential *assertionCredential = NULL;
    FIDO2_ErrorCode ret = HMS_FIDO2_authenticate(options, tokenBinding, origin, &assertionCredential);

    // Determine the error type based on the error code and rectify the fault accordingly. For details, please refer to the error code reference.
    if (ret != FIDO2_SUCCESS) {
        HMS_FIDO2_PublicKeyAssertionCredential_Destroy(assertionCredential);
        return ret;
    }
    return FIDO2_SUCCESS;
}
    3. Assemble an authentication response message based on the authentication result (assertionCredential), send the message to the FIDO server for verification, and obtain the authentication result message.