Class3BiometricOrCredentialAuthExtensionsKt

Added in 1.4.0-alpha02

public final class Class3BiometricOrCredentialAuthExtensionsKt


Summary

Public methods

static final @NonNull BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

static final @NonNull BiometricPrompt.AuthenticationResult
@RequiresApi(value = 30)
authenticateWithClass3BiometricsOrCredentials(
    @NonNull Fragment receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

static final @NonNull BiometricPrompt.AuthenticationResult
@RequiresApi(value = 30)
authenticateWithClass3BiometricsOrCredentials(
    @NonNull FragmentActivity receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

static final @NonNull AuthPrompt
@RequiresApi(value = 30)
startClass3BiometricOrCredentialAuthentication(
    @NonNull Fragment receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired,
    Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

static final @NonNull AuthPrompt
@RequiresApi(value = 30)
startClass3BiometricOrCredentialAuthentication(
    @NonNull FragmentActivity receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired,
    Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Public methods

@RequiresApi(value = 30)
public static final @NonNull BiometricPrompt.AuthenticationResult authenticate(
    @NonNull Class3BiometricOrCredentialAuthPrompt receiver,
    @NonNull AuthPromptHost host,
    BiometricPrompt.CryptoObject crypto
)

Shows an authentication prompt to the user.

import androidx.biometric.BiometricPrompt
import androidx.biometric.auth.AuthPromptErrorException
import androidx.biometric.auth.AuthPromptFailureException
import androidx.biometric.auth.AuthPromptHost
import androidx.biometric.auth.Class3BiometricOrCredentialAuthPrompt
import androidx.biometric.auth.CredentialAuthPrompt
import androidx.biometric.auth.authenticate

// To use Class3 authentication, we need to create a CryptoObject.
// First create a spec for the key to be generated.
val keyPurpose = KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
val keySpec =
    KeyGenParameterSpec.Builder(KEY_NAME, keyPurpose)
        .apply {
            setBlockModes(KeyProperties.BLOCK_MODE_CBC)
            setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
            setUserAuthenticationRequired(true)

            // Require authentication for each use of the key.
            val timeout = 0
            // Set the key type according to the allowed auth types.
            val keyType =
                KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL
            setUserAuthenticationParameters(timeout, keyType)
        }
        .build()

// Generate and store the key in the Android keystore.
KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE_INSTANCE).run {
    init(keySpec)
    generateKey()
}

// Prepare the crypto object to use for authentication.
val cipher =
    Cipher.getInstance(
            "${KeyProperties.KEY_ALGORITHM_AES}/${KeyProperties.BLOCK_MODE_CBC}/" +
                KeyProperties.ENCRYPTION_PADDING_PKCS7
        )
        .apply {
            val keyStore = KeyStore.getInstance(KEYSTORE_INSTANCE).apply { load(null) }
            init(Cipher.ENCRYPT_MODE, keyStore.getKey(KEY_NAME, null) as SecretKey)
        }

val cryptoObject = BiometricPrompt.CryptoObject(cipher)
val payload = "A message to encrypt".toByteArray(Charset.defaultCharset())

// Construct AuthPrompt with localized Strings to be displayed to UI.
val authPrompt =
    Class3BiometricOrCredentialAuthPrompt.Builder(title)
        .apply {
            setSubtitle(subtitle)
            setDescription(description)
            setConfirmationRequired(true)
        }
        .build()

try {
    val authResult = authPrompt.authenticate(AuthPromptHost(this), cryptoObject)

    // Encrypt a payload using the result of crypto-based auth.
    val encryptedPayload = authResult.cryptoObject?.cipher?.doFinal(payload)

    // Use the encrypted payload somewhere interesting.
    sendEncryptedPayload(encryptedPayload)
} catch (e: AuthPromptErrorException) {
    // Handle irrecoverable error during authentication.
    // Possible values for AuthPromptErrorException.errorCode are listed in the @IntDef,
    // androidx.biometric.BiometricPrompt.AuthenticationError.
} catch (e: AuthPromptFailureException) {
    // Handle auth failure due biometric credentials being rejected.
}
Parameters
@NonNull AuthPromptHost host

A wrapper for the component that will host the prompt.

BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

Returns
@NonNull BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

See also
authenticate

( AuthPromptHost, AuthPromptCallback )

authenticateWithClass3BiometricsOrCredentials

@RequiresApi(value = 30)
public static final @NonNull BiometricPrompt.AuthenticationResult authenticateWithClass3BiometricsOrCredentials(
    @NonNull Fragment receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

CharSequence subtitle

An optional subtitle to be displayed on the prompt.

CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

Returns
@NonNull BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass3BiometricsOrCredentials

@RequiresApi(value = 30)
public static final @NonNull BiometricPrompt.AuthenticationResult authenticateWithClass3BiometricsOrCredentials(
    @NonNull FragmentActivity receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

CharSequence subtitle

An optional subtitle to be displayed on the prompt.

CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

Returns
@NonNull BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

startClass3BiometricOrCredentialAuthentication

@RequiresApi(value = 30)
public static final @NonNull AuthPrompt startClass3BiometricOrCredentialAuthentication(
    @NonNull Fragment receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired,
    Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

CharSequence subtitle

An optional subtitle to be displayed on the prompt.

CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

Executor executor

An executor for callback methods. If null, these will run on the main thread.

@NonNull AuthPromptCallback callback

The object that will receive and process authentication events.

Returns
@NonNull AuthPrompt

An AuthPrompt handle to the shown prompt.

startClass3BiometricOrCredentialAuthentication

@RequiresApi(value = 30)
public static final @NonNull AuthPrompt startClass3BiometricOrCredentialAuthentication(
    @NonNull FragmentActivity receiver,
    BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    CharSequence subtitle,
    CharSequence description,
    boolean confirmationRequired,
    Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

CharSequence subtitle

An optional subtitle to be displayed on the prompt.

CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

Executor executor

An executor for callback methods. If null, these will run on the main thread.

@NonNull AuthPromptCallback callback

The object that will receive and process authentication events.

Returns
@NonNull AuthPrompt

An AuthPrompt handle to the shown prompt.