diff options
author | Bert McMeen <amcmeen@google.com> | 2015-09-28 22:47:43 +0000 |
---|---|---|
committer | Android (Google) Code Review <android-gerrit@google.com> | 2015-09-28 22:47:43 +0000 |
commit | fe4ca3806c1af6ed6b002e394f7163aaeeb7a63e (patch) | |
tree | 2397c9933d4cbffc55bf861d108a3556841f9294 | |
parent | 6805320193160606df8af3f1150f46c869a6b6fe (diff) | |
parent | f611377d74968a6328c71b49d83e8d042b602893 (diff) | |
download | source.android.com-fe4ca3806c1af6ed6b002e394f7163aaeeb7a63e.tar.gz |
Merge "Docs: Add Fingerprint HAL page and navigation" into mnc-dev
-rw-r--r-- | src/devices/devices_toc.cs | 25 | ||||
-rw-r--r-- | src/devices/tech/security/authentication/fingerprint-hal.jd | 174 | ||||
-rw-r--r-- | src/devices/tech/security/images/fingerprint-daemon.png | bin | 0 -> 44232 bytes | |||
-rw-r--r-- | src/devices/tech/security/images/fingerprint-data-flow.png | bin | 0 -> 58372 bytes |
4 files changed, 197 insertions, 2 deletions
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs index 5744717f..9184b0ba 100644 --- a/src/devices/devices_toc.cs +++ b/src/devices/devices_toc.cs @@ -310,8 +310,29 @@ </a> </div> <ul> - <li><a href="<?cs var:toroot ?>devices/tech/security/authentication/index.html">Authentication</a></li> - <li><a href="<?cs var:toroot ?>devices/tech/security/encryption/index.html">Full Disk Encryption</a></li> + <li class="nav-section"> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>devices/tech/security/authentication/index.html"> + <span class="en">Authentication</span> + </a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>devices/tech/security/authentication/fingerprint-hal.html">Fingerprint HAL</a></li> + <li><a href="<?cs var:toroot ?>devices/tech/security/authentication/gatekeeper.html">Gatekeeper</a></li> + <li class="nav-section"> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>devices/tech/security/authentication/keymaster.html"> + <span class="en">Keymaster</span> + </a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>devices/tech/security/authentication/km-features.html">Features</a></li> + <li><a href="<?cs var:toroot ?>devices/tech/security/authentication/km-implementer.html">Implementer's Reference</a></li> + </ul> + </li> + </ul> + </li> + <li><a href="<?cs var:toroot ?>devices/tech/security/encryption/index.html">Full Disk Encryption</a></li> <li class="nav-section"> <div class="nav-section-header"> <a href="<?cs var:toroot ?>devices/tech/security/selinux/index.html"> diff --git a/src/devices/tech/security/authentication/fingerprint-hal.jd b/src/devices/tech/security/authentication/fingerprint-hal.jd new file mode 100644 index 00000000..e5af5e4f --- /dev/null +++ b/src/devices/tech/security/authentication/fingerprint-hal.jd @@ -0,0 +1,174 @@ +page.title=Fingerprint HAL +@jd:body + +<!-- + Copyright 2015 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol id="auto-toc"> + </ol> + </div> +</div> + +<h2 id=overview>Overview</h2> + +<p>If a device has a fingerprint sensor, a user can enroll one or more +fingerprints and then use their fingerprints to unlock the device and perform +other tasks.</p> + +<p>Android uses the Fingerprint Hardware Abstraction Layer (HAL) to connect to a +vendor-specific library and fingerprint hardware, e.g. a fingerprint sensor.</p> + +<p>To implement the Fingerprint HAL, you must implement +<a href="#major_functions_in_the_fingerprint_hal">functions</a> +in <code>fingerprint.h</code> (<code>/hardware/libhardware/include/hardware/fingerprint.h</code>) +in a vendor-specific library; please see the comments in +the <a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/fingerprint.h"><code>fingerprint.h</code></a> file.</p> + +<h3 id=fingerprint_matching_flow>Fingerprint matching flow</h3> + +<p>The following is a high-level flow for fingerprint matching. This flow assumes +that a fingerprint already has been enrolled on the device, i.e. the +vendor-specific library already has enrolled a template for the fingerprint. +Also see <a href="index.html">Authentication</a>.</p> + +<p>The fingerprint sensor of a device generally is idle. But in response to a call +to the <code>authenticate</code> or <code>enroll</code> function, the fingerprint +sensor listens for a touch (and perhaps the screen +wakes up when a user touches the fingerprint sensor).</p> + +<ol> + <li>The user places a finger on the fingerprint sensor, and the vendor-specific +library determines if there is a match based on the current set of enrolled +templates. + <li>The result of step 1 is passed to the Fingerprint HAL, which notifies +<code>fingerprintd</code> (the Fingerprint daemon) of a fingerprint authentication. +</ol> + +<p>Note that as more templates are stored on a single device, the time needed for +matching is increased.</p> + +<h2 id=architecture>Architecture</h2> + +<p>The <strong>Fingerprint HAL</strong> interacts with the following components:</p> + +<ul> + <li><strong>FingerprintManager API</strong>. Interacts directly with an app in an app process. + <ul> + <li>Each app has an instance of FingerprintManager. + <li>FingerprintManager is a wrapper that communicates with FingerprintService. + </ul> + <li><strong>FingerprintService</strong>. A singleton service that operates in the system + process, which handles +communication with <code>fingerprintd</code>. + <li><strong>fingerprintd (Fingerprint daemon)</strong>. A C/C++ implementation of the + binder interface from FingerprintService. The +<code>fingerprintd</code> daemon operates in its own process and wraps the Fingerprint HAL +vendor-specific library. + <li><strong>Fingerprint HAL vendor-specific library</strong>. A hardware vendor's + implementation of the Fingerprint HAL. The +vendor-specific library communicates with the device-specific hardware. + <li><strong>Keystore API and Keymaster</strong>. These components provide hardware-backed cryptography + for secure key storage + in a Trusted Execution Environment (TEE). +</ul> + +<p>As shown in the following diagram, a vendor-specific HAL implementation needs +to use the communication protocol required by a TEE.</p> + +<img src="../images/fingerprint-data-flow.png" alt="Data flow for fingerprint authentication" id="figure1" /> + +<p class="img-caption"><strong>Figure 1.</strong> High-level data flow for fingerprint authentication</p> + +<p>Thus, raw images and processed fingerprint features must not be passed in +untrusted memory. All such biometric data needs to be secured within sensor +hardware or trusted memory. (Memory inside the TEE is considered as trusted +memory; memory outside the TEE is considered untrusted.)</p> + +<p>Rooting must not compromise biometric data.</p> + +<p>As shown in the following diagram, <code>fingerprintd</code> makes calls through the +Fingerprint HAL to the vendor-specific library to enroll fingerprints and +perform other operations.</p> + +<img src="../images/fingerprint-daemon.png" alt="Interaction with fingerprintd" id="figure2" /> +<p class="img-caption"><strong>Figure 2.</strong> Interaction of the +fingerprint daemon (<code>fingerprintd</code>) with the fingerprint vendor-specific library</p> + +<h2 id=fingerprint_implementation_guidelines>Fingerprint implementation guidelines</h2> + +<p>The guidelines in this section are intended to ensure the following:</p> + +<ul> + <li>Fingerprint data is not leaked + <li>Fingerprint data is removed when a user account is removed from a device +</ul> + +<p>Here are the guidelines:</p> + +<ol> + <li>Raw fingerprint data or derivatives (e.g. templates) must never be accessible +from outside the sensor driver or Trusted Execution Environment (TEE). Hardware +access must be limited to the TEE, if the hardware supports it, and must be protected by +an SELinux policy. That is, the Serial Peripheral Interface (SPI) channel must +be accessible only to the TEE, and there must be an explicit SELinux policy on +all device files. + <li>Fingerprint acquisition, enrollment and recognition must occur inside the TEE. + <li>Only the encrypted form of the fingerprint data can be stored on the file +system, even if the file system itself is encrypted. + <li>Fingerprint templates must be signed with a private, device-specific key, for +example with AES, with at least the absolute file-system path, group and finger +ID such that template files are inoperable on another device or for anyone +other than the user that enrolled them on the same device. For example, copying +the fingerprint data from a different user on the same device, or from another +device, must not work. + <li>Implementations must either use the file system path provided by the + <code>set_active_group()</code> function or provide a way to erase all user template data when the user +account is removed. It is strongly recommended that fingerprint template files +be stored as encrypted in the path provided. If this is infeasible due to TEE +storage requirements, then the implementer must add hooks to ensure removal of +the data when the user's account is removed. +</ol> + +<h2 id=major_functions_in_the_fingerprint_hal>Major functions in the Fingerprint HAL</h2> + +<p>Below are the major functions in the <code>/hardware/libhardware/include/hardware/fingerprint.h</code> file; see the detailed descriptions in that +file.</p> + +<ul> + <li><strong>enroll.</strong> Switches the HAL state machine to start the collection and storage of a +fingerprint template. As soon as enrollment is complete, or after a timeout, +the HAL state machine is returned to the idle state. + <li><strong>pre_enroll.</strong> Generates a unique token to indicate the start of a fingerprint enrollment. +Provides a token to the <code>enroll</code> function to ensure there was prior authentication, e.g. using a password. The +token is wrapped and, for example, HMAC'd, once the device credential is +confirmed, to prevent tampering. The token must be checked during enrollment to +verify that the token is still valid. + <li><strong>get_authenticator_id.</strong> Returns a token associated with the current fingerprint set. + <li><strong>cancel.</strong> Cancels any pending enroll or authenticate operations. The HAL state machine +is returned to the idle state. + <li><strong>enumerate.</strong> Synchronous call for enumerating all known fingerprint templates. + <li><strong>remove.</strong> Deletes a fingerprint template. + <li><strong>set_active_group.</strong> Restricts a HAL operation to a set of fingerprints that belong to a specified +group (identified by a group identifier, or GID). + <li><strong>authenticate.</strong> Authenticates a fingerprint-related operation (identified by an operation ID). + <li><strong>set_notify.</strong> Registers a user function that will get notifications from the HAL. If the HAL +state machine is in a busy state, the function is blocked until the HAL leaves +the busy state. +</ul> + diff --git a/src/devices/tech/security/images/fingerprint-daemon.png b/src/devices/tech/security/images/fingerprint-daemon.png Binary files differnew file mode 100644 index 00000000..a57a7a4d --- /dev/null +++ b/src/devices/tech/security/images/fingerprint-daemon.png diff --git a/src/devices/tech/security/images/fingerprint-data-flow.png b/src/devices/tech/security/images/fingerprint-data-flow.png Binary files differnew file mode 100644 index 00000000..bc3ff36b --- /dev/null +++ b/src/devices/tech/security/images/fingerprint-data-flow.png |