1 <html devsite> 2 <head> 3 <title>Fingerprint HAL</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <h2 id=overview>Overview</h2> 27 28 <p>If a device has a fingerprint sensor, a user can enroll one or more 29 fingerprints and then use their fingerprints to unlock the device and perform 30 other tasks.</p> 31 32 <p>Android uses the Fingerprint Hardware Abstraction Layer (HAL) to connect to a 33 vendor-specific library and fingerprint hardware, e.g. a fingerprint sensor.</p> 34 35 <p>To implement the Fingerprint HAL, you must implement 36 <a href="#major_functions_in_the_fingerprint_hal">functions</a> 37 in <code>fingerprint.h</code> (<code>/hardware/libhardware/include/hardware/fingerprint.h</code>) 38 in a vendor-specific library; please see the comments in 39 the <a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/fingerprint.h"><code>fingerprint.h</code></a> file.</p> 40 41 <h3 id=fingerprint_matching_flow>Fingerprint matching flow</h3> 42 43 <p>The following is a high-level flow for fingerprint matching. This flow assumes 44 that a fingerprint already has been enrolled on the device, i.e. the 45 vendor-specific library already has enrolled a template for the fingerprint. 46 Also see <a href="index.html">Authentication</a>.</p> 47 48 <p>The fingerprint sensor of a device generally is idle. But in response to a call 49 to the <code>authenticate</code> or <code>enroll</code> function, the fingerprint 50 sensor listens for a touch (and perhaps the screen 51 wakes up when a user touches the fingerprint sensor).</p> 52 53 <ol> 54 <li>The user places a finger on the fingerprint sensor, and the vendor-specific 55 library determines if there is a match based on the current set of enrolled 56 templates. 57 <li>The result of step 1 is passed to the Fingerprint HAL, which notifies 58 <code>fingerprintd</code> (the Fingerprint daemon) of a fingerprint authentication. 59 </ol> 60 61 <p>Note that as more templates are stored on a single device, the time needed for 62 matching is increased.</p> 63 64 <h2 id=architecture>Architecture</h2> 65 66 <p>The <strong>Fingerprint HAL</strong> interacts with the following components:</p> 67 68 <ul> 69 <li><strong>FingerprintManager API</strong>. Interacts directly with an app in an app process. 70 <ul> 71 <li>Each app has an instance of FingerprintManager. 72 <li>FingerprintManager is a wrapper that communicates with FingerprintService. 73 </ul> 74 <li><strong>FingerprintService</strong>. A singleton service that operates in the system 75 process, which handles 76 communication with <code>fingerprintd</code>. 77 <li><strong>fingerprintd (Fingerprint daemon)</strong>. A C/C++ implementation of the 78 binder interface from FingerprintService. The 79 <code>fingerprintd</code> daemon operates in its own process and wraps the Fingerprint HAL 80 vendor-specific library. 81 <li><strong>Fingerprint HAL vendor-specific library</strong>. A hardware vendor's 82 implementation of the Fingerprint HAL. The 83 vendor-specific library communicates with the device-specific hardware. 84 <li><strong>Keystore API and Keymaster</strong>. These components provide hardware-backed cryptography 85 for secure key storage 86 in a Trusted Execution Environment (TEE). 87 </ul> 88 89 <p>As shown in the following diagram, a vendor-specific HAL implementation needs 90 to use the communication protocol required by a TEE.</p> 91 92 <img src="../images/fingerprint-data-flow.png" alt="Data flow for fingerprint authentication" id="figure1" /> 93 94 <p class="img-caption"><strong>Figure 1.</strong> High-level data flow for fingerprint authentication</p> 95 96 <p>Thus, raw images and processed fingerprint features must not be passed in 97 untrusted memory. All such biometric data needs to be secured within sensor 98 hardware or trusted memory. (Memory inside the TEE is considered as trusted 99 memory; memory outside the TEE is considered untrusted.)</p> 100 101 <p>Rooting must not compromise biometric data.</p> 102 103 <p>As shown in the following diagram, <code>fingerprintd</code> makes calls through the 104 Fingerprint HAL to the vendor-specific library to enroll fingerprints and 105 perform other operations.</p> 106 107 <img src="../images/fingerprint-daemon.png" alt="Interaction with fingerprintd" id="figure2" /> 108 <p class="img-caption"><strong>Figure 2.</strong> Interaction of the 109 fingerprint daemon (<code>fingerprintd</code>) with the fingerprint vendor-specific library</p> 110 111 <h2 id=fingerprint_implementation_guidelines>Fingerprint implementation guidelines</h2> 112 113 <p>The guidelines in this section are intended to ensure the following:</p> 114 115 <ul> 116 <li>Fingerprint data is not leaked 117 <li>Fingerprint data is removed when a user is removed from a device 118 </ul> 119 120 <p>Here are the guidelines:</p> 121 122 <ol> 123 <li>Raw fingerprint data or derivatives (e.g. templates) must never be accessible 124 from outside the sensor driver or Trusted Execution Environment (TEE). Hardware 125 access must be limited to the TEE, if the hardware supports it, and must be protected by 126 an SELinux policy. That is, the Serial Peripheral Interface (SPI) channel must 127 be accessible only to the TEE, and there must be an explicit SELinux policy on 128 all device files. 129 <li>Fingerprint acquisition, enrollment and recognition must occur inside the TEE. 130 <li>Only the encrypted form of the fingerprint data can be stored on the file 131 system, even if the file system itself is encrypted. 132 <li>Fingerprint templates must be signed with a private, device-specific key, for 133 example with AES, with at least the absolute file-system path, group and finger 134 ID such that template files are inoperable on another device or for anyone 135 other than the user that enrolled them on the same device. For example, copying 136 the fingerprint data from a different user on the same device, or from another 137 device, must not work. 138 <li>Implementations must either use the file system path provided by the 139 <code>set_active_group()</code> function or provide a way to erase all user template data when the user 140 is removed. It is strongly recommended that fingerprint template files 141 be stored as encrypted in the path provided. If this is infeasible due to TEE 142 storage requirements, then the implementer must add hooks to ensure removal of 143 the data when the user is removed. 144 </ol> 145 146 <h2 id=major_functions_in_the_fingerprint_hal>Major functions in the Fingerprint HAL</h2> 147 148 <p>Below are the major functions in the <code>/hardware/libhardware/include/hardware/fingerprint.h</code> file; see the detailed descriptions in that 149 file.</p> 150 151 <ul> 152 <li><strong>enroll.</strong> Switches the HAL state machine to start the collection and storage of a 153 fingerprint template. As soon as enrollment is complete, or after a timeout, 154 the HAL state machine is returned to the idle state. 155 <li><strong>pre_enroll.</strong> Generates a unique token to indicate the start of a fingerprint enrollment. 156 Provides a token to the <code>enroll</code> function to ensure there was prior authentication, e.g. using a password. The 157 token is wrapped and, for example, HMAC'd, once the device credential is 158 confirmed, to prevent tampering. The token must be checked during enrollment to 159 verify that the token is still valid. 160 <li><strong>get_authenticator_id.</strong> Returns a token associated with the current fingerprint set. 161 <li><strong>cancel.</strong> Cancels any pending enroll or authenticate operations. The HAL state machine 162 is returned to the idle state. 163 <li><strong>enumerate.</strong> Synchronous call for enumerating all known fingerprint templates. 164 <li><strong>remove.</strong> Deletes a fingerprint template. 165 <li><strong>set_active_group.</strong> Restricts a HAL operation to a set of fingerprints that belong to a specified 166 group (identified by a group identifier, or GID). 167 <li><strong>authenticate.</strong> Authenticates a fingerprint-related operation (identified by an operation ID). 168 <li><strong>set_notify.</strong> Registers a user function that will get notifications from the HAL. If the HAL 169 state machine is in a busy state, the function is blocked until the HAL leaves 170 the busy state. 171 </ul> 172 173 174 </body> 175 </html> 176
