Document

Fingerprint Authentication

Huawei provides the secure fingerprint authentication capability. If the system is insecure, the callback method BioAuthnCallback.onAuthError() returns the error code BioAuthnPrompt.ERROR_SYS_INTEGRITY_FAILED. If the system is secure, fingerprint authentication is performed. For details about the fingerprint authentication error codes, please refer to the API Reference.

NOTICE

Only EMUI 4.0 and later versions support fingerprint authentication.

To use the fingerprint authentication capability, perform the following steps:

Create BioAuthnPrompt and BioAuthnCallback objects.

Java

Kotlin

private BioAuthnPrompt createBioAuthnPrompt() {
     // Callback.
     BioAuthnCallback callback = new BioAuthnCallback() {
         @Override
         public void onAuthError(int errMsgId, CharSequence errString) {
             showResult("Authentication error. errorCode=" + errMsgId + ",errorMessage=" + errString);
         }
         @Override
         public void onAuthSucceeded(BioAuthnResult result) {
             showResult("Authentication succeeded. CryptoObject=" + result.getCryptoObject());
         }
         @Override
         public void onAuthFailed() {
             showResult("Authentication failed.");
         }
     };
     return new BioAuthnPrompt(this, ContextCompat.getMainExecutor(this), callback);
 }

private fun createBioAuthnPrompt(): BioAuthnPrompt {
     // Callback.
     val callback = object : BioAuthnCallback() {
         override fun onAuthError(errMsgId: Int, errString: CharSequence) {
             showResult("Authentication error. errorCode=$errMsgId,errorMessage=$errString")
         }
         override fun onAuthSucceeded(result: BioAuthnResult) {
             if (result.cryptoObject != null) {
                 showResult("Authentication succeeded. CryptoObject=" + result.cryptoObject!!)
             } else {
                 showResult("Authentication succeeded. CryptoObject=null")
             }
         }
         override fun onAuthFailed() {
             showResult("Authentication failed.")
         }
     }
     return BioAuthnPrompt(this, ContextCompat.getMainExecutor(this), callback)
 }

Build prompt information and perform authentication.

NOTICE

When you create PromptInfo using PromptInfo.Builder, you can only select either setDeviceCredentialAllowed(true) or setNegativeButtonText(). setDeviceCredentialAllowed(true) allows change from fingerprint authentication to another authentication mode, for example, lock screen password authentication.
When using BioAuthnPrompt.PromptInfo.Builder.setDeviceCredentialAllowed(true), pay attention to the following:
1. This function does not support devices with in-screen fingerprint sensors and running EMUI 9.x, for example, Mate 20 Pro, P30, P30 Pro, and Magic 2. If the function is used on these devices, the authentication will fail immediately when users change the authentication mode to lock screen password authentication.
2. In EMUI 9.x or earlier, fingerprint authentication may work once only. You can solve this problem in one of the following ways:
  - Do not create the BioAuthnPrompt object for the activity repeatedly.
  - After the authentication is complete, call the Activity.recreate() method to recreate the UI.
  - Close the activity and open it again.

Java

Kotlin

// Build prompt information.
BioAuthnPrompt.PromptInfo.Builder builder =
     new BioAuthnPrompt.PromptInfo.Builder().setTitle("This is the title.")
         .setSubtitle("This is the subtitle")
         .setDescription("This is the description");
// The user will first be prompted to authenticate with biometrics, but also given the option to
 // authenticate with their device PIN, pattern, or password. setNegativeButtonText(CharSequence) should
 // not be set if this is set to true.
builder.setDeviceCredentialAllowed(true);
// Set the text for the negative button. setDeviceCredentialAllowed(true) should not be set if this button text
 // is set.
 // builder.setNegativeButtonText("This is the 'Cancel' button.");
BioAuthnPrompt.PromptInfo info = builder.build();
resultTextView.setText("Start fingerprint authentication without CryptoObject.\nAuthenticating......\n");
 bioAuthnPrompt.auth(info);

// Build prompt information.
val builder = BioAuthnPrompt.PromptInfo.Builder().setTitle("This is the title.")
         .setSubtitle("This is the subtitle")
         .setDescription("This is the description")
// The user will first be prompted to authenticate with biometrics, but also given the option to
 // authenticate with their device PIN, pattern, or password. setNegativeButtonText(CharSequence) should
 // not be set if this is set to true.
builder.setDeviceCredentialAllowed(true)
// Set the text for the negative button. setDeviceCredentialAllowed(true) should not be set if this button text
 // is set.
 // builder.setNegativeButtonText("This is the 'Cancel' button.");
val info = builder.build()
resultTextView!!.text = "Start fingerprint authentication without CryptoObject.\nAuthenticating......\n"
 bioAuthnPrompt!!.auth(info)

Facial Authentication

Huawei provides the secure facial authentication capability. If the system is insecure, the callback method BioAuthnCallback.onAuthError returns the error code FaceManager.FACE_ERROR_SYS_INTEGRITY_FAILED. If the system is secure, facial authentication is performed. For details about the facial authentication error codes, please refer to the API Reference.

NOTICE

Only EMUI 10.0 (API Level 29) and later versions support facial authentication. In addition, the device hardware must support facial authentication.
Facial authentication is supported on devices running EMUI 10.0 or later and where the return value for the getFaceModality method in FaceManager is 2 or 3. Facial authentication is not supported if the return value is 1.
When CryptoObject is used for authentication and KeyGenParameterSpec.Builder is used to generate a key, false must be passed to setUserAuthenticationRequired(). In this version, the KeyStore is not associated with the facial authentication result.

To use the facial authentication capability, perform the following steps:

Build a BioAuthnCallback object.

Java

Kotlin

// Callback.
BioAuthnCallback callback = new BioAuthnCallback() {
    @Override
    public void onAuthError(int errMsgId, CharSequence errString) {
        showResult("Authentication error. errorCode=" + errMsgId + ",errorMessage=" + errString
            + (errMsgId == 1012 ? " The camera permission may not be enabled." : ""));
    }
    @Override
    public void onAuthHelp(int helpMsgId, CharSequence helpString) {
        resultTextView
            .append("Authentication help. helpMsgId=" + helpMsgId + ",helpString=" + helpString + "\n");
    }
    @Override
    public void onAuthSucceeded(BioAuthnResult result) {
        showResult("Authentication succeeded. CryptoObject=" + result.getCryptoObject());
    }
    @Override
    public void onAuthFailed() {
        showResult("Authentication failed.");
    }
};

// Callback.
val callback = object : BioAuthnCallback() {
    override fun onAuthError(errMsgId: Int, errString: CharSequence) {
        showResult("Authentication error. errorCode=" + errMsgId + ",errorMessage=" + errString
                + if (errMsgId == 1012) " The camera permission may not be enabled." else "")
    }
    override fun onAuthHelp(helpMsgId: Int, helpString: CharSequence) {
        resultTextView!!
                .append("Authentication help. helpMsgId=$helpMsgId,helpString=$helpString\n")
    }
    override fun onAuthSucceeded(result: BioAuthnResult) {
        showResult("Authentication succeeded.")
    }
    override fun onAuthFailed() {
        showResult("Authentication failed.")
    }
}

Build a FaceManager object and call the auth method.

Java

Kotlin

// Cancellation signal.
CancellationSignal cancellationSignal = new CancellationSignal();
FaceManager faceManager = new FaceManager(this);
// Flags.
int flags = 0;
// Authentication message handler.
Handler handler = null;
// You are advised to set CryptoObject to null. KeyStore is not associated with face authentication in the current
// version. KeyGenParameterSpec.Builder.setUserAuthenticationRequired() must be set to false in this scenario.
CryptoObject crypto = null;
faceManager.auth(crypto, cancellationSignal, flags, callback, handler);

// Cancellation signal.
val cancellationSignal = CancellationSignal()
val faceManager = FaceManager(this) 
// Flags.
val flags = 0
// Authentication message handler.
val handler: Handler? = null
// You are advised to set CryptoObject to null. KeyStore is not associated with face authentication in the current
// version. KeyGenParameterSpec.Builder.setUserAuthenticationRequired() must be set to false in this scenario.
val crypto: CryptoObject? = null
faceManager.auth(crypto, cancellationSignal, flags, callback, handler)

NOTE

For details about the complete sample code, please refer to BioAuthn-AndroidX.

Integrating the BioAuthn-AndroidX SDK

Fingerprint Authentication

Facial Authentication