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    repeated SensorServiceStateProto sensor_service_states = 1;
95
96    optional AuthSessionState auth_session_state = 2;
97}
98
99// Overall state for an instance of a <Biometric>Service, for example FingerprintService or
100// FaceService. Note that a single service may provide multiple sensors.
101message SensorServiceStateProto {
102    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
103
104    repeated SensorStateProto sensor_states = 1;
105}
106
107// State of a single sensor.
108message SensorStateProto {
109    enum Modality {
110        UNKNOWN = 0;
111        FINGERPRINT = 1;
112        FACE = 2;
113        IRIS = 3;
114    }
115
116    enum ModalityFlag {
117        FINGERPRINT_UDFPS = 0;
118    }
119
120    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
121
122    // Unique sensorId
123    optional int32 sensor_id = 1;
124
125    // The type of the sensor.
126    optional Modality modality = 2;
127
128    // The current strength (see {@link BiometricManager.Authenticators}) of this sensor, taking any
129    // downgraded strengths into effect. It may be different from the sensor's original strength but
130    // can never be stronger than that.
131    optional int32 current_strength = 3;
132
133    // State of the sensor's scheduler.
134    optional BiometricSchedulerProto scheduler = 4;
135
136    // User states for this sensor.
137    repeated UserStateProto user_states = 5;
138
139    // True if resetLockout requires a HAT to be verified in the TEE or equivalent.
140    optional bool reset_lockout_requires_hardware_auth_token = 6;
141
142    // True if a HAT is required (field above) AND a challenge needs to be generated by the
143    // biometric TEE (or equivalent), and wrapped within the HAT.
144    optional bool reset_lockout_requires_challenge = 7;
145
146    // Detailed information about the sensor's modality, if available.
147    repeated ModalityFlag modality_flags = 8;
148}
149
150// State of a specific user for a specific sensor.
151message UserStateProto {
152    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
153
154    // Android user ID
155    optional int32 user_id = 1;
156
157    // Number of fingerprints enrolled
158    optional int32 num_enrolled = 2;
159}
160
161// BiometricScheduler dump
162message BiometricSchedulerProto {
163    option (.android.msg_privacy).dest = DEST_AUTOMATIC;
164
165    // Operation currently being handled by the BiometricScheduler
166    optional ClientMonitorEnum current_operation = 1;
167
168    // Total number of operations that have been handled, not including the current one if one
169    // exists. Kept in FIFO order (most recent at the end of the array)
170    optional int32 total_operations = 2;
171
172    // A list of recent past operations in the order which they were handled
173    repeated ClientMonitorEnum recent_operations = 3;
174}
175
176// BaseClientMonitor subtypes
177enum ClientMonitorEnum {
178    CM_NONE = 0;
179    CM_UPDATE_ACTIVE_USER = 1;
180    CM_ENROLL = 2;
181    CM_AUTHENTICATE = 3;
182    CM_REMOVE = 4;
183    CM_GET_AUTHENTICATOR_ID = 5;
184    CM_ENUMERATE = 6;
185    CM_INTERNAL_CLEANUP = 7;
186    CM_SET_FEATURE = 8;
187    CM_GET_FEATURE = 9;
188    CM_GENERATE_CHALLENGE = 10;
189    CM_REVOKE_CHALLENGE = 11;
190    CM_RESET_LOCKOUT = 12;
191    CM_DETECT_INTERACTION = 13;
192    CM_INVALIDATION_REQUESTER = 14;
193    CM_INVALIDATE = 15;
194    CM_STOP_USER = 16;
195    CM_START_USER = 17;
196}