Class3BiometricAuthExtensionsKt

public final class Class3BiometricAuthExtensionsKt


Summary

Public methods

static final @NonNull BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

static final @NonNull AuthPrompt
Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull FragmentActivity receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired,
    @Nullable Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g.

static final @NonNull BiometricPrompt.AuthenticationResult
Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull FragmentActivity receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g.

static final @NonNull AuthPrompt
Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull Fragment receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired,
    @Nullable Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g.

static final @NonNull BiometricPrompt.AuthenticationResult
Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull Fragment receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g.

Public methods

Class3BiometricAuthExtensionsKt.authenticate

@NonNull
public static final BiometricPrompt.AuthenticationResult Class3BiometricAuthExtensionsKt.authenticate(
    @NonNull Class3BiometricAuthPrompt receiver,
    @NonNull AuthPromptHost host,
    @Nullable BiometricPrompt.CryptoObject crypto
)

Shows an authentication prompt to the user.

import androidx.biometric.auth.AuthPromptHost
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 = Class3BiometricAuthPrompt.Builder(title, negativeButtonText).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.

@Nullable BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

Returns
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)

Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics

@NonNull
public static final AuthPrompt Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull FragmentActivity receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired,
    @Nullable Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
@Nullable BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

@NonNull CharSequence negativeButtonText

The label for the negative button on the prompt.

@Nullable CharSequence subtitle

An optional subtitle to be displayed on the prompt.

@Nullable CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

@Nullable 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
AuthPrompt

An AuthPrompt handle to the shown prompt.

Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics

@NonNull
public static final BiometricPrompt.AuthenticationResult Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull FragmentActivity receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
@Nullable BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

@NonNull CharSequence negativeButtonText

The label for the negative button on the prompt.

@Nullable CharSequence subtitle

An optional subtitle to be displayed on the prompt.

@Nullable CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

Returns
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.

Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics

@NonNull
public static final AuthPrompt Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull Fragment receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired,
    @Nullable Executor executor,
    @NonNull AuthPromptCallback callback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
@Nullable BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

@NonNull CharSequence negativeButtonText

The label for the negative button on the prompt.

@Nullable CharSequence subtitle

An optional subtitle to be displayed on the prompt.

@Nullable CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

@Nullable 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
AuthPrompt

An AuthPrompt handle to the shown prompt.

Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics

@NonNull
public static final BiometricPrompt.AuthenticationResult Class3BiometricAuthExtensionsKt.authenticateWithClass3Biometrics(
    @NonNull Fragment receiver,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull CharSequence title,
    @NonNull CharSequence negativeButtonText,
    @Nullable CharSequence subtitle,
    @Nullable CharSequence description,
    boolean confirmationRequired
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
@Nullable BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull CharSequence title

The title to be displayed on the prompt.

@NonNull CharSequence negativeButtonText

The label for the negative button on the prompt.

@Nullable CharSequence subtitle

An optional subtitle to be displayed on the prompt.

@Nullable CharSequence description

An optional description to be displayed on the prompt.

boolean confirmationRequired

Whether user confirmation should be required for passive biometrics.

Returns
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.