CredentialAuthPrompt.java

/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.biometric.auth;

import android.annotation.SuppressLint;
import android.os.Build;

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RequiresApi;
import androidx.biometric.BiometricManager.Authenticators;
import androidx.biometric.BiometricPrompt;

import java.util.concurrent.Executor;

/**
 * An authentication prompt that requires the user to present the screen lock credential (i.e. PIN,
 * pattern, or password) for the device.
 *
 * @see Authenticators#DEVICE_CREDENTIAL
 * @see Class2BiometricAuthPrompt
 * @see Class2BiometricOrCredentialAuthPrompt
 * @see Class3BiometricAuthPrompt
 * @see Class3BiometricOrCredentialAuthPrompt
 */
@RequiresApi(Build.VERSION_CODES.R)
public class CredentialAuthPrompt {
    @NonNull private final BiometricPrompt.PromptInfo mPromptInfo;

    /**
     * Constructs an authentication prompt with the given parameters.
     *
     * @param promptInfo A set of options describing how the prompt should appear and behave.
     */
    CredentialAuthPrompt(@NonNull BiometricPrompt.PromptInfo promptInfo) {
        mPromptInfo = promptInfo;
    }

    /**
     * Shows an authentication prompt to the user.
     *
     * @param host     A wrapper for the component that will host the prompt.
     * @param crypto   A cryptographic object to be associated with this authentication.
     * @param callback The callback object that will receive and process authentication events. Each
     *                 callback method will be run on the main thread.
     * @return A handle to the shown prompt.
     *
     * @see #startAuthentication(AuthPromptHost, BiometricPrompt.CryptoObject, Executor,
     * AuthPromptCallback)
     */
    @NonNull
    public AuthPrompt startAuthentication(
            @NonNull AuthPromptHost host,
            @Nullable BiometricPrompt.CryptoObject crypto,
            @NonNull AuthPromptCallback callback) {
        return AuthPromptUtils.startAuthentication(
                host, mPromptInfo, crypto, null /* executor */, callback);
    }

    /**
     * Shows an authentication prompt to the user.
     *
     * @param host     A wrapper for the component that will host the prompt.
     * @param crypto   A cryptographic object to be associated with this authentication.
     * @param executor The executor that will be used to run authentication callback methods.
     * @param callback The callback object that will receive and process authentication events.
     * @return A handle to the shown prompt.
     *
     * @see #startAuthentication(AuthPromptHost, BiometricPrompt.CryptoObject, AuthPromptCallback)
     */
    @NonNull
    public AuthPrompt startAuthentication(
            @NonNull AuthPromptHost host,
            @Nullable BiometricPrompt.CryptoObject crypto,
            @NonNull Executor executor,
            @NonNull AuthPromptCallback callback) {
        return AuthPromptUtils.startAuthentication(
                host, mPromptInfo, crypto, executor, callback);
    }

    /**
     * Gets the title to be displayed on the prompt.
     *
     * @return The title for the prompt.
     */
    @NonNull
    public CharSequence getTitle() {
        return mPromptInfo.getTitle();
    }

    /**
     * Gets the description to be displayed on the prompt, if set.
     *
     * @return The description for the prompt.
     *
     * @see Builder#setDescription(CharSequence)
     */
    @Nullable
    public CharSequence getDescription() {
        return mPromptInfo.getDescription();
    }

    /**
     * Builder for a {@link CredentialAuthPrompt} with configurable options.
     */
    public static final class Builder {
        // Required fields.
        @NonNull private final CharSequence mTitle;

        // Optional fields.
        @Nullable private CharSequence mDescription = null;

        /**
         * Constructs a prompt builder with the given required options.
         *
         * @param title The title to be displayed on the prompt.
         */
        @SuppressLint("ExecutorRegistration")
        public Builder(@NonNull CharSequence title) {
            mTitle = title;
        }

        /**
         * Sets a description that should be displayed on the prompt. Defaults to {@code null}.
         *
         * @param description A description for the prompt.
         * @return This builder.
         */
        @NonNull
        public CredentialAuthPrompt.Builder setDescription(@NonNull CharSequence description) {
            mDescription = description;
            return this;
        }

        /**
         * Creates a new prompt with the specified options.
         *
         * @return An instance of {@link CredentialAuthPrompt}.
         */
        @NonNull
        public CredentialAuthPrompt build() {
            final BiometricPrompt.PromptInfo promptInfo = new BiometricPrompt.PromptInfo.Builder()
                    .setTitle(mTitle)
                    .setDescription(mDescription)
                    .setAllowedAuthenticators(Authenticators.DEVICE_CREDENTIAL)
                    .build();
            return new CredentialAuthPrompt(promptInfo);
        }
    }
}