biometric/biometric/src/main/java/androidx/biometric/auth/Class3BiometricOrCredentialAuthPrompt.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.os.Handler;
import android.os.Looper;

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.biometric.BiometricManager;
import androidx.biometric.BiometricPrompt;
import androidx.biometric.BiometricViewModel;
import androidx.lifecycle.ViewModelProvider;

import java.lang.ref.WeakReference;
import java.util.concurrent.Executor;

/**
 * This class is used to build and configure a {@link BiometricPrompt} for authentication that
 * permits Class 3 biometric modalities (fingerprint, iris, face, etc), or device credential
 * modalities (device PIN, pattern, or password), and then start authentication.
 *
 * Class 3 (formerly known as Strong) refers to the strength of the biometric sensor, as specified
 * in the Android 11 CDD. Class 3 authentication can be used for applications that use
 * cryptographic operations.
 */
public class Class3BiometricOrCredentialAuthPrompt {

    /**
     * The default executor provided when not provided in the
     * {@link Class3BiometricOrCredentialAuthPrompt} constructor.
     */
    private static class DefaultExecutor implements Executor {
        private final Handler mHandler = new Handler(Looper.getMainLooper());

        @SuppressWarnings("WeakerAccess") /* synthetic access */
        DefaultExecutor() {}

        @Override
        public void execute(Runnable runnable) {
            mHandler.post(runnable);
        }
    }

    @SuppressWarnings("WeakerAccess") /* synthetic access */
    @NonNull BiometricPrompt mBiometricPrompt;
    @NonNull private BiometricPrompt.PromptInfo mPromptInfo;
    private boolean mIsConfirmationRequired;

    @Nullable private BiometricPrompt.CryptoObject mCrypto;
    @Nullable private CharSequence mSubtitle;
    @Nullable private CharSequence mDescription;

    /**
     * Constructs a {@link Class3BiometricOrCredentialAuthPrompt}, which can be used to begin
     * authentication.
     * @param biometricPrompt Manages a system-provided biometric prompt for authentication
     * @param promptInfo A set of configurable options for how the {@link BiometricPrompt}
     *                   should appear and behave.
     * @param crypto A crypto object to be associated with this authentication.
     * @param subtitle The subtitle to be displayed on the prompt.
     * @param description The description to be displayed on the prompt.
     * @param confirmationRequired Whether explicit user confirmation is required after a
     *                             passive biometric
     */
    Class3BiometricOrCredentialAuthPrompt(@NonNull BiometricPrompt biometricPrompt,
            @NonNull BiometricPrompt.PromptInfo promptInfo,
            @Nullable BiometricPrompt.CryptoObject crypto,
            @NonNull CharSequence subtitle,
            @NonNull CharSequence description,
            boolean confirmationRequired) {
        mBiometricPrompt = biometricPrompt;
        mPromptInfo = promptInfo;
        mCrypto = crypto;
        mSubtitle = subtitle;
        mDescription = description;
        mIsConfirmationRequired = confirmationRequired;
    }

    /**
     * Begins authentication using the configured biometric prompt, and returns an
     * {@link AuthPrompt} wrapper that can be used for cancellation and dismissal of the biometric
     * prompt.
     * @return {@link AuthPrompt} wrapper that can be used for cancellation and dismissal of the
     * biometric prompt using {@link AuthPrompt#cancelAuthentication()}
     */
    @NonNull
    public AuthPrompt startAuthentication() {
        if (mCrypto == null) {
            mBiometricPrompt.authenticate(mPromptInfo);
        } else {
            mBiometricPrompt.authenticate(mPromptInfo, mCrypto);
        }

        return new AuthPrompt() {
            @Override
            public void cancelAuthentication() {
                mBiometricPrompt.cancelAuthentication();
            }
        };
    }

    /**
     * Gets the subtitle for the prompt.
     * @return subtitle for the prompt
     */
    @Nullable
    public CharSequence getSubtitle() {
        return mSubtitle;
    }

    /**
     * Gets the description for the prompt. Defaults to null.
     * @return description for the prompt
     */
    @Nullable
    public CharSequence getDescription() {
        return mDescription;
    }

    /**
     * Indicates whether prompt requires explicit user confirmation after a passive biometric (e.g.
     * iris or face) has been recognized but before {@link
     * AuthPromptCallback#onAuthenticationSucceeded(androidx.fragment.app.FragmentActivity,
     * BiometricPrompt.AuthenticationResult)} is called.
     * @return whether prompt requires explicit user confirmation after a passive biometric.
     */
    public boolean isConfirmationRequired() {
        return mIsConfirmationRequired;
    }

    /**
     * Gets the crypto object for the prompt authentication.
     * @return Crypto object associated with this authentication.
     */
    @Nullable
    public BiometricPrompt.CryptoObject getCrypto() {
        return mCrypto;
    }

    /**
     * Builder to configure a {@link BiometricPrompt} object for class 3 biometric or device
     * credential authentication with specified options.
     */
    public static final class Builder {
        // Nullable options on the builder
        @Nullable private BiometricPrompt.CryptoObject mCrypto = null;
        @Nullable private CharSequence mSubtitle = null;
        @Nullable private CharSequence mDescription = null;

        // Non-null options on the builder
        @NonNull private final AuthPromptHost mAuthPromptHost;
        @NonNull private final CharSequence mTitle;
        @NonNull private final Executor mClientExecutor;

        @SuppressWarnings("WeakerAccess") /* synthetic access */
        @NonNull final AuthPromptCallback mClientCallback;

        private boolean mIsConfirmationRequired = true;

        /**
         * A builder used to set individual options for the
         * {@link Class3BiometricOrCredentialAuthPrompt} class to construct a
         * {@link BiometricPrompt} for class 3 biometric or device credential authentication.
         *
         * @param authPromptHost {@link androidx.fragment.app.Fragment} or
         * {@link androidx.fragment.app.FragmentActivity} to host the authentication prompt
         * @param title The title to be displayed on the prompt.
         * @param clientExecutor The executor that will run authentication callback methods.
         * @param clientCallback The object that will receive and process authentication events.
         */
        public Builder(
                @NonNull AuthPromptHost authPromptHost,
                @NonNull CharSequence title,
                @NonNull Executor clientExecutor,
                @NonNull AuthPromptCallback clientCallback) {
            mAuthPromptHost = authPromptHost;
            mTitle = title;
            mClientExecutor = clientExecutor;
            mClientCallback = clientCallback;
        }

        /**
         * A builder used to set individual options for the
         * {@link Class3BiometricOrCredentialAuthPrompt} class to construct a
         * {@link BiometricPrompt} for class 3 biometric or device credential authentication.
         * Sets mClientExecutor to new DefaultExecutor() object.
         *
         * @param authPromptHost {@link androidx.fragment.app.Fragment} or
         * {@link androidx.fragment.app.FragmentActivity} to host the authentication prompt
         * @param title The title to be displayed on the prompt.
         * @param clientCallback The object that will receive and process authentication events.
         */
        public Builder(
                @NonNull AuthPromptHost authPromptHost,
                @NonNull CharSequence title,
                @NonNull AuthPromptCallback clientCallback) {
            mAuthPromptHost = authPromptHost;
            mTitle = title;
            mClientExecutor = new DefaultExecutor();
            mClientCallback = clientCallback;
        }

        /**
         * Optional: Sets the crypto object for the prompt.
         * @param crypto A crypto object to be associated with this authentication.
         */
        @NonNull
        public Builder setCrypto(@NonNull BiometricPrompt.CryptoObject crypto) {
            mCrypto = crypto;
            return this;
        }

        /**
         * Optional: Sets the subtitle for the prompt.
         *
         * @param subtitle The subtitle to be displayed on the prompt.
         * @return This builder.
         */
        @NonNull
        public Builder setSubtitle(
                @NonNull CharSequence subtitle) {
            mSubtitle = subtitle;
            return this;
        }

        /**
         * Optional: Sets the description for the prompt.
         *
         * @param description The description to be displayed on the prompt.
         * @return This builder.
         */
        @NonNull
        public Builder setDescription(
                @NonNull CharSequence description) {
            mDescription = description;
            return this;
        }

        /**
         * Optional: Sets a system hint for whether to require explicit user confirmation after
         * a passive biometric (e.g. iris or face) has been recognized but before
         * {@link AuthPromptCallback#onAuthenticationSucceeded(
         * androidx.fragment.app.FragmentActivity, BiometricPrompt.AuthenticationResult)} is
         * called. Defaults to {@code true}.
         *
         * <p>Disabling this option is generally only appropriate for frequent, low-value
         * transactions, such as re-authenticating for a previously authorized application.
         *
         * <p>Also note that, as it is merely a hint, this option may be ignored by the system.
         * For example, the system may choose to instead always require confirmation if the user
         * has disabled passive authentication for their device in Settings. Additionally, this
         * option will be ignored on devices running OS versions prior to Android 10 (API 29).
         *
         * @param confirmationRequired Whether this option should be enabled.
         * @return This builder.
         */
        @NonNull
        public Builder setConfirmationRequired(
                boolean confirmationRequired) {
            mIsConfirmationRequired = confirmationRequired;
            return this;
        }

        /**
         * Configures a {@link BiometricPrompt} object with the specified options, and returns a
         * {@link Class3BiometricOrCredentialAuthPrompt} instance that can be used for starting
         * authentication.
         * @return {@link Class3BiometricOrCredentialAuthPrompt} instance for starting
         * authentication.
         */
        @NonNull
        public Class3BiometricOrCredentialAuthPrompt build() {
            final BiometricPrompt.PromptInfo promptInfo = new BiometricPrompt.PromptInfo
                    .Builder()
                    .setTitle(mTitle)
                    .setSubtitle(mSubtitle)
                    .setDescription(mDescription)
                    .setConfirmationRequired(mIsConfirmationRequired)
                    .setAllowedAuthenticators(BiometricManager.Authenticators.BIOMETRIC_STRONG
                            | BiometricManager.Authenticators.DEVICE_CREDENTIAL)
                    .build();

            final BiometricPrompt biometricPrompt;
            final BiometricPrompt.AuthenticationCallback wrappedCallback;

            if (mAuthPromptHost.getActivity() != null) {
                wrappedCallback = new WrappedAuthPromptCallback(mClientCallback,
                        new ViewModelProvider(mAuthPromptHost.getActivity())
                                .get(BiometricViewModel.class));
                biometricPrompt = new BiometricPrompt(mAuthPromptHost.getActivity(),
                        mClientExecutor, wrappedCallback);
            } else if (mAuthPromptHost.getFragment() != null) {
                wrappedCallback = new WrappedAuthPromptCallback(mClientCallback,
                        new ViewModelProvider(mAuthPromptHost.getFragment().getActivity())
                                .get(BiometricViewModel.class));
                biometricPrompt = new BiometricPrompt(mAuthPromptHost.getFragment(),
                        mClientExecutor, wrappedCallback);
            } else {
                throw new IllegalArgumentException("Invalid AuthPromptHost provided. Must "
                        + "provide AuthPromptHost containing Fragment or FragmentActivity for"
                        + " hosting the BiometricPrompt.");
            }
            return new Class3BiometricOrCredentialAuthPrompt(biometricPrompt, promptInfo, mCrypto,
                    mSubtitle, mDescription, mIsConfirmationRequired);
        }

        /**
         * Wraps AuthPromptCallback in BiometricPrompt.AuthenticationCallback for BiometricPrompt
         * construction
         */
        private static class WrappedAuthPromptCallback
                extends BiometricPrompt.AuthenticationCallback {
            @NonNull private final AuthPromptCallback mClientCallback;
            @NonNull private final WeakReference<BiometricViewModel> mViewModelRef;

            WrappedAuthPromptCallback(@NonNull AuthPromptCallback callback,
                    @NonNull BiometricViewModel viewModel) {
                mClientCallback = callback;
                mViewModelRef = new WeakReference<>(viewModel);
            }

            @Override
            public void onAuthenticationError(int errorCode,
                    @NonNull CharSequence errString) {
                if (mViewModelRef != null) {
                    mClientCallback.onAuthenticationError(
                            mViewModelRef.get().getClientActivity(),
                            errorCode,
                            errString
                    );
                }
            }

            @Override
            public void onAuthenticationSucceeded(
                    @NonNull BiometricPrompt.AuthenticationResult result) {
                if (mViewModelRef != null) {
                    mClientCallback.onAuthenticationSucceeded(
                            mViewModelRef.get().getClientActivity(),
                            result
                    );
                }
            }

            @Override
            public void onAuthenticationFailed() {
                if (mViewModelRef != null) {
                    mClientCallback.onAuthenticationFailed(
                            mViewModelRef.get().getClientActivity()
                    );
                }
            }
        }
    }
}