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