Home | History | Annotate | Download | only in biometrics 
      1 /*
      2  * Copyright (C) 2018 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.hardware.biometrics;
     18 
     19 import android.annotation.CallbackExecutor;
     20 import android.annotation.NonNull;
     21 import android.os.CancellationSignal;
     22 import android.os.Parcelable;
     23 
     24 import java.util.concurrent.Executor;
     25 
     26 /**
     27  * This is the common interface that all biometric authentication classes should implement.
     28  * @hide
     29  */
     30 public interface BiometricAuthenticator {
     31 
     32     /**
     33      * Container for biometric data
     34      * @hide
     35      */
     36     abstract class BiometricIdentifier implements Parcelable {}
     37 
     38     /**
     39      * Container for callback data from {@link BiometricAuthenticator#authenticate(
     40      * CancellationSignal, Executor, AuthenticationCallback)} and
     41      * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
     42      * AuthenticationCallback)}
     43      */
     44     class AuthenticationResult {
     45         private BiometricIdentifier mIdentifier;
     46         private CryptoObject mCryptoObject;
     47         private int mUserId;
     48 
     49         /**
     50          * @hide
     51          */
     52         public AuthenticationResult() { }
     53 
     54         /**
     55          * Authentication result
     56          * @param crypto
     57          * @param identifier
     58          * @param userId
     59          * @hide
     60          */
     61         public AuthenticationResult(CryptoObject crypto, BiometricIdentifier identifier,
     62                 int userId) {
     63             mCryptoObject = crypto;
     64             mIdentifier = identifier;
     65             mUserId = userId;
     66         }
     67 
     68         /**
     69          * Obtain the crypto object associated with this transaction
     70          * @return crypto object provided to {@link BiometricAuthenticator#authenticate(
     71          * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}
     72          */
     73         public CryptoObject getCryptoObject() {
     74             return mCryptoObject;
     75         }
     76 
     77         /**
     78          * Obtain the biometric identifier associated with this operation. Applications are strongly
     79          * discouraged from associating specific identifiers with specific applications or
     80          * operations.
     81          * @hide
     82          */
     83         public BiometricIdentifier getId() {
     84             return mIdentifier;
     85         }
     86 
     87         /**
     88          * Obtain the userId for which this biometric was authenticated.
     89          * @hide
     90          */
     91         public int getUserId() {
     92             return mUserId;
     93         }
     94     };
     95 
     96     /**
     97      * Callback structure provided to {@link BiometricAuthenticator#authenticate(CancellationSignal,
     98      * Executor, AuthenticationCallback)} or {@link BiometricAuthenticator#authenticate(
     99      * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)}. Users must provide
    100      * an implementation of this for listening to biometric events.
    101      */
    102     abstract class AuthenticationCallback {
    103         /**
    104          * Called when an unrecoverable error has been encountered and the operation is complete.
    105          * No further actions will be made on this object.
    106          * @param errorCode An integer identifying the error message
    107          * @param errString A human-readable error string that can be shown on an UI
    108          */
    109         public void onAuthenticationError(int errorCode, CharSequence errString) {}
    110 
    111         /**
    112          * Called when a recoverable error has been encountered during authentication. The help
    113          * string is provided to give the user guidance for what went wrong, such as "Sensor dirty,
    114          * please clean it."
    115          * @param helpCode An integer identifying the error message
    116          * @param helpString A human-readable string that can be shown on an UI
    117          */
    118         public void onAuthenticationHelp(int helpCode, CharSequence helpString) {}
    119 
    120         /**
    121          * Called when a biometric is recognized.
    122          * @param result An object containing authentication-related data
    123          */
    124         public void onAuthenticationSucceeded(AuthenticationResult result) {}
    125 
    126         /**
    127          * Called when a biometric is valid but not recognized.
    128          */
    129         public void onAuthenticationFailed() {}
    130 
    131         /**
    132          * Called when a biometric has been acquired, but hasn't been processed yet.
    133          * @hide
    134          */
    135         public void onAuthenticationAcquired(int acquireInfo) {}
    136     };
    137 
    138     /**
    139      * This call warms up the hardware and starts scanning for valid biometrics. It terminates
    140      * when {@link AuthenticationCallback#onAuthenticationError(int,
    141      * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
    142      * AuthenticationResult)} is called, at which point the crypto object becomes invalid. This
    143      * operation can be canceled by using the provided cancel object. The application wil receive
    144      * authentication errors through {@link AuthenticationCallback}. Calling
    145      * {@link BiometricAuthenticator#authenticate(CryptoObject, CancellationSignal, Executor,
    146      * AuthenticationCallback)} while an existing authentication attempt is occurring will stop
    147      * the previous client and start a new authentication. The interrupted client will receive a
    148      * cancelled notification through {@link AuthenticationCallback#onAuthenticationError(int,
    149      * CharSequence)}.
    150      *
    151      * @throws IllegalArgumentException If any of the arguments are null
    152      *
    153      * @param crypto Object associated with the call
    154      * @param cancel An object that can be used to cancel authentication
    155      * @param executor An executor to handle callback events
    156      * @param callback An object to receive authentication events
    157      */
    158     void authenticate(@NonNull CryptoObject crypto,
    159             @NonNull CancellationSignal cancel,
    160             @NonNull @CallbackExecutor Executor executor,
    161             @NonNull AuthenticationCallback callback);
    162 
    163     /**
    164      * This call warms up the hardware and starts scanning for valid biometrics. It terminates
    165      * when {@link AuthenticationCallback#onAuthenticationError(int,
    166      * CharSequence)} is called or when {@link AuthenticationCallback#onAuthenticationSucceeded(
    167      * AuthenticationResult)} is called. This operation can be canceled by using the provided cancel
    168      * object. The application wil receive authentication errors through
    169      * {@link AuthenticationCallback}. Calling {@link BiometricAuthenticator#authenticate(
    170      * CryptoObject, CancellationSignal, Executor, AuthenticationCallback)} while an existing
    171      * authentication attempt is occurring will stop the previous client and start a new
    172      * authentication. The interrupted client will receive a cancelled notification through
    173      * {@link AuthenticationCallback#onAuthenticationError(int, CharSequence)}.
    174      *
    175      * @throws IllegalArgumentException If any of the arguments are null
    176      *
    177      * @param cancel An object that can be used to cancel authentication
    178      * @param executor An executor to handle callback events
    179      * @param callback An object to receive authentication events
    180      */
    181     void authenticate(@NonNull CancellationSignal cancel,
    182             @NonNull @CallbackExecutor Executor executor,
    183             @NonNull AuthenticationCallback callback);
    184 }
    185