1/*
2 * Copyright (C) 2020 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
17syntax = "proto2";
18package com.android.server.biometrics;
19
20import "frameworks/base/core/proto/android/privacy.proto";
21
22option java_multiple_files = true;
23option java_outer_classname = "BiometricsProto";
24
25// Overall state of BiometricService (and not <Biometric>Service), including any
26// <Biomteric>Service(s), for example FingerprintService or FaceService.
27message BiometricServiceStateProto {
28    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
29
30    enum AuthSessionState {
31        /**
32         * Authentication either just called and we have not transitioned to the CALLED state, or
33         * authentication terminated (success or error).
34         */
35        STATE_AUTH_IDLE = 0;
36
37        /**
38         * Authentication was called and we are waiting for the <Biometric>Services to return their
39         * cookies before starting the hardware and showing the BiometricPrompt.
40         */
41        STATE_AUTH_CALLED = 1;
42
43        /**
44         * Authentication started, BiometricPrompt is showing and the hardware is authenticating.
45         */
46        STATE_AUTH_STARTED = 2;
47
48        /**
49         * Same as {@link #STATE_AUTH_STARTED}, except the BiometricPrompt UI is done animating in.
50         */
51        STATE_AUTH_STARTED_UI_SHOWING = 3;
52
53        /**
54         * Authentication is paused, waiting for the user to press "try again" button. Only
55         * passive modalities such as Face or Iris should have this state. Note that for passive
56         * modalities, the HAL enters the idle state after onAuthenticated(false) which differs from
57         * fingerprint.
58         */
59        STATE_AUTH_PAUSED = 4;
60
61        /**
62         * Paused, but "try again" was pressed. Sensors have new cookies and we're now waiting for
63         * all cookies to be returned.
64         */
65        STATE_AUTH_PAUSED_RESUMING = 5;
66
67        /**
68         * Authentication is successful, but we're waiting for the user to press "confirm" button.
69         */
70        STATE_AUTH_PENDING_CONFIRM = 6;
71
72        /**
73         * Biometric authenticated, waiting for SysUI to finish animation
74         */
75        STATE_AUTHENTICATED_PENDING_SYSUI = 7;
76
77        /**
78         * Biometric error, waiting for SysUI to finish animation
79         */
80        STATE_ERROR_PENDING_SYSUI = 8;
81
82        /**
83         * Device credential in AuthController is showing
84         */
85        STATE_SHOWING_DEVICE_CREDENTIAL = 9;
86
87        /**
88         * The client binder died, and sensors were authenticating at the time. Cancel has been
89         * requested and we're waiting for the HAL(s) to send ERROR_CANCELED.
90         */
91        STATE_CLIENT_DIED_CANCELLING = 10;
92    }
93
94    enum MultiSensorState {
95        // Initializing or not yet started.
96        MULTI_SENSOR_STATE_UNKNOWN = 0;
97        // Sensors are in the process of being transitioned and there is no active sensor.
98        MULTI_SENSOR_STATE_SWITCHING = 1;
99        // Face sensor is being used as the primary input.
100        MULTI_SENSOR_STATE_FACE_SCANNING = 2;
101        // Fingerprint sensor is being used as the primary input.
102        MULTI_SENSOR_STATE_FP_SCANNING = 3;
103    }
104
105    repeated SensorServiceStateProto sensor_service_states = 1;
106
107    optional AuthSessionState auth_session_state = 2;
108
109    // Additional session state information, when the device has multiple sensors.
110    optional MultiSensorState auth_session_multi_sensor_state = 3;
111}
112
113// Overall state for an instance of a <Biometric>Service, for example FingerprintService or
114// FaceService. Note that a single service may provide multiple sensors.
115message SensorServiceStateProto {
116    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
117
118    repeated SensorStateProto sensor_states = 1;
119}
120
121// State of a single sensor.
122message SensorStateProto {
123    enum Modality {
124        UNKNOWN = 0;
125        FINGERPRINT = 1;
126        FACE = 2;
127        IRIS = 3;
128    }
129
130    enum ModalityFlag {
131        FINGERPRINT_UDFPS = 0;
132    }
133
134    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
135
136    // Unique sensorId
137    optional int32 sensor_id = 1;
138
139    // The type of the sensor.
140    optional Modality modality = 2;
141
142    // The current strength (see {@link BiometricManager.Authenticators}) of this sensor, taking any
143    // downgraded strengths into effect. It may be different from the sensor's original strength but
144    // can never be stronger than that.
145    optional int32 current_strength = 3;
146
147    // State of the sensor's scheduler.
148    optional BiometricSchedulerProto scheduler = 4;
149
150    // User states for this sensor.
151    repeated UserStateProto user_states = 5;
152
153    // True if resetLockout requires a HAT to be verified in the TEE or equivalent.
154    optional bool reset_lockout_requires_hardware_auth_token = 6;
155
156    // True if a HAT is required (field above) AND a challenge needs to be generated by the
157    // biometric TEE (or equivalent), and wrapped within the HAT.
158    optional bool reset_lockout_requires_challenge = 7;
159
160    // Detailed information about the sensor's modality, if available.
161    repeated ModalityFlag modality_flags = 8;
162}
163
164// State of a specific user for a specific sensor.
165message UserStateProto {
166    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
167
168    // Android user ID
169    optional int32 user_id = 1;
170
171    // Number of fingerprints enrolled
172    optional int32 num_enrolled = 2;
173}
174
175// BiometricScheduler dump
176message BiometricSchedulerProto {
177    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
178
179    // Operation currently being handled by the BiometricScheduler
180    optional ClientMonitorEnum current_operation = 1;
181
182    // Total number of operations that have been handled, not including the current one if one
183    // exists. Kept in FIFO order (most recent at the end of the array)
184    optional int32 total_operations = 2;
185
186    // A list of recent past operations in the order which they were handled
187    repeated ClientMonitorEnum recent_operations = 3;
188}
189
190// BaseClientMonitor subtypes
191enum ClientMonitorEnum {
192    CM_NONE = 0;
193    CM_UPDATE_ACTIVE_USER = 1;
194    CM_ENROLL = 2;
195    CM_AUTHENTICATE = 3;
196    CM_REMOVE = 4;
197    CM_GET_AUTHENTICATOR_ID = 5;
198    CM_ENUMERATE = 6;
199    CM_INTERNAL_CLEANUP = 7;
200    CM_SET_FEATURE = 8;
201    CM_GET_FEATURE = 9;
202    CM_GENERATE_CHALLENGE = 10;
203    CM_REVOKE_CHALLENGE = 11;
204    CM_RESET_LOCKOUT = 12;
205    CM_DETECT_INTERACTION = 13;
206    CM_INVALIDATION_REQUESTER = 14;
207    CM_INVALIDATE = 15;
208    CM_STOP_USER = 16;
209    CM_START_USER = 17;
210}