1# Face Virtual HAL (VHAL)
2
3This is a virtual HAL implementation that is backed by system properties instead
4of actual hardware. It's intended for testing and UI development on debuggable
5builds to allow devices to masquerade as alternative device types and for
6emulators. Note: The virtual face HAL feature development will be done in
7phases. Refer to this doc often for the latest supported features
8
9## Supported Devices
10
11The face virtual hal is automatically built in in all debug builds (userdebug<br/>
12and eng) for the latest pixel devices and CF. The instructions in this doc<br/>
13applies to all
14
15## Enabling Face Virtual HAL
16
17On pixel devicse (non-CF), by default (after manufacture reset), Face VHAL is <br/>
18not enabled. Therefore real Face HAL is used. Face VHAL enabling is gated by the<br/>
19following two AND conditions:<br/>
201. The Face VHAL feature flag (as part ofTrunk-development strategy) must be<br/>
21   turned on until the flags life-cycle ends.
222. The Face VHAL must be enabled via sysprop.
23
24See the adb commands below
25
26## Getting Stared
27
28A basic use case for a successful authentication via Face VHAL is given as an
29exmple below.
30
31### Enabling VHAL
32
33```shell
34$ adb root
35$ adb shell device_config put biometrics_framework com.android.server.biometrics.face_vhal_feature true
36$ adb shell settings put secure biometric_virtual_enabled 1
37$ adb shell setprop persist.vendor.face.virtual.strength strong
38$ adb shell setprop persist.vendor.face.virtual.type RGB
39$ adb reboot
40```
41
42### Direct Enrollment
43
44```shell
45$ adb shell locksettings set-pin 0000
46$ adb shell setprop persist.vendor.face.virtual.enrollments 1
47$ adb shell cmd face syncadb shell cmd face sync
48```
49
50## Authenticating
51
52To authenticate successfully, the captured (hit) must match the enrollment id<br/>
53set above. To trigger authentication failure, set the hit id to a different value.
54`shell
55$ adb shell setprop vendor.face.virtual.operation_authenticate_duration 800
56$ adb shell setprop vendor.face.virtual.enrollment_hit 1`
57
58### AcquiredInfo
59
60AcquiredInfo codes can be sent during authentication by specifying the sysprop.<br/>
61The codes is sent in sequence and in the interval of operation_authentication_duration/numberOfAcquiredInfoCode
62`shell
63$ adb shell setprop vendor.face.virtual.operation_authenticate_acquired 6,9,1013`
64Refer to [AcquiredInfo.aidl](https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:hardware/interfaces/biometrics/face/aidl/android/hardware/biometrics/face/AcquiredInfo.aidl) for full face acquiredInfo codes.
65Note: For vendor specific acquired info, acquiredInfo = 1000 + vendorCode.
66
67### Error Insertion
68
69Error can be inserted during authentction by specifying the authenticate_error
70sysprop. `shell $ adb shell setprop
71vendor.face.virtual.operation_authenticate_error 4` Refer to
72[Error.aidl](https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:hardware/interfaces/biometrics/face/aidl/android/hardware/biometrics/face/Error.aidl)
73for full face error codes
74
75## Enrollment via Settings
76
77Enrollment process is specified by sysprop `next_enrollment` in the following
78format
79
80```shell
81Format: <id>:<progress_ms-[acquiredInfo,...],...:<success>
82        ----:-----------------------------------:---------
83        |           |                               |--->sucess (true/false)
84        |           |--> progress_step(s)
85        |
86        |-->enrollment_id
87
88E.g.
89$ adb shell setprop vendor.face.virtual.next_enrollment 1:6000-[21,8,1,1108,1,10,1113,1,1118,1124]:true
90```
91
92If next_enrollment prop is not set, the following default value is used:<br/>
93&nbsp;&nbsp;defaultNextEnrollment="1:1000-[21,7,1,1103],1500-[1108,1],2000-[1113,1],2500-[1118,1]:true"<br/>
94Note: Enrollment data and configuration can be supported upon request in case of needs
95
96## Lockout
97
98Device lockout is based on the number of consecutive failed authentication attempts. There are a few
99flavors of lockout mechanisms that are supported by virtula HAL <br/>
100
101### Permanent Lockout
102
103There are two sysprop to control permanent lockout <br/>
1041. general lockout feature enable <br/>
1052. threshold of failed attempts <br/>
106`shell
107$ adb shell setprop persist.vendor.face.virtual.lockout_enable true
108$ adb shell setprop persist.vendor.face.virtual.lockout_permanent_threshold 3`
109
110### Temporary Lockout
111
112There are a few parameters to control temporary lockout (aka timed lockout): <br/>
1131. enable lockout (general lockout feature enable, and timed lcokout enable) <br/>
1142. threshold of failed attempts <br/>
1153. timeout in ms <br/>
116`shell
117$ adb shell setprop persist.vendor.face.virtual.lockout_enable true
118$ adb shell setprop persist.vendor.face.virtual.lockout_timed_enable true
119$ adb shell setprop persist.vendor.face.virtual.lockout_timed_threshold 5
120$ adb shell setprop persist.vendor.face.virtual.lockout_timed_duration 10000`
121
122### Forced Lockout
123
124A permanent lockout can be inserted on next authentication attempt independent of the failed <br/>
125attempt count. This is a feature purely for test purpose.
126`shell
127$ adb shell setprop persist.vendor.face.virtual.lockout true`
128