Merge "CDD: Add strongly encouraged to pro audio feature" into mnc-dev
diff --git a/src/accessories/accessories_toc.cs b/src/accessories/accessories_toc.cs
index 654ff7b..616cc5e 100644
--- a/src/accessories/accessories_toc.cs
+++ b/src/accessories/accessories_toc.cs
@@ -1,5 +1,5 @@
<!--
- Copyright 2014 The Android Open Source Project
+ 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.
@@ -30,9 +30,20 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>accessories/headset-spec.html">Headset specification</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>accessories/headset/index.html">
+ <span class="en">Headset</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>accessories/headset/specification.html">Specification</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/headset/requirements.html">Requirements</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/headset/testing.html">Testing</a></li>
</ul>
- </li>
+ </li>
+ </ul>
+ </li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>accessories/custom.html">
@@ -45,8 +56,8 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>accessories/aoa2.html">Version 2.0</a></li>
- <li><a href="<?cs var:toroot ?>accessories/aoa.html">Version 1.0</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/aoa2.html">AOA 2.0</a></li>
+ <li><a href="<?cs var:toroot ?>accessories/aoa.html">AOA 1.0</a></li>
</ul>
</li>
</ul>
diff --git a/src/accessories/aoa.jd b/src/accessories/aoa.jd
index 7388d54..7c728fe 100644
--- a/src/accessories/aoa.jd
+++ b/src/accessories/aoa.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ 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.
@@ -16,55 +16,81 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>An Android USB accessory must adhere to Android Accessory Protocol, which defines how
-an accessory detects and sets up communication with an Android-powered device. In general, an
-accessory should carry out the following steps:</p>
+<p>Android USB accessories must adhere to the Android Open Accessory (AOA)
+protocol, which defines how an accessory detects and sets up communication with
+an Android-powered device. Accessories should carry out the following steps:</p>
+
<ul>
-<li>Wait for and detect connected devices</li>
-<li>Determine the device's accessory mode support</li>
-<li>Attempt to start the device in accessory mode if needed</li>
-<li>Establish communication with the device if it supports the Android accessory protocol</li>
+<li>Wait for and detect a connected device.</li>
+<li>Determine the device's accessory mode support.</li>
+<li>Attempt to start the device in accessory mode (if needed).</li>
+<li>If the device supports AOA, establish communication with the device.</li>
</ul>
+
<p>The following sections explain how to implement these steps.</p>
-<h2 id="wait-for-and-detect-connected-devices">Wait for and Detect Connected Devices</h2>
-<p>Your accessory should have logic to continuously check for connected Android-powered devices.
-When a device is connected, your accessory should determine if the device supports accessory mode.</p>
-<h2 id="determine-accessory-mode-support">Determine Accessory Mode Support</h2>
-<p>When an Android-powered device is connected, it can be in one of three states:</p>
+
+<p class="note">When developing a new accessory that connects to an Android
+device over USB, use <a href="{@docRoot}accessories/aoa2.html">AOAv2</a>.</p>
+
+<h2 id="wait-for-and-detect-connected-devices">Wait for and detect connected
+devices</h2>
+
+<p>Accessories should continuously check for connected Android-powered devices.
+When a device is connected, the accessory should determine if the device
+supports accessory mode.</p>
+
+<h2 id="determine-accessory-mode-support">Determine accessory mode support</h2>
+
+<p>When an Android-powered device connects, it can be in one of three states:
+</p>
+
<ul>
-<li>The attached device supports Android accessory mode and is already in accessory mode.</li>
-<li>The attached device supports Android accessory mode, but it is not in accessory mode.</li>
-<li>The attached device does not support Android accessory mode.</li>
+<li>Supports Android accessory mode and is already in accessory mode.</li>
+<li>Supports Android accessory mode but it is not in accessory mode.</li>
+<li>Does not support Android accessory mode.</li>
</ul>
-<p>During the initial connection, the accessory should check the vendor and product IDs of the
-connected device's USB device descriptor. The vendor ID should match Google's ID (<code>0x18D1</code>) and the
-product ID should be <code>0x2D00</code> or <code>0x2D01</code> if the device is already in accessory mode (case A). If
-so, the accessory can now
-<a href="#establish-communication-with-the-device">establish communication with the device</a> through
-bulk transfer endpoints with its own communication protocol. There is no need to start the device
-in accessory mode.</p>
-<p><strong>Note:</strong> <code>0x2D00</code> is reserved for Android-powered devices that
-support accessory mode. <code>0x2D01</code> is reserved for devices that support accessory mode as well as the
-ADB (Android Debug Bridge) protocol, which exposes a second interface with two bulk endpoints for
-ADB. You can use these endpoints for debugging the accessory application if you are simulating
-the accessory on a computer. In general, do not use this interface unless your accessory is
-implementing a passthrough to ADB on the device.</p>
-<p>If the vendor and product ID do not match, there is no way to distinguish between states b and c, so
-the accessory <a href="#attempt-to-start-in-accessory-mode">attempts to start the device in accessory mode</a>
-to determine if the device is supported.</p>
-<h2 id="attempt-to-start-in-accessory-mode">Attempt to Start in Accessory Mode</h2>
-<p>If the vendor and product IDs do not correspond to an Android-powered device in accessory
-mode, the accessory cannot discern whether the device supports accessory mode and is not in that
-state, or if the device does not support accessory mode at all. This is because devices that
-support accessory mode but aren't in it initially report the device's manufacturer vendor ID and
-product ID, and not the special Android Open Accessory ones. In either case, the accessory should
-try to start the device into accessory mode to figure out if the device supports it. The following
-steps explain how to do this:</p>
+
+<p>During the initial connection, the accessory should check the vendor ID and
+product ID of the connected device's USB device descriptor. The vendor ID
+should match Google's ID (<code>0x18D1</code>). If the device is already in
+accessory mode, the product ID should be <code>0x2D00</code> or
+<code>0x2D01</code> and the accessory can
+<a href="#establish-communication-with-the-device">establish communication with
+the device</a> through bulk transfer endpoints using its own communication
+protocol (the device does not need to be started in accessory mode).</p>
+
+<p class="note"><strong>Note:</strong> <code>0x2D00</code> is reserved for
+Android-powered devices that support accessory mode. <code>0x2D01</code> is
+reserved for devices that support accessory mode as well as the Android Debug
+Bridge (ADB) protocol, which exposes a second interface with two bulk endpoints
+for ADB. You can use these endpoints for debugging the accessory application if
+you are simulating the accessory on a computer. In general, do not use this
+interface unless the accessory implements a passthrough to ADB on the device.
+</p>
+
+<p>If the vendor ID or the product ID found in USB device descriptor do not
+match expected values, the accessory cannot determine if the device supports
+Android accessory mode. The accessory should attempt to start the device in
+accessory mode (detailed below) to determine device support.</p>
+
+<h2 id="attempt-to-start-in-accessory-mode">Attempt to start in accessory
+mode</h2>
+
+<p>If the vendor and product IDs do not correspond to an Android-powered device
+in accessory mode, the accessory cannot discern whether the device supports (but
+is not in) accessory mode or if the device does not support accessory mode. This
+can occur because devices that support accessory mode (but are not in that mode)
+initially report the <em>device</em> manufacturer vendor and product IDs instead
+of the <em>AOA</em> vendor and product IDs.</p>
+
+<p>The accessory should try to start the device in accessory mode to determine
+if the device supports that mode:</p>
+
<ul>
- <li>Send a 51 control request ("Get Protocol") to figure out if the device supports the Android
- accessory protocol. A non-zero number is returned if the protocol is supported, which
- represents the version of the protocol that the device supports (currently, only version 1
- exists). This request is a control request on endpoint 0 with the following characteristics:
+ <li>Send a 51 control request ("Get Protocol") to determine if the device
+ supports the Android accessory protocol. If the device supports the protocol,
+ it returns a non-zero number that represents the supported protocol version.
+ The control request is on endpoint 0 with the following characteristics:
<pre>
requestType: USB_DIR_IN | USB_TYPE_VENDOR
@@ -75,10 +101,12 @@
device to the accessory)
</pre>
</li>
- <li>If the device returns a proper protocol version, send identifying string information to the
- device. This information allows the device to figure out an appropriate application for this
- accessory and also present the user with a URL if an appropriate application does not exist.
- These requests are control requests on endpoint 0 (for each string ID) with the following
+
+ <li>If the device returns a supported protocol version, send a control request
+ with identifying string information to the device. This information allows the
+ device to determine an appropriate application for the accessory (or present a
+ URL to the user if an appropriate application does not exist). The control
+ request is on endpoint 0 (for each string ID) with the following
characteristics:
<pre>
@@ -89,8 +117,8 @@
data zero terminated UTF8 string sent from accessory to device
</pre>
- <p>The following string IDs are supported, with a maximum size of 256 bytes for each string
- (must be zero terminated with `\0`).</p>
+ <p>The following string IDs are supported, with a maximum size of 256 bytes
+ for each string (must be zero-terminated with <code>\0</code>).</p>
<pre>
manufacturer name: 0
@@ -101,8 +129,9 @@
serial number: 5
</pre>
</li>
- <li>When the identifying strings are sent, request the device start up in accessory mode. This
- request is a control request on endpoint 0 with the following characteristics:
+
+ <li>Send a control request to ask the device to start in accessory mode. The
+ control request is on endpoint 0 with the following characteristics:
<pre>
requestType: USB_DIR_OUT | USB_TYPE_VENDOR
@@ -114,25 +143,37 @@
</li>
</ul>
-<p>After sending the final control request, the connected USB device should re-introduce itself
-on the bus in accessory mode and the accessory can re-enumerate the connected devices. The
-algorithm jumps back to
-<a href="#determine-accessory-mode-support">determining the device's accessory mode support</a>
-to check for the vendor and product ID. The vendor ID and product ID of the device will be
-different if the device successfully switched to accessory mode and will now correspond to
-Google's vendor and product IDs instead of the device manufacturer's IDs. The accessory can now
-<a href="#establish-communication-with-the-device">establish communication with the device</a>.</p>
-<p>If at any point these steps fail, the device does not support Android accessory mode and the
-accessory should wait for the next device to be connected.</p>
-<h2 id="establish-communication-with-the-device">Establish Communication with the Device</h2>
-<p>If an Android-powered device in accessory mode is detected, the accessory can query the
-device's interface and endpoint descriptors to obtain the bulk endpoints to communicate with the
-device. An Android-powered device that has a product ID of <code>0x2D00</code> has one interface with two bulk
-endpoints for input and output communication. A device with product ID of <code>0x2D01</code> has two
-interfaces with two bulk endpoints each for input and output communication. The first interface
-is for standard communication while the second interface is for ADB communication. To communicate
-on an interface, all you need to do is find the first bulk input and output endpoints, set the
-device's configuration to a value of 1 with a <code>SET_CONFIGURATION</code> (<code>0x09</code>) device request, then
-communicate using the endpoints.</p>
+<p>After completing these steps, the accessory should wait for the connected USB
+device to re-introduce itself on the bus in accessory mode, then re-enumerate
+connected devices. The algorithm returns to
+<a href="#determine-accessory-mode-support">determine accessory mode support</a>
+to check the vendor and product IDs, which should be correct (e.g. correspond to
+Google's vendor and product IDs instead of the device manufacturer's IDs) if the
+device successfully switched to accessory mode. If IDs are correct, the
+accessory moves to <a href="#establish-communication-with-the-device">establish
+communication with the device</a>.</p>
+
+<p>If any step fails, the accessory determines the device does not support
+Android accessory mode and waits for the next device to connect.</p>
+<h2 id="establish-communication-with-the-device">Establish communication with
+the device</h2>
+
+<p>If the accessory detects an Android-powered device in accessory mode, the
+accessory can query the device interface and endpoint descriptors to obtain the
+bulk endpoints for communicating with the device.</p>
+
+<p>The number of interfaces and bulk endpoints depends on the product ID. An
+Android-powered device with a product ID of:</p>
+
+<ul>
+<li><code>0x2D00</code> has one interface with two bulk endpoints for input and
+output communication.</li>
+<li><code>0x2D01</code> has two interfaces with two bulk endpoints each for
+input and output communication. The first interface handles standard
+communication and the second interface handles ADB communication. To use an
+interface, locate the first bulk input and output endpoints, set the
+device configuration to a value of 1 with a <code>SET_CONFIGURATION</code>
+(<code>0x09</code>) device request, then communicate using the endpoints.</li>
+</ul>
\ No newline at end of file
diff --git a/src/accessories/aoa2.jd b/src/accessories/aoa2.jd
index c48bf25..2cbdc47 100644
--- a/src/accessories/aoa2.jd
+++ b/src/accessories/aoa2.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ 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.
@@ -16,24 +16,37 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>This document describes the changes to the Android Open Accessory (AOA) protocol since its
-initial release, and is a supplement to the documentation of the
-<a href="{@docRoot}accessories/aoa.html">first release of AOA</a>.</p>
-<p>The Android Open Accessory Protocol 2.0 adds two new features: audio output (from the Android
-device to the accessory) and support for the accessory acting as one or more Human Interface Devices
-(HID) to the Android device. The Android SDK APIs available to Android application developers
-remain unchanged.</p>
-<h2 id="detecting-android-open-accessory-20-support">Detecting Android Open Accessory 2.0 Support</h2>
-<p>In order for an accessory to determine if a connected Android device supports accessories and at
-what protocol level, the accessory must send a <code>getProtocol()</code> command and check the result.
-Android devices supporting the initial version of the Android Open Accessory protocol return a
-<code>1</code>, representing the protocol version number. Devices that support the new features described
-in this document must return <code>2</code> for the protocol version. Version 2.0 of the protocol is
-upwardly compatible, so accessories designed for the original accessory protocol still work
-with newer Android devices. The following example from the Accessory Development Kit 2011
+<p>This document describes changes in the Android Open Accessory (AOA) protocol
+since its initial release and supplements
+<a href="{@docRoot}accessories/aoa.html">AOA 1.0 documentation</a>. AOAv2
+adds the following features:</p>
+
+<ul>
+<li>Audio output (from the Android device to the accessory).</li>
+<li>Support for the accessory acting as one or more Human Interface Devices
+(HID) to the Android device.</li>
+</ul>
+
+<p>Android SDK APIs available to Android application developers are unchanged.
+</p>
+
+
+<h2 id="detecting-android-open-accessory-20-support">Detecting AOAv2 support</h2>
+
+<p>To determine if a connected Android device supports accessories and the
+supported protocol version, an accessory must send a <code>getProtocol()</code>
+command and check the result. Android devices that support only the feautures
+in AOAv1 must return <code>1</code> as the protocol version; devices that
+support the additional feautres in AOAv2 must return <code>2</code> as the
+protocol version. AOAv2 is backward-compatible with AOAv1, so accessories
+designed for the original accessory protocol continue to work with newer Android
+devices.</p>
+
+<p>The following example from the Accessory Development Kit 2011
<a href="http://developer.android.com/tools/adk/adk2.html#src-download">source code</a>
-(<code><adk-src>/adk1/board/AndroidAccessory/AndroidAccessory.cpp</code>) library demonstrates this protocol
-check:</p>
+(<code><adk-src>/adk1/board/AndroidAccessory/AndroidAccessory.cpp</code>)
+library demonstrates this protocol check:</p>
+
<pre><code>bool AndroidAccessory::switchDevice(byte addr)
{
int protocol = getProtocol(addr);
@@ -56,35 +69,77 @@
return true;
}
</code></pre>
-<p>AOA 2.0 includes new USB product IDs, one for each combination of USB interfaces available when
-in accessory mode. The possible USB interfaces are:</p>
-<ul>
-<li><strong>accessory</strong> - An interface providing 2 bulk endpoints for communicating with an
-Android application.</li>
-<li><strong>audio</strong> - A new standard USB audio class interface for streaming audio
-from an Android device to an accessory.</li>
-<li><strong>adb</strong> - An interface intended only for debugging purposes while developing an
-accessory. Only enabled if the user has USB Debugging enabled in Settings on the Android device.</li>
-</ul>
-<p>In AOA 1.0, there are only two USB product IDs:</p>
-<ul>
-<li><code>0x2D00</code> - accessory</li>
-<li><code>0x2D01</code> - accessory + adb</li>
-</ul>
-<p>AOA 2.0 adds an optional USB audio interface and, therefore, includes product IDs for the new
-combinations of USB interfaces:</p>
-<ul>
-<li><code>0x2D02</code> - audio</li>
-<li><code>0x2D03</code> - audio + adb</li>
-<li><code>0x2D04</code> - accessory + audio</li>
-<li><code>0x2D05</code> - accessory + audio + adb</li>
-</ul>
-<h2 id="audio-support">Audio Support</h2>
-<p>AOA 2.0 includes optional support for audio output from an Android device to an accessory. This
-version of the protocol supports a standard USB audio class interface that is capable of 2 channel
-16-bit PCM audio with a bit rate of 44100 Khz. AOA 2.0 is currently limited to this output mode, but
-additional audio modes may be added in the future.</p>
-<p>To enable the audio support, the accessory must send a new USB control request:</p>
+
+<p>AOAv2 includes new USB product IDs for each combination of USB interfaces
+available in accessory mode:</p>
+
+<table id="AOA-version-comparison">
+<tbody>
+
+<tr>
+<th>Version</th>
+<th>Product ID</th>
+<th>Communication</th>
+<th>Description</th>
+</tr>
+
+<tr>
+<td rowspan="2">AOAv1</td>
+<td><code>0x2D00</code></td>
+<td>accessory</td>
+<td>Provides two bulk endpoints for communicating with an Android
+application.</td>
+</tr>
+
+<tr>
+<td><code>0x2D01</code></td>
+<td>accessory + adb</td>
+<td>For debugging purposes during accessory development. Available only if the
+user has enabled <em>USB Debugging</em> in the Android device settings.</td>
+</tr>
+
+<tr>
+<td rowspan="4">AOAv2</td>
+<td><code>0x2D02</code></td>
+<td>audio</td>
+<td>For streaming audio from an Android device to an accessory.</td>
+</tr>
+
+<tr>
+<td><code>0x2D03</code></td>
+<td>audio + adb</td>
+<td></td>
+</tr>
+
+<tr>
+<td><code>0x2D04</code></td>
+<td>accessory + audio</td>
+<td></td>
+</tr>
+
+<tr>
+<td><code>0x2D05</code></td>
+<td>accessory + audio + adb</td>
+<td></td>
+</tr>
+
+</tbody>
+</table>
+
+
+<p>Product IDs used in AOAv1 (<code>0x2D00</code> and <code>0x2D01</code>)
+continue to be supported in AOAv2.</p>
+
+<h2 id="audio-support">Audio support</h2>
+
+<p>AOAv2 includes support for audio output from an Android device to an
+accessory via a standard USB audio class interface capable of 2 channel, 16-bit
+PCM audio with a bit rate of 44100 Khz (additional audio modes may be added in
+the future).</p>
+
+<p>To enable audio support, the accessory must send a new USB control request:
+</p>
+
<pre><code>**SET_AUDIO_MODE**
requestType: USB_DIR_OUT | USB_TYPE_VENDOR
request: 58
@@ -93,39 +148,53 @@
index: 0
data none
</code></pre>
-<p>This command must be sent <em>before</em> sending the <code>ACCESSORY_START</code> command for
-entering accessory mode.</p>
-<h2 id="hid-support">HID Support</h2>
-<p>AOA 2.0 allows the accessory to register one or more USB Human Interface Devices (HID) with
-an Android device. This approach reverses the direction of communication for typical USB HID
-devices like USB mice and keyboards. Normally, the HID device is a peripheral connected to a USB
-host like a personal computer. But in the case of the AOA protocol, the USB host acts as one or more
-input devices to a USB peripheral.</p>
-<p>HID support in AOA 2.0 is simply a proxy for standard HID events. The implementation makes no
-assumptions about the content or type of events and merely passes it through to the input system,
-so an AOA 2.0 accessory can act as any HID device (mouse, keyboard, game controller, etc.). It
-can be used for something as simple as the play/pause button on a media dock, or something as
-complicated as a docking station with a mouse and full QWERTY keyboard.</p>
-<p>The AOA 2.0 protocol adds four new USB control requests to allow the accessory to act as one or
-more HID input devices to the Android device. Since HID support is done entirely through
-control requests on endpoint zero, no new USB interface is needed to provide this support. The
-control requests are as follows:</p>
+
+<p>This command must be sent <em>before</em> sending the
+<code>ACCESSORY_START</code> command for entering accessory mode.</p>
+
+<h2 id="hid-support">HID support</h2>
+
+<p>AOAv2 allows accessories to register one or more USB Human Interface
+Devices (HID) with an Android device. This approach reverses the direction of
+communication for typical USB HID devices such as USB mice and keyboards.
+Normally, the HID device is a peripheral connected to a USB host (i.e. a
+personal computer), but in AOA the USB host can act as one or more input
+devices to a USB peripheral.</p>
+
+<p>HID support is a proxy for standard HID events; the
+implementation makes no assumptions about the content or type of events and
+simply passes it through to the input system, enabling an AOAv2 accessory to
+act as any HID device (mouse, keyboard, game controller, etc.). You can use HID
+support to provide basic functionality, such as a play/pause button on a media
+dock, or for advanced functionality such as a docking station with a mouse and
+full QWERTY keyboard.</p>
+
+<p>AOAv2 adds new USB control requests that allow the accessory to act as
+one or more HID input devices to the Android device. HID support is handled
+entirely through control requests on endpoint zero, so no new USB interface is
+needed. The four new control requests are:</p>
+
<ul>
-<li><strong>ACCESSORY_REGISTER_HID</strong> registers a new HID device with the Android device.
-The accessory provides an ID number that is used to identify the HID device for the other three
-calls. This ID is valid until USB is disconnected or until the accessory sends
-<code>ACCESSORY_UNREGISTER_HID</code> to unregister the HID device.</li>
-<li><strong>ACCESSORY_UNREGISTER_HID</strong> unregisters a HID device that was previously
-registered with <code>ACCESSORY_REGISTER_HID</code>.</li>
-<li><strong>ACCESSORY_SET_HID_REPORT_DESC</strong> sends a report descriptor for a HID device to
-the Android device. This request is used to describe the capabilities of the HID device, and must
-be sent before reporting any HID events to the Android device. If the report descriptor is larger
-than the maximum packet size for endpoint zero, multiple <code>ACCESSORY_SET_HID_REPORT_DESC</code> commands
-are sent in order to transfer the entire descriptor.</li>
-<li><strong>ACCESSORY_SEND_HID_EVENT</strong> sends input events from the accessory to the Android
+<li><strong>ACCESSORY_REGISTER_HID</strong> registers a new HID device with the
+Android device. The accessory provides an ID used to identify the HID device for
+the other three calls. This ID is valid until USB disconnects or until the
+accessory sends <code>ACCESSORY_UNREGISTER_HID</code> to unregister the HID
device.</li>
+<li><strong>ACCESSORY_UNREGISTER_HID</strong> unregisters a HID device
+previously registered with <code>ACCESSORY_REGISTER_HID</code>.</li>
+<li><strong>ACCESSORY_SET_HID_REPORT_DESC</strong> sends a report descriptor for
+a HID device to the Android device. This request is used to describe the
+capabilities of the HID device and must be sent before reporting any HID events
+to the Android device. If the report descriptor is larger than the maximum
+packet size for endpoint zero, multiple
+<code>ACCESSORY_SET_HID_REPORT_DESC</code> commands are sent to transfer the
+entire descriptor.</li>
+<li><strong>ACCESSORY_SEND_HID_EVENT</strong> sends input events from the
+accessory to the Android device.</li>
</ul>
-<p>The code definitions for these new control requests are as follows:</p>
+
+<p>The code definitions for the new control requests are:</p>
+
<pre><code>/* Control request for registering a HID device.
* Upon registering, a unique ID is sent by the accessory in the
* value parameter. This ID will be used for future commands for
@@ -174,23 +243,34 @@
*/
#define ACCESSORY_SEND_HID_EVENT 57
</code></pre>
-<h2 id="interoperability-with-aoa-10-features">Interoperability with AOA 1.0 Features</h2>
-<p>The original <a href="{@docRoot}accessories/aoa.html">AOA protocol</a> provided support for an Android
-application to communicate directly with a USB host (accessory) over USB. AOA 2.0 keeps that
-support, but adds new features to allow the accessory to communicate with the Android operating
-system itself (specifically the audio and input systems). The design of the AOA 2.0 makes it is
-possible to build an accessory that also makes use of the new audio and/or HID support in addition
-to the original feature set. Simply use the new features described in this document in addition to
-the original AOA protocol features.</p>
-<h2 id="connecting-aoa-20-without-an-android-app">Connecting AOA 2.0 without an Android App</h2>
-<p>It is possible to design an accessory (for example, an audio dock) that uses the new audio and
-HID support, but does not need to communicate with an application on the Android device. In that
-case, the user would not want to see the dialog prompts related to finding and associating the newly
-attached accessory with an Android application that can communicate with it. To prevent these
-dialogs from appearing after the device and accessory are connected, the accessory can simply not
-send the manufacturer and model names to the Android device. If these strings are not provided to
-the Android device, then the accessory is able to make use of the new audio and HID support in AOA
-2.0 without the system attempting to find an application to communicate with the accessory. Also,
-if these strings are not provided, the accessory USB interface is not present in the Android
-device USB configuration after the device enters accessory mode.</p>
+<h2 id="interoperability-with-aoa-10-features">Interoperability with AOAv1</h2>
+
+<p>The original protocol (<a href="{@docRoot}accessories/aoa.html">AOAv1</a>)
+provides support for an Android application to communicate directly with a USB
+host (accessory) over USB. AOAv2 continues this support and adds new features
+to allow the accessory to communicate with the Android operating system itself
+(specifically the audio and input systems). The design of AOAv2 makes it
+possible to build an accessory that uses the new audio and HID support
+in addition to the original feature set. Simply use the new features along with
+the original features.</p>
+
+<h2 id="connecting-aoa-20-without-an-android-app">Connecting AOAv2 without an
+Android app</h2>
+
+<p>You can design an accessory (such as an audio dock) that uses audio and HID
+support but does not communicate with an application on the Android device. For
+these accessories, users do not need to receive dialog prompts for finding and
+associating the newly attached accessory with an Android application that can
+communicate with it.</p>
+
+<p>To suppress such dialogs after an accessory connects, the
+accessory can choose not to send the manufacturer and model names to the Android
+device. When these strings are not provided to the Android device:</p>
+
+<ul>
+<li>The system does not attempt to find an application to communicate with the
+accessory.</li>
+<li>The accessory USB interface is not present in the Android device USB
+configuration after the device enters accessory mode.</li>
+</ul>
\ No newline at end of file
diff --git a/src/accessories/audio.jd b/src/accessories/audio.jd
index 92ce6fe..72c5e1d 100644
--- a/src/accessories/audio.jd
+++ b/src/accessories/audio.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ 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.
@@ -24,53 +24,67 @@
</div>
</div>
-<p>In implementing an audio accessory, such as a headset, headphone amplifier,
-microphone, DAC/ADC, or dock, you should consider how your accessory will
-connect with Android devices. In particular, you should decide
-if your accessory will use wired a 3.5 mm headset connector, Universal Serial
-Bus (USB), or a Bluetooth connection to stream music or other audio content.</p>
+<p>When implementing an audio accessory such as a headset, headphone amplifier,
+microphone, DAC/ADC, or dock, consider how the accessory connects to Android
+devices. The following sections describe wired 3.5 mm headset connections,
+Universal Serial Bus (USB) connections, and Bluetooth connections for streaming
+music or other audio content.</p>
+
<h2 id="audio-over-35mm">Audio over 3.5 mm headset connector</h2>
-<p>Many Android-based devices include a 3.5 mm (“mini”) headset connector. In
-addition to the traditional stereo output and mono input features, the <a
-href="headset-spec.html">Wired audio headset specification</a> defines standard
-impedances and functions so a range of Android devices and headsets can inter-operate.</p>
+<p>Many Android devices include a 3.5 mm (“mini”) headset connector.
+In addition to traditional stereo output and mono input features, the
+<a href="headset/specification.html">Wired audio headset specification</a>
+defines standard impedances and functions that enable interoperability between
+a range of Android devices and headsets.</p>
<h2 id="audio-over-usb">Audio over USB</h2>
<p>Android can use USB in several modes:</p>
<ul>
- <li>development
- <li>accessory
- <li>host
+ <li><strong>Development</strong>. Does not support audio. </li>
+ <li><strong>Accessory</strong>. Provided by Android Open Accessory (AOA) 2.0
+ and provides limited audio capability, as described in
+ <a href="custom.html#audio-over-usb">Connecting custom audio over USB</a>.
+ </li>
+ <li><strong>Host</strong>. Enables the Android device to drive the USB bus
+ and operate with a wide range of USB-based peripherals, including audio
+ interfaces. Host mode audio is described in
+ <a href="{@docRoot}devices/audio/usb.html">USB Digital Audio</a>.</li>
</ul>
-<p>In the development mode, there is no audio capability.</p>
-<p>Accessory mode is provided by the Open Accessory (AOA) protocol version 2.0.
-There is limited audio capability in accessory mode, as described in <a
-href="custom.html#audio-over-usb">Connecting custom audio over USB</a>.</p>
-<p>Host mode enables the Android device to drive the USB bus and operate with a
-wide range of USB-based peripherals, including audio interfaces. Host mode
-audio is described in <a href="{@docRoot}devices/audio/usb.html">USB Digital Audio</a>
<h2 id="audio-over-bluetooth">Audio over Bluetooth</h2>
-<p>An accessory that connects with Android over Bluetooth can use an Advanced Audio Distribution
-Profile (A2DP) connection stream music for playback. Playing audio over a Bluetooth with A2DP is
-supported on Android 1.5 (API Level 3) and higher. An Android user can connect to an accessory
-that supports this profile using the system Settings > Bluetooth and play music directly to the
-accessory without the need for a secondary application.</p>
-<p><strong>Note:</strong> If you want to provide a custom application for output to your audio
-accessory, note that the Android 3.0 (API Level 11) allows applications to operate an A2DP
-connection using the
-<a href="http://developer.android.com/reference/android/bluetooth/BluetoothA2dp.html"><code>BluetoothA2dp</code></a>
-class.</p>
+<p>An accessory that connects with Android over Bluetooth can use an Advanced
+Audio Distribution Profile (A2DP) connection stream music for playback. Playing
+audio over a Bluetooth with A2DP is supported on Android 1.5 (API Level 3) and
+higher. An Android user can connect to an accessory that supports this profile
+using the system Settings > Bluetooth and play music directly to the
+accessory without a secondary application.</p>
+
+<p>As of Android 3.0 (API Level 11), applications can operate an A2DP connection
+using the
+<a href="http://developer.android.com/reference/android/bluetooth/BluetoothA2dp.html">
+<code>BluetoothA2dp</code></a> class. To provide a custom application for
+output to an audio accessory, you must use Android 3.0 or higher.
+</p>
+
<h3 id="next-steps_1">Next steps</h3>
-<p>To get started on building an audio accessory that uses a Bluetooth connection:</p>
+<p>To get started building an audio accessory that uses a Bluetooth connection:
+</p>
<ul>
-<li>Select a hardware platform or build an hardware device that can support Bluetooth
- communications and the A2DP connection profile.</li>
+<li>Select a hardware platform or build an hardware device that can support
+Bluetooth communications and the A2DP connection profile.</li>
<li>Review the ADK 2012
- <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
- of an audio playback accessory using a Bluetooth connection.</li>
+ <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware
+ source code</a> (<code><adk-src>/adk2012/board/library/ADK2/</code>),
+ which includes an example implementation of an audio playback accessory using
+ a Bluetooth connection.</li>
</ul>
-<p><strong>Note:</strong> The ADK 2012 source code includes an open source Bluetooth stack that
-is built for the Texas Instruments CC2564 chip, but can work with any Bluetooth chip that
-implements a standard Host/Controller Interface (HCI).</p>
+
+<p class="note"><strong>Note:</strong> The ADK 2012 source code includes an open
+source Bluetooth stack built for the Texas Instruments CC2564 chip, but is
+designed to work with any Bluetooth chip that implements a standard
+Host/Controller Interface (HCI).</p>
+
+<h2 id="midi-over-usb">MIDI over USB and Bluetooth LE</h2>
+<p>Both USB and Bluetooth Low Energy can be used as transports for the
+<a href="http://en.wikipedia.org/wiki/MIDI">MIDI</a> protocol. For details, see
+<a href="{@docRoot}devices/audio/midi.html">MIDI</a>.</p>
\ No newline at end of file
diff --git a/src/accessories/custom.jd b/src/accessories/custom.jd
index 560f182..c4ff0f6 100644
--- a/src/accessories/custom.jd
+++ b/src/accessories/custom.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ 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.
@@ -24,88 +24,109 @@
</div>
</div>
-<p>An accessory for Android can be anything: keyboard, thermometer, robot, lighting control or
-anything else you can imagine. Accessories for Android all have one thing in common; they all
-connect to an Android device in some way. When starting out to build an accessory, you should
-decide how your accessory will connect to Android devices. This page gives you quick overview of
-your options for connecting your Android accessory and resources to help you get started.</p>
+<p>An accessory for Android can be anything: keyboard, thermometer, robot,
+lighting control, or anything else you can imagine. All Android accessories
+connect to an Android device in some way, so when building an accessory you must
+consider the type of connections your accessory will use. This page provides a
+quick overview of your options for connecting your Android accessory and
+a list of resources to help you get started.</p>
+
<h2 id="connecting-over-usb">Connecting over USB</h2>
-<p>An accessory that connects to an Android device through a USB cable must support the Android
-Open Accessory (AOA) protocol, which specifies how an accessory can establish communication with
-an Android device over a USB cable. Due to the low power output of Android devices, the AOA
-protocol requires the accessory act as a USB host, which means that the connecting accessory must
-power the bus.</p>
-<p>The AOA protocol has two versions which support different types of communication. Version
-1.0 supports a generic accessory communication and adb debugging. This version of the protocol is
-supported by the platform in Android 3.1 (API Level 12) and higher, and supported through an
-<a href="https://developers.google.com/android/add-ons/google-apis/">Add-On Library</a> in Android
-2.3.4 (API Level 10) and higher. Version 2.0 of the protocol is available in Android 4.1 (API Level
-16) and adds audio streaming and human interface device (HID) capabilities.</p>
-<p>If you use the general accessory protocol to communicate with your accessory (rather than the
-adb or audio protocol), you must provide an Android application that can detect the connection of
-your USB accessory and establish communication.</p>
-<h3 id="next-steps">Next steps</h3>
-<p>To get started on building an Android accessory that uses a USB connection:</p>
+<p>An accessory that connects to an Android device through a USB cable must
+support the Android Open Accessory (AOA) protocol, which specifies how an
+accessory can establish communication with an Android device via USB.
+Due to the low power output of Android devices, AOA requires the accessory to
+act as a USB host, meaning the connecting accessory must power the bus.</p>
+
+<p>AOA has two versions that support different types of communication:</p>
<ul>
-<li>Select a hardware platform or build a hardware device that can support USB host mode.</li>
-<li>Review the <a href="{@docRoot}accessories/index.html">AOA protocol</a> specifications to understand
- how to implement this protocol on your accessory hardware. Implementing the
- <a href="{@docRoot}accessories/aoa2.html">AOA 2.0 protocol</a> is recommended for all new Android USB
- accessories.</li>
-<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which demonstrates an implementation of an accessory
- using a USB connection for general data communications and audio streaming.</li>
-<li>If you are planning to build an Android application that communicates with your accessory
- via USB, review the ADK 2012 Android
- <a href="http://developer.android.com/tools/adk/adk2.html#src-download">application source code</a>
- (<code><adk-src>/adk2012/app/</code>).</li>
+<li><strong>AOAv1</strong>. Supports generic accessory communication and adb
+debugging. Available in Android 3.1 (API Level 12) and higher and supported
+through an
+<a href="https://developers.google.com/android/add-ons/google-apis/">Add-On
+Library</a> in Android 2.3.4 (API Level 10) and higher.</li>
+<li><strong>AOAv2</strong>. Supports audio streaming and human interface
+device (HID) capabilities. Available in Android 4.1 (API Level 16).</li>
</ul>
+
+<p>If you use the general accessory protocol to communicate with your accessory
+(rather than the adb or audio protocol), you must provide an Android application
+that can detect the connection of your USB accessory and establish communication.
+</p>
+
+<h3 id="next-steps_0">Next steps</h3>
+<p>To get started building an Android accessory that uses a USB connection:
+</p>
+<ul>
+<li>Select a hardware platform or build a hardware device that can support USB
+host mode.</li>
+<li>Review <a href="{@docRoot}accessories/protocol.html">AOA</a> specifications to
+understand how to implement this protocol on your accessory hardware.
+Implementing <a href="{@docRoot}accessories/aoa2.html">AOAv2</a> is
+recommended for all new Android USB accessories.</li>
+<li>Review the ADK 2012
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware
+source code</a> (<code><adk-src>/adk2012/board/library/ADK2/</code>),
+which demonstrates an implementation of an accessory using a USB connection for
+general data communications and audio streaming.</li>
+<li>When planning to build an Android application that communicates with your
+accessory via USB, review the ADK 2012 Android
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">application
+source code</a> (<code><adk-src>/adk2012/app/</code>).</li>
+</ul>
+
<h2 id="connecting-over-bluetooth">Connecting over Bluetooth</h2>
-<p>An accessory that connects with Android devices over a Bluetooth connection can use the
-various connection profiles supported by Android, including the Simple Serial Protocol (SSP) and
-Advanced Audio Distribution Profile (A2DP) profile. An accessory that uses Bluetooth to connect to
-Android devices must support Bluetooth communications and at least one of the supported connection
-profiles.</p>
-<p>Users must enable Bluetooth on their Android device and pair with your accessory in order to
-use it. You can also provide a secondary Android application that handles any specialized
-communication, such as data input or control outputs, to interface with your accessory.</p>
+<p>An accessory that connects with Android devices over a Bluetooth connection
+can use connection profiles supported by Android, including the Simple Serial
+Protocol (SSP) and Advanced Audio Distribution Profile (A2DP) profile. An
+accessory that uses Bluetooth to connect to Android devices must support
+Bluetooth communications and at least one of the supported connection profiles.
+</p>
+<p>Users must enable Bluetooth on their Android device and pair with your
+accessory to use the accessory. You can also provide a secondary Android
+application that handles specialized communication such as data input or control
+outputs to interface with your accessory.</p>
+
<h3 id="next-steps_1">Next steps</h3>
-<p>To get started on building an Android accessory that uses a Bluetooth connection:</p>
+<p>To get started building an Android accessory that uses a Bluetooth connection:
+</p>
<ul>
-<li>Select a hardware platform or build an hardware device that can support Bluetooth
- communications and an Android supported connection profile, such as SSP or A2DP.</li>
-<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
- of general data communications and audio streaming using a Bluetooth connection.</li>
-<li>If you are planning to build an Android application that communicates with your accessory
- via Bluetooth, review the ADK 2012 Android
- <a href="http://developer.android.com/tools/adk/adk2.html#src-download">application source code</a>
- (<code><adk-src>/adk2012/app/</code>).</li>
+<li>Select a hardware platform or build an hardware device that can support
+Bluetooth communications and an Android supported connection profile, such as
+SSP or A2DP.</li>
+<li>Review the ADK 2012
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware
+source code</a> (<code><adk-src>/adk2012/board/library/ADK2/</code>),
+which includes an example implementation of general data communications and
+audio streaming using a Bluetooth connection.</li>
+<li>When planning to build an Android application that communicates with your
+accessory via Bluetooth, review the ADK 2012 Android
+<a href="http://developer.android.com/tools/adk/adk2.html#src-download">application
+source code</a> (<code><adk-src>/adk2012/app/</code>).</li>
</ul>
-<p><strong>Note:</strong> The ADK 2012 source code includes an open source Bluetooth stack which
-is built for the Texas Instruments CC2564 chip, but can work with any Bluetooth chip that
-supports a standard Host/Controller Interface (HCI).</p>
+
+<p class="note"><strong>Note:</strong> The ADK 2012 source code includes an open
+source Bluetooth stack built for the Texas Instruments CC2564 chip but is
+designed to work with any Bluetooth chip that supports a standard
+Host/Controller Interface (HCI).</p>
<h2 id="audio-over-usb">Connecting audio over USB</h2>
-<p>An accessory that connects with Android over USB connection may use the Android Open
-Accessory (AOA) protocol version 2.0. This version of the AOA protocol is supported on Android 4.1
-(API Level 16) and higher. Once an Android device connects to an accessory that supports this
-protocol, the Android system treats it as a standard audio output device and routes all audio to
-that accessory. No secondary software application is required on the Android device.</p>
-<p><strong>Note:</strong> Due to the low power output of Android devices, the Android Open Accessory
-Protocol requires that accessories act as a USB host, which means that the connecting accessory
-must power the bus.</p>
-<h3 id="next-steps">Next steps</h3>
-<p>To get started on building an audio accessory that uses a USB connection:</p>
-<ul>
-<li>Select a hardware platform or build a hardware device that can support USB host mode.</li>
-<li>Review the <a href="{@docRoot}accessories/aoa2.html">AOA 2.0 protocol</a> specification to understand
- how to implement this protocol on your accessory hardware.</li>
-<li>Review the ADK 2012 <a href="http://developer.android.com/tools/adk/adk2.html#src-download">firmware source code</a>
- (<code><adk-src>/adk2012/board/library/ADK2/</code>), which includes an example implementation
- of an audio playback accessory using a USB connection.</li>
-</ul>
-<p><strong>Note:</strong> The AOA 2.0 protocol also supports the
-<a href="{@docRoot}accessories/aoa2.html#hid-support">human interface device</a> (HID) protocol through a USB
-connection, enabling accessories such as audio docks to provide hardware play back controls such
-as pause, fast-forward or volume buttons.</p>
+<p>An accessory that connects with Android over USB can use AOAv2 (supported on
+Android 4.1 (API Level 16) and higher. After an Android device connects to an
+accessory that supports this protocol, the Android system treats it as a
+standard audio output device and routes all audio to that accessory. No
+secondary software application is required on the Android device.</p>
+
+<p class="note"><strong>Note:</strong> Due to the low power output of Android
+devices, AOA requires accessories to act as a USB host, meaning the connecting
+accessory must power the bus.</p>
+
+<h3 id="next-steps_2">Next steps</h3>
+<p>To get started building an audio accessory that uses a USB connection, see
+<a href="#next-steps_0">next steps for USB connections.</a></p>
+
+<p>AOAv2 also supports the
+<a href="{@docRoot}accessories/aoa2.html#hid-support">human interface device</a>
+(HID) protocol through a USB connection, enabling accessories such as audio
+docks to provide hardware play back controls such as pause, fast-forward or
+volume buttons.</p>
\ No newline at end of file
diff --git a/src/accessories/headset-spec.jd b/src/accessories/headset-spec.jd
deleted file mode 100644
index c9a749e..0000000
--- a/src/accessories/headset-spec.jd
+++ /dev/null
@@ -1,697 +0,0 @@
-page.title=Wired audio headset specification
-@jd:body
-
-<!--
- Copyright 2014 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>
-
-<p><em>Version 1.1</em></p>
-
-<p>This document specifies the requirements for headsets and mobile devices to
-function uniformly across the Android ecosystem. It is separated into two
-sections beginning with the specifications for the headset
-accessory followed by the specifications for the mobile device.</p>
-
-<h2 id=headset_accessory_plug_specifications>Headset Accessory (Plug) Specifications</h2>
-
-<p>The requirements in the following section apply to the headset accessory.</p>
-
-<h3 id=functions>Functions</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Stereo Audio Out</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Audio in (Mic)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Ground</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
-</table>
-
-<h3 id=control-function_mapping>Control-Function Mapping</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Control Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Function A</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Play/pause/hook (Short Press), Trigger Assist (Long Press), Next (double press)</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function B</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td>
-<p>Vol+</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function C</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td>
-<p>Vol-</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function D</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td>
-<p>Reserved (Nexus devices will use this reserved function to launch Google
-voice search)</p>
-</td>
- </tr>
-</table>
-
-<p><strong>Assign functions to buttons as follows</strong>:</p>
-
-<ul>
- <li> All one-button headsets must implement Function A.
- <li> Headsets with multiple buttons must implement functions according to the
-following pattern:
- <ul>
- <li> 2 functions: A and D
- <li> 3 functions: A, B, C
- <li> 4 functions: A, B, C, D
- </ul>
-</ul>
-
-<h3 id=mechanical>Mechanical</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- <th>
-<p><strong>Notes</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>4 conductor 3.5mm plug</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Ref: EIAJ-RC5325A standard</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>CTIA pinout order (LRGM)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Except in regions with legal requirements for OMTP pinout</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>OMTP pinout order (LRMG)</p>
-</td>
- <td>
-<p>Optional</p>
-</td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>Microphone</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Must not be obstructed when operating headset controls</p>
-</td>
- </tr>
-</table>
-
-<h3 id=electrical>Electrical</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Accessory Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Ear speaker impedance</p>
-</td>
- <td>
-<p><strong>16 ohms or higher</strong></p>
-</td>
- <td>
-<p>Recommend 32 - 300 ohms</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Mic DC resistance</p>
-</td>
- <td>
-<p><strong>1000 ohms or higher</strong></p>
-</td>
- <td>
-<p>Mic characteristics must be compliant with section 5.4 “Audio Recording” of
-current Android Compatibility Definition Document (CDD)</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Control Function Equivalent impedance*</p>
-
-<p>*Total impedance from positive mic terminal to GND when button is pressed with
-2.2 V mic bias applied through 2.2 kOhm resistor</p>
-</td>
- <td>
-<p><strong>0 ohm</strong></p>
-</td>
- <td>
-<p>[Function A] Play/Pause/Hook</p>
-</td>
- </tr>
- <tr>
- <td></td>
- <td>
-<p><strong>240 ohm</strong> +/- 1% resistance</p>
-</td>
- <td>
-<p>[Function B]</p>
-</td>
- </tr>
- <tr>
- <td></td>
- <td>
-<p><strong>470 ohm</strong> +/- 1% resistance</p>
-</td>
- <td>
-<p>[Function C] </p>
-</td>
- </tr>
- <tr>
- <td></td>
- <td>
-<p><strong>135 ohm</strong> +/- 1% resistance</p>
-</td>
- <td>
-<p>[Function D]</p>
-</td>
- </tr>
-</table>
-
-<p>In the following diagrams, Button A is mapped to Function A, Button B to
-Function B, and so on.</p>
-
-<h3 id=reference_headset_test_circuit_1>Reference Headset Test Circuit 1</h3>
-
-<img src="images/headset-circuit1.png" alt="Reference Headset Test Circuit 1" />
-<p class="img-caption"><strong>Figure 1.</strong> Reference headset test circuit 1</p>
-
-<p class="note"><strong>Note:</strong> The above diagram shows the CTIA pinout
-for a 4-segment plug. For the OMTP pinout, switch the positions of the MIC and
-GND segments.</p>
-
-<h3 id=reference_headset_test_circuit_2>Reference Headset Test Circuit 2</h3>
-
-<p>The second reference circuit shows how the actual resistor values (R1 - R4)
-are altered to meet this specification.</p>
-
-<img src="images/headset-circuit2.png" alt="Reference Headset Test Circuit 2" />
-<p class="img-caption"><strong>Figure 2.</strong> Reference headset test circuit 2</p>
-
-<p>The actual resistance of the buttons parallel with the microphone (R1-R4) is
-based on the microphone capsule resistance (Rmic) and the equivalent impedance
-values (ReqA-ReqD). Use the following formula:</p>
-
-<p><em>Rn=(Rmic*ReqN) / (ReqN-Rmic)</em></p>
-
-<p>Where R<em>n</em> is the actual resistance of a button, Req<em>N</em> is the
-equivalent impedance value of that button (provided), and Rmic is the
-microphone impedance value.</p>
-
-<p>The example above assumes a 5 kohm microphone impedance (Rmic). Therefore, to
-achieve an equivalent R4 impedance of 135 ohm (ReqD), the actual resistor value
-(R4) needs to be 139 ohms.</p>
-
-
-<h2 id=mobile_device_jack_specifications>Mobile Device (Jack) Specifications</h2>
-
-<p class="caution"><strong>Caution:</strong> To achieve compatibility with the
-headset specification above, devices that include a 4 conductor 3.5mm audio
-jack must meet the following specifications. Please see the <em>Analog audio
-ports</em> section of the <a
-href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition
-Document (CDD)</a> for Android compatibility requirements.</p>
-
-<p><strong>Headset Jack Functions</strong></p>
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Stereo Audio Out</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Audio in (Mic)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Ground</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- </tr>
-</table>
-
-<h3 id=software_mapping>Software mapping</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Function A control event </p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_MEDIA</p>
-
-<p>Android key KEYCODE_HEADSETHOOK</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function D control event</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_VOICECOMMAND</p>
-
-<p>Android key KEYCODE_VOICE_ASSIST</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function B control event</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_VOLUMEUP</p>
-
-<p>Android key VOLUME_UP</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Function C control event</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event KEY_VOLUMEDOWN</p>
-
-<p>Android key VOLUME_DOWN</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset insertion detection</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>input event SW_JACK_PHYSICAL_INSERT 7</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset type detection</p>
-</td>
- <td>
-<p><strong>Mic</strong></p>
-</td>
- <td>
-<p>input event SW_MICROPHONE_INSERT 4</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset type detection</p>
-</td>
- <td>
-<p><strong>No Mic</strong></p>
-</td>
- <td>
-<p>input event SW_HEADPHONE_INSERT 2</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset speaker impedance</p>
-</td>
- <td>
-<p><strong>Required Headphone (low)</strong></p>
-</td>
- <td>
-<p>Failure mode is to indicate headphones so that limitation would be on</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Headset speaker impedance</p>
-</td>
- <td>
-<p><strong>Required Line In (high)</strong></p>
-</td>
- <td>
-<p>input event SW_LINEOUT_INSERT 6</p>
-</td>
- </tr>
-</table>
-
-<h3 id=mechanical11>Mechanical</h3>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Description</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>4 conductor 3.5mm jack</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>CTIA pinout order (LRGM)</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>3 Pin & Mono Plug Compatible</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>OMTP pinout order (LRMG)</p>
-</td>
- <td>
-<p>Optional but <strong>Strongly Recommended</strong></p>
-</td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>Headset detect sequence</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Plug insert notification must only be triggered after all contacts on plug are
-touching their relevant segments. This will prevent unreliable headset
-detection due to slow insertion. </p>
-</td>
- </tr>
-</table>
-
-<h3 id=electrical12>Electrical</h3>
-
-<h4 id=general>General</h4>
-
-<table>
- <tr>
- <th>
-<p><strong>Function</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Notes</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p>Maximum output voltage drive</p>
-</td>
- <td>
-<p>150mV </p>
-</td>
- <td>
-<p>>= 150mV on 32 ohm</p>
-
-<p>Test conditions: EN50332-2</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Mic bias resistance </p>
-</td>
- <td>
-<p>Required</p>
-</td>
- <td>
-<p>Flexible on detection method used and microphone bias resistor selection.
-Require that all button resistance value ranges specified below be detected and
-related to their respective function</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>Mic bias voltage</p>
-</td>
- <td>
-<p>1.8V - 2.9V</p>
-</td>
- <td>
-<p>To guarantee compatibility to common microphone capsules.</p>
-</td>
- </tr>
-</table>
-
-<h4 id=function_impedance_and_threshold_detection>Function Impedance and Threshold Detection</h4>
-
-<p>Devices must detect the following resistor ladder on the accessories. The
-accessories will be tested to the standardized circuit diagram in the diagram
-illustrated earlier (Reference Headset Test Circuit) where the total impedance
-is measured from MIC terminal to GND when a button is pressed with 2.2V mic
-bias applied through 2.2 kOhm resistor. This is the same effective resistance
-as the button detection circuit with the microphone in parallel with the button
-resistor.</p>
-<table>
- <tr>
- <th>
-<p><strong>Button Impedance Level</strong></p>
-</th>
- <th>
-<p><strong>Device Support</strong></p>
-</th>
- <th>
-<p><strong>Notes</strong></p>
-</th>
- </tr>
- <tr>
- <td>
-<p><strong>70 ohm or less</strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function A]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>110 - 180 ohm </strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function D]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>210 - 290 ohm</strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function B]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>360 - 680 ohm </strong></p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>[Function C]</p>
-</td>
- </tr>
- <tr>
- <td>
-<p><strong>Headset speaker impedance level</strong></p>
-</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td>
-<p>Low Threshold Detection</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Headphone (low) < 1 Kohm</p>
-</td>
- </tr>
- <tr>
- <td>
-<p>High Threshold Detection</p>
-</td>
- <td>
-<p><strong>Required</strong></p>
-</td>
- <td>
-<p>Line In (high) > 5 Kohm</p>
-</td>
- </tr>
-</table>
diff --git a/src/accessories/headset/images/button_configuration.png b/src/accessories/headset/images/button_configuration.png
new file mode 100644
index 0000000..52a0750
--- /dev/null
+++ b/src/accessories/headset/images/button_configuration.png
Binary files differ
diff --git a/src/accessories/headset/images/button_icons.png b/src/accessories/headset/images/button_icons.png
new file mode 100644
index 0000000..e7b695a
--- /dev/null
+++ b/src/accessories/headset/images/button_icons.png
Binary files differ
diff --git a/src/accessories/headset/images/button_spacing.png b/src/accessories/headset/images/button_spacing.png
new file mode 100644
index 0000000..2bc6cdf
--- /dev/null
+++ b/src/accessories/headset/images/button_spacing.png
Binary files differ
diff --git a/src/accessories/images/headset-circuit1.png b/src/accessories/headset/images/headset-circuit1.png
similarity index 100%
rename from src/accessories/images/headset-circuit1.png
rename to src/accessories/headset/images/headset-circuit1.png
Binary files differ
diff --git a/src/accessories/images/headset-circuit2.png b/src/accessories/headset/images/headset-circuit2.png
similarity index 100%
rename from src/accessories/images/headset-circuit2.png
rename to src/accessories/headset/images/headset-circuit2.png
Binary files differ
diff --git a/src/accessories/headset/images/icon_sizing.png b/src/accessories/headset/images/icon_sizing.png
new file mode 100644
index 0000000..8bfd128
--- /dev/null
+++ b/src/accessories/headset/images/icon_sizing.png
Binary files differ
diff --git a/src/accessories/headset/images/media_four.png b/src/accessories/headset/images/media_four.png
new file mode 100644
index 0000000..128dba0
--- /dev/null
+++ b/src/accessories/headset/images/media_four.png
Binary files differ
diff --git a/src/accessories/headset/images/media_one.png b/src/accessories/headset/images/media_one.png
new file mode 100644
index 0000000..3f9d4db
--- /dev/null
+++ b/src/accessories/headset/images/media_one.png
Binary files differ
diff --git a/src/accessories/headset/images/media_three.png b/src/accessories/headset/images/media_three.png
new file mode 100644
index 0000000..5f1105c
--- /dev/null
+++ b/src/accessories/headset/images/media_three.png
Binary files differ
diff --git a/src/accessories/headset/images/media_two.png b/src/accessories/headset/images/media_two.png
new file mode 100644
index 0000000..3b1e26c
--- /dev/null
+++ b/src/accessories/headset/images/media_two.png
Binary files differ
diff --git a/src/accessories/headset/images/microphone.png b/src/accessories/headset/images/microphone.png
new file mode 100644
index 0000000..1b19015
--- /dev/null
+++ b/src/accessories/headset/images/microphone.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_four.png b/src/accessories/headset/images/telephony_four.png
new file mode 100644
index 0000000..bea091e
--- /dev/null
+++ b/src/accessories/headset/images/telephony_four.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_one.png b/src/accessories/headset/images/telephony_one.png
new file mode 100644
index 0000000..0760f25
--- /dev/null
+++ b/src/accessories/headset/images/telephony_one.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_three.png b/src/accessories/headset/images/telephony_three.png
new file mode 100644
index 0000000..b2c8e29
--- /dev/null
+++ b/src/accessories/headset/images/telephony_three.png
Binary files differ
diff --git a/src/accessories/headset/images/telephony_two.png b/src/accessories/headset/images/telephony_two.png
new file mode 100644
index 0000000..1ba31e2
--- /dev/null
+++ b/src/accessories/headset/images/telephony_two.png
Binary files differ
diff --git a/src/accessories/headset/index.jd b/src/accessories/headset/index.jd
new file mode 100644
index 0000000..d66c6ac
--- /dev/null
+++ b/src/accessories/headset/index.jd
@@ -0,0 +1,29 @@
+page.title=Android Audio Headset
+@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.
+-->
+
+<p>This section describes the development and testing of the Android headset
+accessory interface. This documentation presents the interface guidelines for the
+Android headset inline remote.</p>
+
+<p>The goal is to maintain certain standards for consistency and design while
+allowing for freedom in design expression. If you choose to implement a
+dedicated Android headset accessory, please follow these guidelines to ensure
+your headset is compatible with devices following the recommendations in the <a
+href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition
+Document (CDD)</a>.</p>
diff --git a/src/accessories/headset/requirements.jd b/src/accessories/headset/requirements.jd
new file mode 100644
index 0000000..1f5c0d0
--- /dev/null
+++ b/src/accessories/headset/requirements.jd
@@ -0,0 +1,189 @@
+page.title=Headset Requirements
+@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=media>Media</h2>
+
+<p>If a user connects a headset to the device while playing media, the audio
+output (sound) should be heard only via the headset.</p>
+
+<p>For example, while playing media with the <a
+href="https://github.com/googlesamples/android-UniversalMusicPlayer">open
+source</a> <a
+href="https://android-developers.blogspot.com/2015/03/a-new-reference-app-for-multi-device.html">Universal
+Music Player</a>, pressing the play/pause button should pause playback.
+Pressing the same button when media is paused should resume playback.</p>
+
+<p>If the headset has volume control buttons: </p>
+
+<ul>
+ <li> Pressing the volume-up button should increase the volume incrementally each
+time the button is pressed until maximum volume is reached. If the volume-up
+button is pressed and held, the volume should gradually increase to maximum
+volume setting.
+ <li> Pressing the volume-down button should decrease the volume incrementally each
+time the button is pressed until entirely muted. If the volume-down button is
+pressed and held, the volume should gradually decrease to silent.
+ <li> Pressing the volume-up button when in a muted state should increase the volume
+one notch at a time starting from silent.
+</ul>
+
+<p><strong>Recommended for Apps</strong>: On disconnecting the headset, sound output should stop and playback should
+pause. On reconnecting, playback should not start again unless the user presses
+the play button. Upon pressing play, sound output should again be limited to
+the headset.</p>
+
+<h3 id=one_button>One button</h3>
+
+<img src="images/media_one.png" alt="Button functions for one-button headsets handling a media stream.">
+</span>
+
+<p class="img-caption"><strong>Figure 1.</strong> Button functions for one-button headsets handling a media stream.</p>
+
+<h3 id=two_buttons>Two buttons</h3>
+
+<img src="images/media_two.png" alt="Button functions for two-button headsets handling a media stream.">
+
+<p class="img-caption"><strong>Figure 2.</strong> Button functions for two-button headsets handling a media stream.</p>
+
+<h3 id=three_buttons>Three buttons</h3>
+
+<img src="images/media_three.png" alt="Button functions for three-button headsets handling a media stream.">
+
+<p class="img-caption"><strong>Figure 3.</strong> Button functions for three-button headsets handling a media stream.</p>
+
+<h3 id=four_buttons>Four buttons</h3>
+
+<img src="images/media_four.png" alt="Button functions for four-button headsets handling a media stream.">
+
+<p class="img-caption"><strong>Figure 4.</strong> Button functions for four-button headsets handling a media stream.</p>
+
+<h2 id=telephony>Telephony</h2>
+
+
+<p>If a user connects a headset to the device while a call is in progress, the
+conversation should continue on the headset. The call should not get
+disconnected, and the microphone should not be muted. If present, volume
+buttons should behave identically to media playback.</p>
+
+<p>Pressing the play/pause button while a phone call is in progress should toggle
+the microphone state between muted and unmuted. If a user receives calls while
+using the headset, the voice assistance button should allow handling of those
+calls:</p>
+
+<ul>
+ <li> While in a phone call, pressing quickly on the play/pause button should mute
+the microphone. And if pressed quickly again, the microphone should un-mute.
+ <li> While in a phone call, a long press on the play/pause button should end the
+telephone call.
+ <li> While receiving a phone call, pressing quickly on the play/pause button should
+accept the call.
+ <li> While receiving a phone call, a long press on the play/pause button should
+reject the call.
+</ul>
+
+<h3 id=one_button>One button</h3>
+
+<img src="images/telephony_one.png" alt="Button functions for one-button headsets handling a phone call.">
+
+<p class="img-caption"><strong>Figure 5.</strong> Button functions for one-button headsets handling a phone call. </p>
+
+<h3 id=two_buttons>Two buttons</h3>
+
+<img src="images/telephony_two.png" alt="Button functions for two-button headsets handling a phone call.">
+
+<p class="img-caption"><strong>Figure 6.</strong> Button functions for two-button headsets handling a phone call. </p>
+
+<h3 id=three_buttons>Three buttons</h3>
+
+<img src="images/telephony_three.png" alt="Button functions for three-button headsets handling a phone call.">
+
+<p class="img-caption"><strong>Figure 7.</strong> Button functions for three-button headsets handling a phone call. </p>
+
+<h3 id=four_buttons>Four buttons</h3>
+
+<img src="images/telephony_four.png" alt="Button functions for four-button headsets handling a phone call.">
+<p class="img-caption"><strong>Figure 8.</strong> Button functions for four-button headsets handling a phone call. </p>
+
+<h2 id=voice_assistance>Voice assistance</h2>
+
+<p>The voice assistance button is a new inline control standard for consistently
+and conveniently accessing a voice search feature from any approved wearable
+audio device. By pressing the button defined here, users will hear the two-tone
+signature <a href="http://en.wikipedia.org/wiki/Earcon">earcon</a> indicating that the device is listening and ready to receive the query.</p>
+
+<p>Whether embedded into a multi-function button or highlighted as a single
+button, it should always be quickly accessible, ergonomically correct, and
+placed intuitively as described in the following section.</p>
+
+<h2 id=buttons_and_function_mapping>Buttons and function mapping recommendations</h2>
+
+<p>The following diagrams depict the acceptable configuration of the Android voice
+assistance button.</p>
+
+<h3 id=options>Options</h3>
+
+<img src="images/button_configuration.png" alt="Button configuration options.">
+
+<p class="img-caption"><strong>Figure 9.</strong> Button configuration options. </p>
+
+<p>Buttons should always be front facing and spaced out so they can be easily
+located by touch only.</p>
+
+<h3 id=spacing>Spacing</h3>
+
+<p>Buttons must be more than 5mm and must have at least 5mm distance between
+buttons. For four-button headsets, there must be at least 9mm of space between
+button D and the cluster of other buttons. </p>
+
+<img src="images/button_spacing.png" alt="Button spacing requirements">
+
+<p class="img-caption"><strong>Figure 10.</strong> Button spacing requirements.</p>
+
+<h3 id=icon>Icon</h3>
+
+<p>In the following diagram, A is unlabeled or labeled with a dot. B is labeled
+with a + or an arrow pointing up. C is labeled with a - or an arrow pointing
+down. D is labeled with the selected button icon.</p>
+
+<img src="images/button_icons.png" alt="Button icon requirements">
+<p class="img-caption"><strong>Figure 11.</strong> Button icon requirements. </p>
+
+<h3 id=sizing>Sizing</h3>
+
+<p>The following diagram shows the ratio of button icon to the space around it.</p>
+
+<img src="images/icon_sizing.png" alt="Voice search button icon sizing requirements">
+
+<p class="img-caption"><strong>Figure 12.</strong> Voice search button icon sizing requirements. </p>
+
+<h3 id=microphone_port>Microphone port</h3>
+
+<p>The microphone should never be obstructed when operating the buttons. Place the
+port away from finger interface area.</p>
+
+<img src="images/microphone.png" alt="Microphone placement">
+
+<p class="img-caption"><strong>Figure 13.</strong> Microphone placement. </p>
diff --git a/src/accessories/headset/specification.jd b/src/accessories/headset/specification.jd
new file mode 100644
index 0000000..d1616b1
--- /dev/null
+++ b/src/accessories/headset/specification.jd
@@ -0,0 +1,410 @@
+page.title=Wired Audio Headset Specification (v1.1)
+@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>
+
+<p>This section specifies requirements for headsets and mobile devices to
+function uniformly across the Android ecosystem.</p>
+
+<h2 id="headset_accessory_plug_specifications">Headset accessory (plug)
+specifications</h2>
+
+<p>The following requirements apply to headset accessories.</p>
+
+<h3 id="functions">Functions</h3>
+
+<table style="width:50%">
+ <tr>
+ <th>Function</th>
+ <th>Accessory Support</th>
+ </tr>
+ <tr>
+ <td>Stereo Audio Out</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Audio in (Mic)</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Ground</td>
+ <td>Required</td>
+ </tr>
+</table>
+
+<h3 id="control-function_mapping">Control-function mapping</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Control Function</th>
+ <th style="width:33%">Accessory Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>Function A</td>
+ <td>Required</td>
+ <td>Play/pause/hook (Short Press), Trigger Assist (Long Press), Next
+ (Double Press)</td>
+ </tr>
+ <tr>
+ <td>Function B</td>
+ <td>Optional</td>
+ <td>Vol+</td>
+ </tr>
+ <tr>
+ <td>Function C</td>
+ <td>Optional</td>
+ <td>Vol-</td>
+ </tr>
+ <tr>
+ <td>Function D</td>
+ <td>Optional</td>
+ <td>Reserved (Nexus devices use this to launch Voice Assist)
+</td>
+ </tr>
+</table>
+
+<p>Assign functions to buttons as follows:</p>
+
+<ul>
+ <li> All one-button headsets must implement Function A.
+ <li> Headsets with multiple buttons must implement functions according to the
+following pattern:
+ <ul>
+ <li> 2 functions: A and D
+ <li> 3 functions: A, B, C
+ <li> 4 functions: A, B, C, D
+ </ul>
+</ul>
+
+<h3 id="mechanical">Mechanical</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Accessory Support</th>
+ <th style="width:33%">Notes</th>
+ </tr>
+ <tr>
+ <td>4 conductor 3.5mm plug</td>
+ <td>Required</td>
+ <td>Ref: EIAJ-RC5325A standard</td>
+ </tr>
+ <tr>
+ <td>CTIA pinout order (LRGM)</td>
+ <td>Required</td>
+ <td>Except in regions with legal requirements for OMTP pinout</td>
+ </tr>
+ <tr>
+ <td>OMTP pinout order (LRMG)</td>
+ <td>Optional</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>Microphone</td>
+ <td>Required</td>
+ <td>Must not be obstructed when operating headset controls</td>
+ </tr>
+</table>
+
+<h3 id="electrical">Electrical</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Accessory Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>Ear speaker impedance</td>
+ <td>16 ohms or higher</td>
+ <td>Recommend 32 - 300 ohms</td>
+ </tr>
+ <tr>
+ <td>Mic DC resistance</td>
+ <td>1000 ohms or higher
+</td>
+ <td>Mic characteristics must be compliant with section 5.4 “Audio
+ Recording” of the current
+ <a href="{@docRoot}compatibility/android-cdd.pdf">Android CDD</a></td>
+ </tr>
+ <tr>
+ <td rowspan="4">Control Function Equivalent impedance*</td>
+ <td>0 ohm</td>
+ <td>[Function A] Play/Pause/Hook</td>
+ </tr>
+ <tr>
+ <td>240 ohm +/- 1% resistance</td>
+ <td>[Function B]</td>
+ </tr>
+ <tr>
+ <td>470 ohm +/- 1% resistance</td>
+ <td>[Function C]</td>
+ </tr>
+ <tr>
+ <td>135 ohm +/- 1% resistance</td>
+ <td>[Function D]</td>
+ </tr>
+</table>
+
+<p><em>*Total impedance from positive mic terminal to GND when button is
+pressed with 2.2 V mic bias applied through 2.2 kOhm resistor</em></p>
+
+<p>In the following diagrams, Button A maps to Function A, Button B to
+Function B, and so on.</p>
+
+<h3 id="reference_headsets">Reference headset test circuits</h3>
+
+<p>The following diagram for Reference Headset Test Circuit 1 shows the CTIA
+pinout for a 4-segment plug. For the OMTP pinout, switch the positions of the
+MIC and GND segments.</p>
+
+<img src="images/headset-circuit1.png" alt="Reference Headset Test Circuit 1" />
+<p class="img-caption"><strong>Figure 1.</strong> Reference headset test circuit 1</p>
+
+<p>The following diagram for Reference Headset Test Circuit 2 shows how the
+actual resistor values (R1 - R4) are altered to meet this specification.</p>
+
+<img src="images/headset-circuit2.png" alt="Reference Headset Test Circuit 2" />
+<p class="img-caption"><strong>Figure 2.</strong> Reference headset test circuit 2</p>
+
+<p>The actual resistance of the buttons parallel with the microphone (R1-R4) is
+based on the microphone capsule resistance (Rmic) and the equivalent impedance
+values (ReqA-ReqD). Use the following formula:</p>
+
+<p><em>Rn=(Rmic*ReqN) / (ReqN-Rmic)</em></p>
+
+<p>Where R<em>n</em> is the actual resistance of a button, Req<em>N</em> is the
+equivalent impedance value of that button (provided), and Rmic is the
+microphone impedance value.</p>
+
+<p>The example above assumes a 5 kohm microphone impedance (Rmic); to achieve
+an equivalent R4 impedance of 135 ohm (ReqD), the actual resistor value (R4)
+must be 139 ohms.</p>
+
+<h2 id="mobile_device_jack_specifications">Mobile device (jack) specifications</h2>
+
+<p class="caution"><strong>Caution:</strong> To achieve compatibility with the
+headset specification, devices that include a 4 conductor 3.5mm audio jack
+must meet the following specifications. For Android compatibility requirements,
+refer to the <em>Analog audio ports</em> section of the <a
+href="{@docRoot}compatibility/android-cdd.pdf">Android CDD</a>.</p>
+
+<h3 id="headset_jack_functions">Functions</h3>
+
+<table>
+ <tr>
+ <th>Function</th>
+ <th>Device Support</th>
+ </tr>
+ <tr>
+ <td>Stereo Audio Out</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Audio in (Mic)</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Ground</td>
+ <td>Required</td>
+ </tr>
+</table>
+
+<h3 id="software_mapping">Software mapping</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Device Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>Function A control event</td>
+ <td>Required</td>
+ <td>input event KEY_MEDIA
+<p>Android key KEYCODE_HEADSETHOOK</p></td>
+ </tr>
+ <tr>
+ <td>Function D control event</td>
+ <td>Required</td>
+ <td>input event KEY_VOICECOMMAND
+<p>Android key KEYCODE_VOICE_ASSIST</p></td>
+ </tr>
+ <tr>
+ <td>Function B control event</td>
+ <td>Required
+</td>
+ <td>input event KEY_VOLUMEUP
+<p>Android key VOLUME_UP</p></td>
+ </tr>
+ <tr>
+ <td>Function C control event</td>
+ <td>Required</td>
+ <td>input event KEY_VOLUMEDOWN
+<p>Android key VOLUME_DOWN</p></td>
+ </tr>
+ <tr>
+ <td>Headset insertion detection</td>
+ <td>Required</td>
+ <td>input event SW_JACK_PHYSICAL_INSERT 7</td>
+ </tr>
+ <tr>
+ <td rowspan="2">Headset type detection</td>
+ <td>Mic</td>
+ <td>input event SW_MICROPHONE_INSERT 4</td>
+ </tr>
+ <tr>
+ <td>No Mic</td>
+ <td>input event SW_HEADPHONE_INSERT 2</td>
+ </tr>
+ <tr>
+ <td rowspan="2">Headset speaker impedance</td>
+ <td>Required Headphone (low)</td>
+ <td>Failure mode is to indicate headphones so limitation would be on</td>
+ </tr>
+ <tr>
+ <td>Required Line In (high)</td>
+ <td>input event SW_LINEOUT_INSERT 6</td>
+ </tr>
+</table>
+
+<h3 id="mechanical11">Mechanical</h3>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Device Support</th>
+ <th style="width:33%">Description</th>
+ </tr>
+ <tr>
+ <td>4 conductor 3.5mm jack</td>
+ <td>Required</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>CTIA pinout order (LRGM)</td>
+ <td>Required</td>
+ <td>3 Pin & Mono Plug Compatible</td>
+ </tr>
+ <tr>
+ <td>OMTP pinout order (LRMG)</td>
+ <td>Optional but strongly recommended</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>Headset detect sequence</td>
+ <td>Required</td>
+ <td>Plug insert notification must be triggered only after all contacts on
+ plug are touching their relevant segments (this prevents unreliable headset
+ detection due to slow insertion.</td>
+ </tr>
+</table>
+
+<h3 id="electrical12">Electrical</h3>
+
+<h4 id="general">General</h4>
+
+<table>
+ <tr>
+ <th style="width:33%">Function</th>
+ <th style="width:33%">Device Support</th>
+ <th style="width:33%">Notes</th>
+ </tr>
+ <tr>
+ <td>Maximum output voltage drive</td>
+ <td>150mV</td>
+ <td>>= 150mV on 32 ohm
+<p>Test conditions: EN50332-2</p></td>
+ </tr>
+ <tr>
+ <td>Mic bias resistance</td>
+ <td>Required</td>
+ <td>Flexible on detection method used and microphone bias resistor
+ selection. Require that all button resistance value ranges specified below
+ be detected and related to their respective function</td>
+ </tr>
+ <tr>
+ <td>Mic bias voltage</td>
+ <td>1.8V - 2.9V</td>
+ <td>To guarantee compatibility to common microphone capsules.</td>
+ </tr>
+</table>
+
+<h4 id="function_impedance_and_threshold_detection">Function impedance and
+threshold detection</h4>
+
+<p>Devices must detect the following resistor ladder on the accessories. The
+accessories will be tested to the standardized circuit diagram in the diagram
+illustrated earlier (Reference Headset Test Circuit) where the total impedance
+is measured from MIC terminal to GND when a button is pressed with 2.2V mic
+bias applied through 2.2 kOhm resistor. This is the same effective resistance
+as the button detection circuit with the microphone in parallel with the button
+resistor.</p>
+
+<table>
+ <tr>
+ <th style="width:40%">Button Impedance Level</th>
+ <th style="width:20%">Device Support</th>
+ <th style="width:40%">Notes</th>
+ </tr>
+ <tr>
+ <td>70 ohm or less</td>
+ <td>Required</td>
+ <td>[Function A]</td>
+ </tr>
+ <tr>
+ <td>110 - 180 ohm</td>
+ <td>Required</td>
+ <td>[Function D]</td>
+ </tr>
+ <tr>
+ <td>210 - 290 ohm</td>
+ <td>Required</td>
+ <td>[Function B]</td>
+ </tr>
+ <tr>
+ <td>360 - 680 ohm</td>
+ <td>Required</td>
+ <td>[Function C]</td>
+ </tr>
+ </table>
+
+ <table>
+ <tr>
+ <th style="width:40%">Headset Speaker Impedance Level</th>
+ <th style="width:20%">Device Support</th>
+ <th style="width:40%">Notes</th>
+ </tr>
+ <tr>
+ <td>Low Threshold Detection</td>
+ <td>Required</td>
+ <td>Headphone (low) < 1 Kohm</td>
+ </tr>
+ <tr>
+ <td>High Threshold Detection</td>
+ <td>Required</td>
+ <td>Line In (high) > 5 Kohm</td>
+ </tr>
+</table>
diff --git a/src/accessories/headset/testing.jd b/src/accessories/headset/testing.jd
new file mode 100644
index 0000000..c66d4f0
--- /dev/null
+++ b/src/accessories/headset/testing.jd
@@ -0,0 +1,112 @@
+page.title=Testing
+@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=headset_insertion>Headset insertion</h2>
+
+<ol>
+ <li> Start with the Android device turned off.
+ <li> Plug in the headset.
+ <li> Turn the device on.
+ <li> Unlock.
+ <li> Open the <a
+ href="https://github.com/googlesamples/android-UniversalMusicPlayer">open
+ source</a> <a
+ href="https://android-developers.blogspot.com/2015/03/a-new-reference-app-for-multi-device.html">Universal
+ Music Player</a>.
+ <li> Press the DUT volume buttons to maximize media volume.
+ <li> Start playing music and verify audio comes out of the headset.
+ <li> While Music is playing, disconnect the headset and verify music stops.
+ <li> Reconnect the headset, start playing music again, and verify audio comes out of
+the headset.
+</ol>
+
+<h2 id=volume_buttons>Volume buttons</h2>
+
+<ol>
+ <li> Play music and ensure it is coming out of the headset.
+ <li> Press (“short press”) on the volume-down button. Then verify the volume panel
+displays the media volume decrease by one notch and the volume output is
+reduced as expected.
+ <li> Long press on the volume-down button. Then verify the volume panel shows media
+volume going all the way down and volume output is reduced gradually to muted.
+ <li> Press on the volume-up button. Then verify the volume panel displays the media
+volume go up one notch and the volume output is increased as expected.
+ <li> Long press on the volume-up button. Then verify the volume panel shows the
+media volume go all the way up to maximum and the volume output is increased as
+expected.
+</ol>
+
+<h2 id=play_pause_for_music>Play/pause for music</h2>
+
+<p>Press quickly on the play/pause button and verify music stops playing out of
+the headset. If music was not already playing, then it should start playing out
+of the headset.</p>
+
+<h2 id=play_pause_for_telephony>Play/pause for telephony</h2>
+
+<ol>
+ <li> Make a phone call.
+ <li> Press quickly on the play/pause button while in the call.
+ <li> Verify the microphone mutes. And if you press quickly again, the microphone
+should un-mute.
+ <li> While still in the call, long press on the play/pause button.
+ <li> Verify the long press ends the telephone call
+ <li> Receive a phone call on the Android device.
+ <li> Press quickly on the play/pause button while the phone is ringing and verify
+the call is accepted.
+ <li> Receive another phone call on the Android device.
+ <li> Long press on the play/pause button while the phone is ringing and verify the
+call is rejected.
+</ol>
+
+<h2 id=play_pause_for_voice_actions_microphone>Play/pause for voice actions + microphone</h2>
+
+<ol>
+ <li> Open the screen on your Android device, unlock it, and go to the home screen.
+ <li> Long press on the play/pause button.
+ <li> Verify:
+ <ol>
+ <li> you hear a beep after which you should be able to make a voice search query,
+such as “What time is it?”
+ <li> you hear a response, such as “The time is ...”
+ </ol>
+ </ol>
+
+<h2 id=voice_button_for_voice_actions_microphone>Voice button for voice actions + microphone</h2>
+
+<ol>
+ <li> Open the screen on your Android device, unlock it, and go to the home screen.
+ <li> Short press on the voice button.
+ <li> Verify:
+ <ol>
+ <li> you hear a beep after which you should be able to make a search query, such as
+“What time is it?”
+ <li> you hear a response, such as “The time is ...”
+ </ol>
+ </ol>
+
+<p><strong>Important</strong>: A press on the voice button can launch launch any search app, for example
+Google search.</p>
diff --git a/src/accessories/index.jd b/src/accessories/index.jd
index d30c0ce..709b26a 100644
--- a/src/accessories/index.jd
+++ b/src/accessories/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2014 The Android Open Source Project
+ 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.
@@ -16,10 +16,8 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>Implement compelling accessories to extend the capabilities of your users'
-Android-powered devices. Android relies on a suite of standard protocols you
-can implement in your accessories to be compatible with a wide range of
-Android-powered devices.
+<p>Using a suite of standard protocols, you can implement compelling accessories
+that extend Android capabilities in a wide range of Android-powered devices.
</p>
<div class="layout-content-row">
@@ -29,8 +27,8 @@
<p>Android supports local on-device audio and remote off-device audio
over a wired 3.5 mm headset jack, USB connection, or Bluetooth.
Manufacturers should see the <a
- href="{@docRoot}accessories/headset-spec.html">wired audio headset
- specification</a>, while users may learn how to <a
+ href="{@docRoot}accessories/headset/specification.html">wired audio headset
+ specification</a>, while users can learn how to <a
href="https://support.google.com/nexus/answer/6127700">record and play
back audio using USB host mode</a>.</p>
<p><a href="{@docRoot}accessories/audio.html">» Audio Accessories</a></p>
@@ -38,9 +36,10 @@
<div class="layout-content-col span-6">
<h4 id="custom-accessories">Custom Accessories</h4>
- <p>What do you want to connect to your Android device? Alarm clock? Keyboard? Thermostat? Robot?
- Learn how to connect existing equipment or your own unique hardware to
- Android using the Android Open Accessory Protocol.</p>
+ <p>What do you want to connect to your Android device? Alarm clock?
+ Keyboard? Thermostat? Robot? Learn how to connect existing equipment or
+ your own unique hardware to Android using the Android Open Accessory
+ (AOA) protocol.</p>
<p><a href="{@docRoot}accessories/custom.html">» Custom Accessories</a></p>
</div>
diff --git a/src/accessories/protocol.jd b/src/accessories/protocol.jd
index 7ce3bb4..b04e634 100644
--- a/src/accessories/protocol.jd
+++ b/src/accessories/protocol.jd
@@ -1,44 +1,52 @@
-page.title=Android Open Accessory Protocol
+page.title=Android Open Accessory (AOA)
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ 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
+ 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.
+ 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.
-->
-<p> Android Open Accessory support allows external USB hardware (an Android USB accessory) to interact
-with an Android-powered device in a special accessory mode. When an Android-powered powered device
-is in accessory mode, the connected accessory acts as the USB host (powers the bus and enumerates
-devices) and the Android-powered device acts in the USB accessory role. Android USB accessories are
-specifically designed to attach to Android-powered devices and adhere to the Android Open Accessory
-Protocol, that allows them to detect Android-powered devices that support
-accessory mode. Accessories must also provide 500mA at 5V for charging power. Many previously
-released Android-powered devices are only capable of acting as a USB device and cannot initiate
-connections with external USB devices. Android Open Accessory support overcomes this limitation
-and allows you to build accessories that can interact with an assortment of Android-powered
-devices by allowing the accessory to initiate the connection.</p>
+<p>Android Open Accessory (AOA) support allows external USB hardware
+(Android USB accessories) to interact with Android-powered devices in
+<em>accessory mode</em>. When an Android-powered powered device is in
+accessory mode, the connected accessory acts as the USB host (powers the bus and
+enumerates devices) and the Android-powered device acts as the USB accessory.
+</p>
+<p>Android USB accessories are designed to attach to Android-powered devices.
+Such accessories adhere to AOA, enabling them to detect Android-powered devices
+that support accessory mode, and must provide 500mA at 5V for charging power.
+Some previously-released Android-powered devices are capable of acting only
+as a USB device and cannot initiate connections with external USB devices. AOA
+support overcomes this limitation, enabling you to build accessories that can
+initiate connections and interact with an assortment of Android-powered devices.
+</p>
-<p><strong>Note:</strong> Accessory mode is ultimately dependent on the device's hardware and not all devices
-support accessory mode. Devices that support accessory mode can be filtered using a <code><uses-feature></code>
-element in your corresponding application's Android manifest. For more information, see the
-<a href="http://developer.android.com/guide/topics/connectivity/usb/accessory.html#manifest">USB Accessory</a>
-developer guide.</p>
-
+<p class="note"><strong>Note:</strong> Accessory mode is dependent on device
+hardware; not all devices support accessory mode. Devices that support accessory
+mode can be filtered using a <code><uses-feature></code> element in the
+corresponding application's Android manifest. For details, see the
+<a href="http://developer.android.com/guide/topics/connectivity/usb/accessory.html#manifest">USB
+Accessory</a> developer guide.</p>
-<p>Android Open Accessory support is included in Android 3.1 (API Level 12) and higher, and supported
-through an <a href="https://developers.google.com/android/add-ons/google-apis/">Add-On Library</a> in Android
-2.3.4 (API Level 10) and higher.</p>
-
-
+<p>AOA has two versions that support different types of communication:</p>
+<ul>
+<li><strong>AOAv1</strong>. Supports generic accessory communication and adb
+debugging. Available in Android 3.1 (API Level 12) and higher and supported
+through an
+<a href="https://developers.google.com/android/add-ons/google-apis/">Add-On
+Library</a> in Android 2.3.4 (API Level 10) and higher.</li>
+<li><strong>AOAv2</strong>. Supports audio streaming and human interface
+device (HID) capabilities. Available in Android 4.1 (API Level 16).</li>
+</ul>
\ No newline at end of file
diff --git a/src/compatibility/android-cdd.html b/src/compatibility/android-cdd.html
index 7750c7e..c24908a 100644
--- a/src/compatibility/android-cdd.html
+++ b/src/compatibility/android-cdd.html
@@ -96,6 +96,12 @@
<p class="toc_h2"><a href="#3_9_device_administration">3.9. Device Administration</a></p>
+<p class="toc_h3"><a href="#3_9_1_device_provisioning">3.9.1 Device Provisioning</a></p>
+
+<p class="toc_h4"><a href="#3_9_1_2_device_owner_provisioning">3.9.1.1 Device Owner provisioning</a></p>
+
+<p class="toc_h4"><a href="#3_9_1_2_managed_profile_provisioning">3.9.1.2 Managed profile provisioning</a></p>
+
<p class="toc_h2"><a href="#3_10_accessibility">3.10. Accessibility</a></p>
<p class="toc_h2"><a href="#3_11_text-to-speech">3.11. Text-to-Speech</a></p>
@@ -710,7 +716,8 @@
</tr>
<tr>
<td>SERIAL</td>
- <td>A hardware serial number, which MUST be available. The value of this field MUST
+ <td>A hardware serial number, which MUST be available and unique across
+devices with the same MODEL and MANUFACTURER. The value of this field MUST
be encodable as 7-bit ASCII and match the regular expression “^([a-zA-Z0-9]{6,20})$”.</td>
</tr>
<tr>
@@ -1486,7 +1493,6 @@
<h2 id="3_9_device_administration">3.9. Device Administration</h2>
-
<p>Android includes features that allow security-aware applications to perform
device administration functions at the system level, such as enforcing password
policies or performing remote wipe, through the Android Device Administration
@@ -1499,9 +1505,40 @@
[<a href="http://developer.android.com/guide/topics/admin/device-admin.html">Resources, 39</a>]
and report the platform feature android.software.device_admin.</p>
-<p>Device implementations MAY have a preinstalled application performing device
-administration functions but this application MUST NOT be set out-of-the box as
-the default Device Owner app [<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)">Resources, 41</a>].</p>
+<h3 id="3_9_1_device_provisioning">3.9.1 Device Provisioning</h3>
+<h4 id="3_9_1_1_device_owner_provisioning">3.9.1.1 Device owner provisioning</h4>
+<p>If a device implementation declares the android.software.device_admin feature,
+the out of box setup flow MUST make it possible to enroll a Device Policy
+Controller (DPC) application as the Device Owner app
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)">
+Resources, XX</a>]. Device implementations MAY have a preinstalled application
+performing device administration functions but this application MUST NOT be set
+as the Device Owner app without explicit consent or action from the user or the
+administrator of the device.</p>
+
+<p>The device owner provisioning process (the flow initiated by
+android.app.action.PROVISION_MANAGED_DEVICE
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE">
+Resources, XX</a>]) user experience MUST align with the AOSP implementation</p>
+
+<p>If the device implementation reports android.hardware.nfc, it MUST have NFC
+enabled, even during the out-of-box setup flow, in order to allow for NFC
+provisioning of Device owners
+<a href="https://source.android.com/devices/tech/admin/provision.html#device_owner_provisioning_via_nfc">[Resources, XX]</a>.
+</p>
+
+<h4 id="3_9_1_2_managed_profile_provisioning">3.9.1.2 Managed profile provisioning</h4>
+<p>If a device implementation declares the android.software.managed_users,
+it MUST be possible to enroll a Device Policy Controller (DPC) application
+as the owner of a new Managed Profile
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProfileOwnerApp(java.lang.String)">
+Resources, XX</a>]</p>
+
+<p>The managed profile provisioning process (the flow initiated by
+android.app.action.PROVISION_MANAGED_PROFILE
+[<a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">
+Resources, XX</a>]) user experience MUST align with the AOSP implementation
+</p>
<h2 id="3_10_accessibility">3.10. Accessibility</h2>
@@ -2421,14 +2458,7 @@
</li>
<li>
-The USB host mode MUST implement the USB audio class and handle concurrent input/output with
-a USB audio class-compliant peripheral having the following minimum capabilities:
-<ul>
-<li>4-channel input</li>
-<li>4-channel output</li>
-<li>24-bit depth PCM</li>
-<li>96 kHz sample rate</li>
-</ul>
+The USB host mode MUST implement the USB audio class.
</li>
<li>
@@ -4356,7 +4386,7 @@
stretching algorithm MUST be cryptographically bound to that keystore. The
encryption key MUST NOT be sent off the device (even when wrapped with the user
passcode and/or hardware bound key). The upstream Android Open Source project
-provides a preferred implementation of this feature based on the linux kernel
+provides a preferred implementation of this feature based on the Linux kernel
feature dm-crypt.</p>
<h2 id="9_10_verified_boot">9.10. Verified Boot</h2>
@@ -4368,20 +4398,22 @@
<ul>
<li>Declare the platform feature flag android.software.verified_boot</li>
<li>Perform verification on every boot sequence</li>
-<li>Start verification from a hardware key that is the root of trust, and go
-all the way up to the system partition</li>
+<li>Start verification from an immutable hardware key that is the root of trust,
+and go all the way up to the system partition</li>
<li>Implement each stage of verification to check the integrity and authenticity
of all the bytes in the next stage before executing the code in the next stage</li>
<li>Use verification algorithms as strong as current recommendations
from NIST for hashing algorithms (SHA-256) and public key sizes (RSA-2048)</li>
</ul>
-<p>Device implementations SHOULD support verified boot for device integrity.
-While this requirement is SHOULD for this version of the Android platform,
-it is <strong>strongly RECOMMENDED</strong> as we expect this to change to MUST
-in future versions of Android. The upstream Android Open Source Project provides
-a preferred implementation of this feature based on the linux kernel feature dm-verity.
-</p>
+<p>The upstream Android Open Source Project provides a preferred implementation of this
+feature based on the Linux kernel feature dm-verity.</p>
+
+<p>Starting from Android 6.0, device implementations with Advanced Encryption Standard (AES)
+crypto perfomance above 50MiB/seconds MUST support verified boot for device integrity.
+If a device implementation is already launched without supporting verified boot on an earlier
+version of Android, such a device can not add support for this feature with a system software
+update and thus are exempted from the requirement.</p>
<h1 id="10_software_compatibility_testing">10. Software Compatibility Testing</h1>
@@ -4715,6 +4747,19 @@
<p>41. Android Device Owner App:</p>
<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp(java.lang.String)</a></p>
+<p>XX. Android Device Owner Provisioning Flow:</p>
+
+<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE</a></p>
+<p>XX. Device Owner Provisioning via NFC:</p>
+
+<p><a href="https://source.android.com/devices/tech/admin/provision.html#device_owner_provisioning_via_nfc">https://source.android.com/devices/tech/admin/provision.html#device_owner_provisioning_via_nfc</a></p>
+<p>XX. Android Managed Profile Provisioning flow:</p>
+
+<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE</a></p>
+
+<p>XX. Android Profile Owner App:</p>
+
+<p><a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProfileOwnerApp(java.lang.String)">http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProfileOwnerApp(java.lang.String)</a></p>
<p>42. Android Accessibility Service APIs: <a href="http://developer.android.com/reference/android/accessibilityservice/AccessibilityService.html">http://developer.android.com/reference/android/accessibilityservice/AccessibilityService.html</a></p>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 8a730cb..9184b0b 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -192,6 +192,7 @@
</a>
</div>
<ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/config/carrier.html">Carrier Customization</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/filesystem.html">File System</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/kernel.html">Kernel</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/low-ram.html">Low RAM</a></li>
@@ -309,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/config/carrier.jd b/src/devices/tech/config/carrier.jd
new file mode 100644
index 0000000..51261ff
--- /dev/null
+++ b/src/devices/tech/config/carrier.jd
@@ -0,0 +1,236 @@
+page.title=Carrier Configuration
+@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>
+
+<p>The Android 6.0 Marshmallow release introduces a capability for privileged
+applications to provide carrier-specific configuration to the platform. This
+functionality, based on the <a href="uicc.html">UICC carrier privilege
+functionality</a> introduced in Android 5.1 (Lollipop MR1), will allow carrier
+configuration to be moved away from the static configuration overlays and give
+carriers and OEMs the ability to dynamically provide carrier configuration to
+the platform through a defined interface.</p>
+
+<p>A properly signed carrier app can either be preloaded in the system image,
+installed automatically, or manually installed through an app store. The app
+will be queried by the platform to provide configuration for settings
+including:</p>
+
+<ul>
+ <li>Roaming/Non-roaming networks
+ <li>Visual Voicemail
+ <li>SMS/MMS network settings
+ <li>VoLTE/IMS configurations
+</ul>
+
+<p class="note"><strong>Note</strong>: This app must be signed with the
+certificate that has a matching signature to one on the SIM. See the <a
+href="#how_privilege_is_granted_to_a_carrier_app">How is privilege granted to a
+Carrier App</a> section for details.</p>
+
+<p>The determination of what values to return is entirely up to the Carrier App
+and can be dynamic based on detailed information passed to the app via the
+platform. </p>
+
+<p>The key benefits of this approach are:</p>
+
+<ul>
+ <li><strong>Dynamic configuration</strong> - Support for concepts like
+non-MCCMNC derived configuration, for example
+mobile virtual network operators (MVNOs) or customer opt in to extra services
+ <li><strong>Support for devices sold through any channel</strong> - e.g. an
+open market phone can be automatically configured with the right
+settings by downloading an app from an app store.
+ <li><strong>Security</strong> - Privilege to provide this configuration is
+given only to applications signed by the carrier
+ <li><strong>Defined API</strong> - Previously this configuration was stored
+mostly in internal XML overlays within the framework and not through a public
+API. The carrier config API in Android 6.0 is public and well defined.
+</ul>
+
+<h2 id=how_it_works>How it works</h2>
+
+<h3 id=loading_the_config>Loading the config</h3>
+
+<p>The carrier configuration supplied by this feature is a set of key-value pairs
+that change various telephony-related behaviors in the platform.</p>
+
+<p>The set of values for a particular device is determined by querying the
+following components in order:</p>
+
+<ol>
+ <li>The Carrier App (although this is technically optional, it is the recommended
+location for additional configuration beyond what exists in the Android Open
+Source Project - AOSP)
+ <li>The Platform Config App bundled with the system image
+ <li>Default values, hardcoded into the framework (equivalent to the behavior prior
+to M)
+</ol>
+
+<p class="caution"><strong>Important</strong>: If a value for a particular key
+is returned at any stage, the first value found takes precedence over the
+further stages.</p>
+
+<h4 id=the_platform_config_app>The Platform Config App</h4>
+
+<p>A generic Platform Config App is bundled with the system image that can supply
+values for any variables the regular Carrier App does not. The platform config
+app can be found (in M) in: <code>packages/apps/CarrierConfig</code></p>
+
+<p>This app’s purpose is to provide some per-network configuration when a Carrier
+App is not installed, and carriers/OEMs should make only minimal changes to it
+in their own images. Instead carriers should provide the separate Carrier App
+for carrier customization, allowing updates to be distributed via avenues such
+as app stores.</p>
+
+<h4 id=how_privilege_is_granted_to_a_carrier_app>How privilege is granted to a Carrier App</h4>
+
+<p>The Carrier App in question must be signed with the same certificate found on
+the SIM card, as documented in <a href="uicc.html">UICC Carrier Privileges</a>.</p>
+
+<h4 id=what_information_is_passed_to_the_carrier_app>What information is passed to the Carrier App</h4>
+
+<p>The Carrier App is supplied with the following values, enabling it to make a
+dynamic decision as to what values to return:</p>
+
+<ul>
+ <li>MCC
+ <li>MNC
+ <li>SPN
+ <li>IMSI
+ <li>GID1
+ <li>GID2
+</ul>
+
+<h4 id=when_loading_the_carrier_config_occurs>When loading the carrier config occurs</h4>
+
+<p>The building of the list of key value pairs occurs:</p>
+
+<ul>
+ <li>When the SIM is loaded (boot, or SIM hot swap)
+ <li>When the Carrier app manually triggers a reload
+ <li>When the Carrier app gets updated
+</ul>
+
+<p>See the <a
+href="http://developer.android.com/reference/android/service/carrier/CarrierService.html#onLoadConfig(android.service.carrier.CarrierIdentifier)">android.service.carrier.CarrierService#onLoadConfig()</a>
+reference for more details.</p>
+
+<p class="note"><strong>Note</strong>: The platform caches carrier
+configuration bundles and loads from the cache for SIM state changes. This is
+to speed up boot and SIM hot swap. It is assumed that without a package update
+or an explicit <code>notifyConfigChangedForSubId</code>, the config bundle has
+not been modified.</p>
+
+<h3 id=using_the_config>Using the config</h3>
+
+<p>Once the configuration has been built, the values contained within it are used
+to set various values of system configuration, including:</p>
+
+<ul>
+ <li>Internal framework telephony settings
+ <li>SDK-returned configuration values, e.g. in SmsManager
+ <li>App settings like VVM connection values in the Dialer
+</ul>
+
+<h3 id=configuration_keys>Configuration keys</h3>
+
+<p>The list of keys is defined as part of the public SDK in <code><a
+href="http://developer.android.com/reference/android/telephony/CarrierConfigManager.html">android.telephony.CarrierConfigManager</a></code>
+and cannot change within the same API level. See the table below for a summary of keys.</p>
+
+<h2 id=how_to_build_your_application>How to build your application</h2>
+
+<h3 id=create_your_application>Create your application</h3>
+
+<p>Your application must target the Android 6.0 API level (23).</p>
+
+<h3 id=declare_a_class_that_overrides_android_service_carrier_carrierservice>Declare a class that overrides android.service.carrier.CarrierService</h3>
+
+<ol>
+ <li>Override <code>onLoadConfig</code> to return the values you wish to
+supply based on the <code>service.carrier.CarrierIdentifier</code> object
+passed.
+ <li>Add logic to call <code>notifyConfigChangedForSubId</code> in scenarios
+where carrier configuration may change over time (e.g. when the
+user adds extra services to their account)
+</ol>
+
+<p>An example is below:</p>
+
+<pre>
+public class SampleCarrierConfigService extends CarrierService {
+
+ private static final String TAG = "SampleCarrierConfigService";
+
+ public SampleCarrierConfigService() {
+ Log.d(TAG, "Service created");
+ }
+
+ @Override
+ public PersistableBundle onLoadConfig(CarrierIdentifier id) {
+ Log.d(TAG, "Config being fetched");
+ PersistableBundle config = new PersistableBundle();
+ config.putBoolean(
+ CarrierConfigManager.KEY_CARRIER_VOLTE_AVAILABLE_BOOL, true);
+ config.putBoolean(
+ CarrierConfigManager.KEY_CARRIER_VOLTE_TTY_SUPPORTED_BOOL, false);
+ config.putInt(CarrierConfigManager.KEY_VOLTE_REPLACEMENT_RAT_INT, 6);
+ // Check CarrierIdentifier and add more config if needed…
+ return config;
+ }
+}
+</pre>
+
+
+<p>Please see the <a
+href="https://developer.android.com/reference/android/service/carrier/CarrierService.html">android.service.carrier.CarrierService</a> reference on developer.android.com for more details.</p>
+
+<h3 id=name_the_class_in_your_manifest>Name the class in your manifest</h3>
+
+<p>An example is below:</p>
+
+<pre>
+<service android:name=".SampleCarrierConfigService"
+android:label="@string/service_name"
+android:permission="android.permission.BIND_CARRIER_SERVICES">
+ <intent-filter>
+ <action android:name="android.service.carrier.ConfigService"/></intent-filter>
+</service>
+</pre>
+
+<h3 id=sign_app_with_same_certificate_on_sim>Sign app with same certificate on SIM</h3>
+
+<p>See <a href="uicc.html">UICC Carrier Privileges</a> for the requirements.</p>
+
+<h2 id=testing_your_application>Testing your application</h2>
+
+<p>Once you have built your configuration application, you can test your code
+with:</p>
+
+<ul>
+ <li>A SIM containing a valid certificate signature
+ <li>A device running Android 6.0 and later, for example a Nexus device
+</ul>
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 0000000..e5af5e4
--- /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/authentication/gatekeeper.jd b/src/devices/tech/security/authentication/gatekeeper.jd
new file mode 100644
index 0000000..1a7fdb3
--- /dev/null
+++ b/src/devices/tech/security/authentication/gatekeeper.jd
@@ -0,0 +1,193 @@
+page.title=Gatekeeper
+@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>The Gatekeeper subsystem performs device pattern/password authentication in a
+Trusted Execution Environment (TEE). Gatekeeper enrolls and verifies passwords
+via an HMAC with a hardware-backed secret key. Additionally, Gatekeeper
+throttles consecutive failed verification attempts and must refuse to service
+requests based on a given timeout and a given number of consecutive failed
+attempts.</p>
+
+<p>When users verify their passwords, Gatekeeper uses the TEE-derived shared
+secret to sign an authentication attestation to
+send to <a href="keymaster.html">Keymaster</a>. That is, a
+Gatekeeper attestation notifies Keymaster that authentication-bound keys (for
+example, keys that apps have created) can be released for use by apps.</p>
+link
+<h2 id=architecture>Architecture </h2>
+
+<p>Gatekeeper involves three main components:</p>
+
+<ul>
+ <li><strong>gatekeeperd (Gatekeeper daemon)</strong>.
+ A C++ binder service containing platform-independent logic and corresponding
+to the <code>GateKeeperService</code> Java interface.
+ <li><strong>Gatekeeper Hardware Abstraction Layer (HAL)</strong>.
+ The HAL interface in <code>hardware/libhardware/include/hardware/gatekeeper.h</code>,
+ and the implementing module.
+ <li><strong>Gatekeeper (TEE)</strong>.
+ The TEE counterpart of <code>gatekeeperd</code>. A TEE-based implementation of Gatekeeper.
+</ul>
+
+<p>To implement Gatekeeper:</p>
+
+<ul>
+ <li>Implement the Gatekeeper HAL, specifically the functions in <code>gatekeeper.h</code>
+ (<code>hardware/libhardware/include/hardware/gatekeeper.h</code>). See <a href="#hal_implementation">HAL Implementation</a>.
+ <li>Implement the TEE-specific Gatekeeper component, in part based on the following
+header file: <code>system/gatekeeper/include/gatekeeper/gatekeeper.h</code>. This
+header file includes pure virtual functions for creating and accessing
+keys, as well as for computing signatures.
+See <a href="#trusty_and_other_implementations">Trusty and other implementations</a>.
+</ul>
+
+<p>As shown in the following diagram, the LockSettingsService makes a request (via
+Binder) that reaches the <code>gatekeeperd</code> daemon in the Android OS. The <code>gatekeeperd</code>
+daemon makes a request that reaches its counterpart (Gatekeeper) in the TEE.</p>
+
+<img src="../images/gatekeeper-flow.png" alt="Gatekeeper flow" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> High-level data flow for authentication by GateKeeper</p>
+
+<p>The <code>gatekeeperd</code> daemon gives the Android framework APIs access to the HAL, and
+participates in reporting device <a href="index.html">authentications</a> to Keymaster.
+The <code>gatekeeperd</code> daemon runs in its own process, separate from the system
+server.</p>
+
+<h2 id=hal_implementation>HAL Implementation</h2>
+
+<p>The <code>gatekeeperd</code> daemon uses the HAL to interact
+with the <code>gatekeeperd</code> daemon's TEE
+counterpart for password authentication. The HAL implementation must be able to
+sign (enroll) and verify blobs. All implementations are expected to adhere to
+the standard format for the authentication token (AuthToken) generated on each
+successful password verification. The contents and semantics of the AuthToken
+are described in <a href="index.html">Authentication</a>.</p>
+
+<p>Specifically, an implementation of the <code>gatekeeper.h</code> header file (in the
+<code>hardware/libhardware/include/hardware</code> folder) needs to implement the
+<code>enroll</code> and <code>verify</code> functions.</p>
+
+<p>The <code>enroll</code> function takes a password blob, signs it, and returns the signature
+as a handle. The returned blob (from a call to <code>enroll</code>) must have the structure
+shown in <code>system/gatekeeper/include/gatekeeper/password_handle.h</code>.</p>
+
+<p>The <code>verify</code> function needs to compare the signature produced by the provided password and
+ensure that it matches the enrolled password handle.</p>
+
+<p>The key used to enroll and verify must never change, and should be re-derivable
+at every device boot.</p>
+
+<h2 id=trusty_and_other_implementations>Trusty and other implementations</h2>
+
+<p>The Trusty operating system is Google's open source trusted OS for TEE
+environments. It contains an approved implementation of GateKeeper. However,
+<strong>any TEE OS</strong> can be used for the implementation of Gatekeeper.
+The TEE <strong>must</strong> have access to a hardware-backed key as well as a secure,
+monotonic clock <strong>that ticks in suspend</strong>.</p>
+
+<p>Trusty uses an internal IPC system to communicate a shared secret directly
+between Keymaster and the Trusty implementation of Gatekeeper ("Trusty
+Gatekeeper"). This shared secret is used for signing AuthTokens that will be
+sent to Keymaster, providing attestations of password verification. Trusty
+Gatekeeper requests the key from Keymaster for each use and does not persist
+or cache the value. Implementations are free to share this secret in any way
+that does not compromise security.</p>
+
+<p>The HMAC key, used to enroll and verify passwords, is derived and kept solely
+in GateKeeper.</p>
+
+<p>The Android tree provides a generic C++ implementation of GateKeeper, requiring
+only the addition of device-specific routines to be complete. To implement a
+TEE Gatekeeper with device-specific code for your TEE, please refer to the
+functions and comments in the following file:</p>
+<pre>
+system/gatekeeper/include/gatekeeper/gatekeeper.h
+</pre>
+
+<p>For the TEE GateKeeper, the primary responsibilities of a compliant
+implementation are:</p>
+
+<ul>
+ <li>Adherence to the Gatekeeper HAL
+ <li>Returned AuthTokens must be formatted according to the AuthToken specification
+(described in <a href="index.html">Authentication</a>)
+ <li>The TEE Gatekeeper must be able to share an HMAC key with Keymaster, either by
+requesting the key through a TEE IPC on demand or maintaining a valid cache of
+the value at all times
+</ul>
+
+<h2 id=user_sids>User SIDs</h2>
+
+<p>A User Secure ID (User SID) is the TEE representation of a user.
+The User SID has no strong connection to an Android user ID.</p>
+
+<p>A User SID is generated with a cryptographic
+PRNG whenever a user enrolls a new password without providing a previous one.
+This is known as an "untrusted" re-enroll.
+A "trusted" re-enroll occurs when a user provides a valid, previous password.
+In this case, the User SID is migrated to the new password handle,
+conserving the keys that were bound to it.
+The Android framework does not allow for an "untrusted" re-enroll under regular circumstances.</p>
+
+<p>The User SID is HMAC'ed along with the password in the password handle when the
+password is enrolled.</p>
+
+<p>User SIDs are written into the AuthToken returned by the <code>verify</code>
+function and associated to all authentication-bound Keymaster keys. For
+information about the AuthToken format and Keymaster, see
+<a href="index.html">Authentication</a>.
+Since an untrusted call to the <code>enroll</code> function
+will change the User SID, the call will render the keys bound to that password useless.</p>
+
+<p>Attackers can change the password for the device if they control the Android
+OS, but they will destroy root-protected, sensitive keys in the process.</p>
+
+<h2 id=request_throttling>Request throttling</h2>
+
+<p>GateKeeper must be able to securely throttle brute-force attempts on a user
+credential. As shown in the <code>gatekeeper.h</code>
+file (in <code>hardware/libhardware/include/hardware</code>),
+the HAL provides for returning a timeout in milliseconds. The timeout
+informs the client not to call GateKeeper again until after the timeout has
+elapsed. GateKeeper should not service requests if there is a pending timeout.</p>
+
+<p>GateKeeper must write a failure counter before verifying a user password. If
+the password verification succeeds, the failure counter should be cleared. This
+prevents attacks that prevent throttling by disabling the embedded MMC (eMMC)
+after issuing a <code>verify</code> call. The <code>enroll</code> function also verifies
+the user password (if provided) and so must be
+throttled in the same way.</p>
+
+<p>If supported by the device, it is highly recommended that the failure counter
+be written to secure storage. If the device does not support
+file-based encryption, or if secure storage is too slow, implementations may
+use RPMB directly.</p>
+
+
+
+
diff --git a/src/devices/tech/security/authentication/index.jd b/src/devices/tech/security/authentication/index.jd
index 66560a7..a47873b 100644
--- a/src/devices/tech/security/authentication/index.jd
+++ b/src/devices/tech/security/authentication/index.jd
@@ -46,7 +46,7 @@
<li><strong>The keystore service and Keymaster.</strong> Cryptographic services,
including hardware-backed cryptography for key storage,
which might include a Trusted Execution Environment (TEE).</li>
- <li><strong>Gatekeeper</strong>. Components for PIN, pattern, and password authentication.</li>
+ <li><a href="gatekeeper.html"><strong>Gatekeeper</strong></a>. Components for PIN, pattern, and password authentication.</li>
<li><strong>Fingerprint.</strong> Components for fingerprint authentication.</li>
</ul>
diff --git a/src/devices/tech/security/authentication/keymaster.jd b/src/devices/tech/security/authentication/keymaster.jd
new file mode 100644
index 0000000..8febf76
--- /dev/null
+++ b/src/devices/tech/security/authentication/keymaster.jd
@@ -0,0 +1,100 @@
+page.title=Keymaster
+@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>
+
+<p>The availability of a trusted execution environment in a system on a chip (SoC)
+offers an opportunity for Android devices to provide hardware-backed, strong
+security services to the Android OS, to platform services, and even to
+third-party apps.</p>
+
+<p>Keymaster has been <a href="km-features.html">significantly enhanced</a>
+in Android 6.0 with the addition of symmetric cryptographic primitives,
+AES and HMAC, and the addition of an access control
+system for hardware-backed keys. Access controls are specified during key
+generation and enforced for the lifetime of the key. Keys can be restricted to
+be usable only after the user has authenticated, only at a specific usage
+velocity, and only for specified purposes or with specified cryptographic
+parameters. For more information, please see
+the <a href="km-implementer-ref.html">Implementer's Reference</a>.</p>
+
+<p>Before Keymaster 1.0, Android already had a simple, hardware-backed crypto
+services API: Keymaster versions 0.2 and 0.3, which provided only digital
+signing and verification operations, plus generation of
+asymmetric signing key pairs. This is already
+implemented on many devices, but there are many security goals that cannot
+easily be achieved with only a signature API. The intent of Keymaster 1.0 is to
+extend the Keymaster API to provide a broader range of capabilities.</p>
+
+<h2 id=goals>Goals</h2>
+
+<p>The goal of the Keymaster API is to provide a basic but adequate set of
+cryptographic primitives to allow the implementation of protocols using
+access-controlled, hardware-backed keys.</p>
+
+<p>In addition to expanding the range of cryptographic primitives, Keymaster v1.0
+adds the following:</p>
+
+<ul>
+ <li>A usage control scheme to allow key usage to be limited, to mitigate the risk
+of security compromise due to misuse of keys
+ <li>An access control scheme to enable restriction of keys to specified users,
+clients, and a defined time range
+</ul>
+
+<h2 id=architecture>Architecture</h2>
+
+<p>The Keymaster API is a Hardware Abstraction Layer module, which is a
+dynamically-loaded library. Implementations must not
+perform any sensitive operations in user space, or even in kernel space.
+Sensitive operations are delegated to a secure processor reached through some
+kernel interface. The resulting architecture looks something like the
+following:</p>
+
+<img src="../images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> Access to Keymaster</p>
+
+<p>Within an Android device, the "client" actually consists of multiple layers
+(e.g. app, framework, keystore daemon), but that can be ignored for the
+purposes of this document. This means that the described API is low-level, used
+by platform-internal components, and not exposed to app developers. The
+higher-level API, for API level 23, is described on
+the <a href="http://developer.android.com/reference/java/security/KeyStore.html">Android Developer site</a>.</p>
+
+<p>The purpose of the <code>libkeymaster</code> library is not to implement the
+security-sensitive algorithms but only to
+marshal and unmarshal requests to the secure world. The wire format is
+implementation-defined.</p>
+
+<h2 id=compatibility_with_previous_versions>Compatibility with previous versions</h2>
+
+<p>The Keymaster v1.0 API is completely incompatible with the previously-released
+APIs, e.g. Keymaster v0.2 and v0.3.
+To facilitate interoperability on pre-Marshmallow devices that launched
+with the older Keymaster APIs, Keystore provides an adapter that provides
+the 1.0 API implemented with calls to the existing hardware library. The result
+cannot provide the full range of functionality in the
+1.0 API. In particular, it will only support RSA and ECDSA algorithms, and all
+of the key authorization enforcement will be performed by the adapter, in the
+non-secure world.</p>
diff --git a/src/devices/tech/security/authentication/km-features.jd b/src/devices/tech/security/authentication/km-features.jd
new file mode 100644
index 0000000..2b469c9
--- /dev/null
+++ b/src/devices/tech/security/authentication/km-features.jd
@@ -0,0 +1,412 @@
+page.title=Features
+@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>
+
+<p>This page contains information about the features of <a href="keymaster.html">Keymaster</a> 1.0.</p>
+
+<h2 id=cryptographic_primitives>Cryptographic primitives</h2>
+
+<p>The <code>libkeymaster</code> library and Keymaster provide the following categories of operations:</p>
+
+<ul>
+ <li>Key generation
+ <li>Import and export of asymmetric keys (no key wrapping)
+ <li>Import of raw symmetric keys (again, no wrapping)
+ <li>Asymmetric encryption and decryption with appropriate padding modes
+ <li>Asymmetric signing and verification with digesting and appropriate padding
+modes
+ <li>Symmetric encryption and decryption in appropriate modes, including an AEAD
+mode
+ <li>Generation and verification of symmetric message authentication codes
+</ul>
+
+<p>Within each category, <code>libkeymaster</code> provides a mechanism for
+discovering the available options (algorithms,
+modes, etc.). But we also specify at least one required option, to ensure that
+client software can depend on the presence of the required primitives.</p>
+
+<p>Protocol elements, such as purpose, mode and padding, as well
+as <a href="#key_access_control">access control constraints</a>,
+must be specified when keys are generated or imported and are permanently
+bound to the key, ensuring the key cannot be used in any other way.</p>
+
+<p>In addition to the list above, there is one more service that Keymaster
+implementations must provide but which is not exposed as an API: Random number
+generation. This is used internally for generation of keys, Initialization
+Vectors (IVs), random padding and other elements of secure protocols that
+require randomness.</p>
+
+<h2 id=required_primitives>Required primitives</h2>
+
+<p>All implementations must provide:</p>
+
+<ul>
+ <li><a href="http://en.wikipedia.org/wiki/RSA_(cryptosystem)">RSA</a>
+ <ul>
+ <li>2048, 3072 and 4096-bit key support are required
+ <li>Support for public exponent F4 (2^16+1)
+ <li>Required padding modes for RSA signing are:
+ <ul>
+ <li>No padding (deprecated, will be removed in the future)
+ <li>RSASSA-PSS (<code>KM_PAD_RSA_PSS</code>)
+ <li>RSASSA-PKCS1-v1_5 (<code>KM_PAD_RSA_PKCS1_1_5_SIGN</code>)
+ </ul>
+ <li>Required digest modes for RSA signing are:
+ <ul>
+ <li>No digest (deprecated, will be removed in the future)
+ <li>SHA-256
+ </ul>
+ <li>Required padding modes for RSA encryption/decryption are:
+ <ul>
+ <li>RSAES-OAEP (<code>KM_PAD_RSA_OAEP</code>)
+ <li>RSAES-PKCS1-v1_5 (<code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code>)
+ </ul>
+ <li>Unpadded RSA encryption must not be supported
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Elliptic_Curve_DSA">ECDSA</a>
+ <ul>
+ <li>224, 256, 384 and 521-bit key support are required, using the NIST P-224,
+P-256, P-384 and P-521 curves, respectively
+ <li>Required digest modes for ECDSA are:
+ <ul>
+ <li>No digest (deprecated, will be removed in the future)
+ <li>SHA-256
+ </ul>
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Advanced_Encryption_Standard">AES</a>
+ <ul>
+ <li>128 and 256-bit keys are required
+ <li><a href="http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher-block_chaining_.28CBC.29">CBC</a>,
+ CTR, ECB and and GCM. The GCM implementation must not allow the use of tags
+smaller than 96 bits or nonce lengths other than 96 bits.
+ <li>Padding modes <code>KM_PAD_NONE</code> and <code>KM_PAD_PKCS7</code> must
+ be supported for CBC and ECB modes. With no padding, CBC or ECB mode
+encryption must fail if the input isn't a multiple of the block size.
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Hash-based_message_authentication_code">HMAC</a>
+ <a href="http://en.wikipedia.org/wiki/SHA-2">SHA-256</a>, with any key size up to at least 32 bytes.
+</ul>
+</ul>
+
+<p>SHA1 and the other members of the SHA2 family (SHA-224, SHA384 and SHA512) are
+strongly recommended, but not required. Keystore will provide them in software
+if the hardware Keymaster implementation doesn't provide them.</p>
+
+<p>Some primitives are also recommended for interoperability with other systems:</p>
+
+<ul>
+ <li>Smaller key sizes for RSA
+ <li>Arbitrary public exponents for RSA
+</ul>
+
+<h2 id=key_access_control>Key access control</h2>
+
+<p>Hardware-based keys that can never be extracted from the device don't provide
+much security if an attacker can use them at will (though they're more secure
+than keys which <em>can</em> be exfiltrated). Thus, it's crucial that Keymaster enforce access controls.</p>
+
+<p>Access controls are defined as an "authorization list" of tag/value pairs.
+Authorization tags are 32-bit integers and the values are a variety of types.
+Some tags may be repeated to specify multiple values. Whether a tag may be
+repeated is specified in the documentation for the tag. When a key is created,
+the caller specifies an authorization list. The Keymaster implementation will
+modify the list to specify some additional information, such as whether the key
+has rollback protection, and return a "final" authorization list, encoded into
+the returned key blob. Any attempt to use the key for any cryptographic
+operation must fail if the final authorization list is modified.</p>
+
+<p>The set of possible tags is defined in the enumeration <code>keymaster_authorization_tag_t</code> and
+the set must be permanently fixed (though it can be extended).
+Names are prefixed with <code>KM_TAG_</code>. The top
+four bits of tag IDs are used to indicate the type.</p>
+
+<p>Possible types include:</p>
+
+<p><strong><code>KM_ENUM</code>:</strong> Many tags' values are defined in enumerations. For example, the possible
+values of <code>KM_TAG_PURPOSE</code> are defined in enum <code>keymaster_purpose_t</code>.</p>
+
+<p><strong><code>KM_ENUM_REP</code></strong>: Same as <code>KM_ENUM</code>, except that the tag may
+be repeated in an authorization list. Repetition
+indicates multiple authorized values. For example, an encryption key will
+likely have <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_DECRYPT</code>.</p>
+
+<p><strong><code>KM_UINT</code>:</strong> 32-bit unsigned integers. Example: <code>KM_TAG_KEY_SIZE</code></p>
+
+<p><strong><code>KM_UINT_REP</code></strong>: Same as <code>KM_UINT</code>, except that the tag may be
+repeated in an authorization list. Repetition indicates multiple authorized values.</p>
+
+<p><strong><code>KM_ULONG</code></strong>: 64-bit unsigned integers. Example: <code>KM_TAG_RSA_PUBLIC_EXPONENT</code></p>
+
+<p><strong><code>KM_ULONG_REP</code></strong>: Same as <code>KM_ULONG</code>, except that the tag may be
+repeated in an authorization list. Repetition
+indicates multiple authorized values.</p>
+
+<p><strong><code>KM_DATE</code></strong>: Date/time values, expressed as milliseconds since January 1, 1970.
+Example: <code>KM_TAG_PRIVKEY_EXPIRE_DATETIME</code></p>
+
+<p><strong><code>KM_BOOL</code></strong>: True or false. A tag of type <code>KM_BOOL</code> is assumed
+to be "false" if the tag is not present and "true" if present. Example: <code>KM_TAG_ROLLBACK_RESISTANT</code></p>
+
+<p><strong><code>KM_BIGNUM</code></strong>: Arbitrary-length integers, expressed as a byte array
+in big-endian order. Example: <code>KM_TAG_RSA_PUBLIC_EXPONENT</code></p>
+
+<p><strong><code>KM_BYTES</code></strong>: A sequence of bytes. Example: <code>KM_TAG_ROOT_OF_TRUST</code></p>
+
+<h3 id=hardware_vs_software_enforcement>Hardware vs. software enforcement</h3>
+
+<p>Not all Keymaster implementations will implement the same features. To support
+a variety of approaches, Keymaster 1.0 distinguishes between secure and
+non-secure world access control enforcement, which we call hardware and
+software enforcement, respectively.</p>
+
+<p>Implementations are required to:</p>
+
+<ul>
+ <li>Enforce exact matching (not enforcement) of all authorizations. Authorization
+lists in key blobs must exactly match the authorizations returned during key
+generation, including ordering. Any mismatch must cause an error diagnostic.
+ <li>Declare the authorizations whose semantic values are enforced.
+</ul>
+
+<p>The API mechanism for declaring hardware-enforced authorizations is in
+the <code>keymaster_key_characteristics_t</code> structure. It divides the authorization
+list into two sub-lists, <code>hw_enforced</code> and <code>sw_enforced</code>. The
+Keymaster implementation is responsible for placing the appropriate
+values in each, based on what it can enforce.</p>
+
+<p>In addition, the keystore daemon will implement software-based enforcement of <em>all</em> authorizations,
+whether they're enforced in hardware or not.</p>
+
+<p>For example, consider a TrustZone-based implementation that does not support
+key expiration. A key with an expiration date may still be created. That key's
+authorization list will include the tag <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> with
+the expiration date. A request to Keymaster for the key characteristics
+will find this tag in the <code>sw_enforced</code> list and the Keymaster implementation will
+not enforce the expiration
+requirement. However, attempts to use the key after expiration will be rejected
+by the keystore daemon.</p>
+
+<p>If the device is then upgraded with a Keymaster implementation that does
+support expiration, then a request for key characteristics will
+find <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> in
+the <code>hw_enforced</code> list, and attempts to use the key after expiration will fail even if the
+keystore is somehow subverted or bypassed.</p>
+
+<h3 id=cryptographic_message_construction_authorizations>Cryptographic message construction authorizations</h3>
+
+<p>The following tags are used to define the cryptographic characteristics of
+operations using the associated key: <code>KM_TAG_ALGORITHM</code>, <code>KM_TAG_KEY_SIZE</code>,
+<code>KM_TAG_BLOCK_MODE</code>, <code>KM_TAG_PADDING</code>, <code>KM_TAG_CALLER_NONCE</code>, and <code>KM_TAG_DIGEST</code></p>
+
+<p><code>KM_TAG_PADDING</code>, <code>KM_TAG_DIGEST</code>, and <code>KM_PAD_BLOCK_MODE</code>
+are repeatable, meaning that multiple values may be associated with a single
+key, and the value to be used will be specified at operation time.</p>
+
+<h3 id=purpose>Purpose</h3>
+
+<p>Keys have an associated set of purposes, expressed as one or more authorization
+entries with tag <code>KM_TAG_PURPOSE</code>, which defines how they can be used. The purposes are:</p>
+
+<ul>
+ <li><code>KM_PURPOSE_ENCRYPT</code>
+ <li><code>KM_PURPOSE_DECRYPT</code>
+ <li><code>KM_PURPOSE_SIGN</code>
+ <li><code>KM_PURPOSE_VERIFY</code>
+</ul>
+
+<p>Any key can have any subset of these purposes. Note that some combinations
+create security problems. For example, an RSA key that can be used to both
+encrypt and to sign allows an attacker who can convince the system to decrypt
+arbitrary data to generate signatures.</p>
+
+<p>Other purposes for keys that may be added in the future include:</p>
+
+<ul>
+ <li>"Derive Key" purpose, for key derivation keys
+ <li>"Attest" purpose, for keys that can generate attestations of the Keymaster
+implementation and/or its environment
+ <li>"Wrap Key" purpose, for keys used to wrap keys for secure import or export
+</ul>
+
+<h3 id=import_and_export>Import and export</h3>
+
+<p>Keymaster supports export of public keys only, in X.509 format, and import of:</p>
+
+<ul>
+ <li>Public and private key pairs in DER-encoded PKCS#8 format, without
+password-based encryption, and
+ <li>Symmetric keys as raw bytes
+</ul>
+
+<p>Future versions will likely expand the import/export options.</p>
+
+<p>To ensure that imported keys can be distinguished from securely-generated
+keys, <code>KM_TAG_ORIGIN</code> is included in the appropriate key
+authorization list. For example, if a key
+was generated in secure hardware, <code>KM_TAG_ORIGIN</code> with
+value <code>KM_ORIGIN_GENERATED</code> will be found in
+the <code>hw_enforced</code> list of the key characteristics, while a key
+that was imported into secure
+hardware will have the value <code>KM_ORIGIN_IMPORTED</code>.</p>
+
+<h3 id=user_authentication>User authentication</h3>
+
+<p>Keymaster does not implement user authentication, but depends on other trusted
+apps which do. For the interface that must be implemented by these apps, see
+the Gatekeeper page.</p>
+
+<p>User authentication requirements are specified via two sets of tags. The first
+set indicate which user can use the key:</p>
+
+<ul>
+ <li><code>KM_TAG_ALL_USERS</code> indicates the key is usable by all users. If
+ present, <code>KM_TAG_USER_ID</code> and <code>KM_TAG_SECURE_USER_ID</code> must not be present.
+ <li><code>KM_TAG_USER_ID</code> has a numeric value specifying the ID of the authorized user.
+ Note that this
+is the Android user ID (for multi-user), not the application UID, and it is
+enforced by non-secure software only. If present, <code>KM_TAG_ALL_USERS</code> must not be present.
+ <li><code>KM_TAG_SECURE_USER_ID</code> has a 64-bit numeric value specifying the secure user ID
+ that must be provided
+in a secure authentication token to unlock use of the key. If repeated, the key
+may be used if any of the values is provided in a secure authentication token.
+</ul>
+
+<p>The second set indicate whether and when the user must be authenticated. If
+neither of these tags is present, but <code>KM_TAG_SECURE_USER_ID</code> is, authentication is
+required for every use of the key.</p>
+
+<ul>
+ <li><code>KM_NO_AUTHENTICATION_REQUIRED</code> indicates no user authentication is required, though
+ the key still may only be
+used by apps running as the user(s) specified by <code>KM_TAG_USER_ID</code>.
+ <li><code>KM_TAG_AUTH_TIMEOUT</code> is a numeric value specifying, in seconds, how fresh the user
+ authentication
+must be to authorize key usage. This applies only to private/secret key
+operations. Public key operations don't require authentication. Timeouts do not
+cross reboots; after a reboot, all keys are "never authenticated." The timeout
+may be set to a large value to indicate that authentication is required once
+per boot (2^32 seconds is ~136 years; presumably Android devices are rebooted
+more often than that).
+</ul>
+
+<h3 id=client_binding>Client binding</h3>
+
+<p>Client binding, the association of a key with a particular client application,
+is done via an optional client ID and some optional client data (<code>KM_TAG_APPLICATION_ID</code>
+and <code>KM_TAG_APPLICATION_DATA</code>, respectively). Keymaster treats these values as opaque blobs,
+only ensuring
+that the same blobs presented during key generation/import are presented for
+every use and are byte-for-byte identical. The client binding data is not
+returned by Keymaster. The caller must know it in order to use the key.</p>
+
+<h3 id=expiration>Expiration</h3>
+
+<p>Keymaster supports restricting key usage by date. Key start of validity and key
+expirations can be associated with a key and Keymaster will refuse to perform
+key operations if the current date/time is outside of the valid range. The key
+validity range is specified with the tags <code>KM_TAG_ACTIVE_DATETIME</code>,
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>, and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code>.
+The distinction between "origination" and "usage" is based on whether the key
+is being used to "originate" a new ciphertext/signature/etc., or to "use" an
+existing ciphertext/signature/etc.</p>
+
+<p>The <code>KM_TAG_ACTIVE_DATETIME</code>, <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>,
+and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code> tags are optional. If the tags are absent, it is
+assumed that the key in
+question can always be used to decrypt/verify messages.</p>
+
+<p>Because wall-clock time is provided by the non-secure world, it's unlikely that
+the expiration-related tags will be in the hardware-enforced list. Hardware
+enforcement of expiry would require that the secure world somehow obtain
+trusted time and data, for example via a challenge response protocol with a
+trusted remote timeserver.</p>
+
+<h3 id=root_of_trust_binding>Root of trust binding</h3>
+
+<p>Keymaster allows keys to be bound to a root of trust, which is a bitstring
+provided to Keymaster during startup, preferably by the bootloader. If
+provided, this bitstring must be cryptographically bound to every key managed
+by Keymaster.</p>
+
+<p>The intent is for the bootloader to pass in the public key, used to verify the
+signature on the boot image, along with the verified boot state (locked or
+unlocked). If the public key is changed to allow a different system image to be
+used or if the verified boot state is changed, then none of the
+Keymaster-protected keys created by the previous system will be usable, unless
+the previous root of trust is restored and a system that is signed by that key
+is booted. The goal is to increase the value of the software-enforced key
+access controls by making it imposSTEM</code>sible for an attacker-installed operating
+system to use Keymaster keys.</p>
+
+<h3 id=standalone_keys>Standalone keys</h3>
+
+<p>Some Keymaster implementations may choose to store key material internally and
+return handles rather than encrypted key material. Or there may be other cases
+in which keys cannot be used until some other non-secure or secure world system
+component is available. The Keymaster 1.0 API allows the caller to request that
+a key be "standalone," via the <code>KM_TAG_STANDALONE</code> tag,
+meaning that no resources other than the blob and the running Keymaster
+system are required. The tags associated with a key may be inspected to see
+whether a key is standalone. At present, only two values are defined:</p>
+
+<ul>
+ <li><code>KM_BLOB_STANDALONE</code>
+ <li><code>KM_BLOB_REQUIRES_FILE_SYSTEM</code>
+</ul>
+
+<h3 id=velocity>Velocity</h3>
+
+<p>When it's created, the maximum usage velocity can be specified
+with <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code>.
+TrustZone implementations will refuse to perform cryptographic operations
+with that key if an operation was performed less
+than <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> seconds earlier.</p>
+
+<p>The simple approach to implementing velocity limits is a table of key IDs and
+last-use timestamps. This table will likely be of limited size, but must
+accommodate at least 16 entries. In the event that the table is full and no
+entries may be updated or discarded, Keymaster implementations must "fail
+safe," preferring to refuse all velocity-limited key operations until one of
+the entries expires. It is acceptable for all entries to expire upon reboot.</p>
+
+<p>Keys can also be limited to <em>n</em> uses per boot with <code>KM_TAG_USES_PER_BOOT</code>.
+This also requires a tracking table, which must accommodate at least four
+keys, and must also fail safe. Note that applications will be unable to create
+per-boot limited keys. This feature will not be exposed through keystore and
+will be reserved for system operations.</p>
+
+<h3 id=random_number_generator_re-seeding>Random number generator re-seeding</h3>
+
+<p>Because Keymaster must generate random numbers for key material and
+Initialization Vectors (IVs), and because hardware random number generators may
+not always be fully trustworthy, Keymaster provides an interface to allow the
+client to provide additional entropy which will be mixed into the random
+numbers generated.</p>
+
+<p>A hardware random-number generator should be used as the primary seed source,
+if available, and the seed data provided through the external API must not be
+the sole source of randomness used for number generation. Further, the mixing
+operation used must ensure that the random output is unpredictable if any one
+of the seed sources is unpredictable.</p>
diff --git a/src/devices/tech/security/authentication/km-implementer-ref.jd b/src/devices/tech/security/authentication/km-implementer-ref.jd
new file mode 100644
index 0000000..9c8c619
--- /dev/null
+++ b/src/devices/tech/security/authentication/km-implementer-ref.jd
@@ -0,0 +1,1229 @@
+page.title=Implementer's Reference
+@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.
+-->
+
+<p>This page provides details to assist implementers of <a href="keymaster.html">Keymaster</a> HALs. It
+covers each tag and each function in the API.</p>
+
+<h2 id=authorization_tags>Authorization tags</h2>
+
+<p>Except as noted in the tag descriptions, all of the tags below are used during
+key generation to specify key characteristics.</p>
+
+<h3 id=km_tag_purpose>KM_TAG_PURPOSE</h3>
+
+<p>Specifies the set of purposes for which the key may be used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_PURPOSE_ENCRYPT = 0,
+ KM_PURPOSE_DECRYPT = 1,
+ KM_PURPOSE_SIGN = 2,
+ KM_PURPOSE_VERIFY = 3,
+} keymaster_purpose_t;
+</pre>
+
+<p>This tag is repeatable; keys may be generated with multiple values, although an
+operation has a single purpose. When the <a href="#begin">begin</a> function is called to
+start an operation, the purpose of the operation is
+specified. If the purpose specified to the operation is not authorized by the
+key, the operation must fail with <code>KM_ERROR_INCOMPATIBLE_PURPOSE</code>.</p>
+
+<h3 id=km_tag_algorithm>KM_TAG_ALGORITHM</h3>
+
+<p>Specifies the cryptographic algorithm with which the key is used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_ALGORITHM_RSA = 1,
+ KM_ALGORITHM_EC = 3,
+ KM_ALGORITHM_AES = 32,
+ KM_ALGORITHM_HMAC = 128,
+} keymaster_algorithm_t;
+</pre>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_key_size>KM_TAG_KEY_SIZE</h3>
+
+<p>Specifies the size, in bits, of the key, measuring in the normal way for the
+key's algorithm. For example, for RSA keys, <code>KM_TAG_KEY_SIZE</code> specifies
+the size of the public modulus. For AES keys it specifies the length
+of the secret key material.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_block_mode>KM_TAG_BLOCK_MODE</h3>
+
+<p>Specifies the block cipher mode(s) with which the key may be used. This tag is
+only relevant to AES keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_MODE_ECB = 1,
+ KM_MODE_CBC = 2,
+ KM_MODE_CTR = 3,
+ KM_MODE_GCM = 32,
+} keymaster_block_mode_t;
+</pre>
+
+<p>This tag is repeatable, and for AES key operations a mode must be specified in
+the <code>additional_params</code> argument of <a href="#begin">begin</a>. If the specified
+mode is not in the modes associated with the key, the
+operation must fail with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
+
+<h3 id=km_tag_digest>KM_TAG_DIGEST</h3>
+
+<p>Specifies the digest algorithms which may be used with the key to perform
+signing and verification operations. This tag is relevant to RSA, ECDSA and
+HMAC keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_DIGEST_NONE = 0,
+ KM_DIGEST_MD5 = 1,
+ KM_DIGEST_SHA1 = 2,
+ KM_DIGEST_SHA_2_224 = 3,
+ KM_DIGEST_SHA_2_256 = 4,
+ KM_DIGEST_SHA_2_384 = 5,
+ KM_DIGEST_SHA_2_512 = 6,
+}
+keymaster_digest_t;
+</pre>
+
+<p>This tag is repeatable. For signing and verification operations a digest must
+be specified in the <code>additional_params</code> argument of <a href="#begin">begin</a>.
+If the specified digest is not in the digests associated with the key, the
+operation must fail with <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.</p>
+
+<h3 id=km_tag_padding>KM_TAG_PADDING</h3>
+
+<p>Specifies the padding modes which may be used with the key. This tag is
+relevant to RSA and AES keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_PAD_NONE = 1,
+ KM_PAD_RSA_OAEP = 2,
+ KM_PAD_RSA_PSS = 3,
+ KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
+ KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
+ KM_PAD_PKCS7 = 64,
+} keymaster_padding_t;
+</pre>
+
+<p><code>KM_PAD_RSA_OAEP</code> and <code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code> are used
+only for RSA encryption/decryption keys and specify RSA PKCS#1v2 OAEP
+padding and RSA PKCS#1 v1.5 randomized padding, respectively. <code>KM_PAD_RSA_PSS</code> and
+<code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> are used only for RSA signing/verification keys and
+specify RSA PKCS#1v2 PSS
+padding and RSA PKCS#1 v1.5 deterministic padding, respectively. Note also that
+the RSA PSS padding mode is incompatible with <a href="#km_tag_digest">KM_DIGEST_NONE</a>.</p>
+
+<p><code>KM_PAD_NONE</code> may be used with either RSA or AES keys. For AES keys,
+if <code>KM_PAD_NONE</code> is used with block mode ECB or CBC and the data to be encrypted
+or decrypted
+is not a multiple of the AES block size in length, the call to finish must fail
+with <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
+
+<p><code>KM_PAD_PKCS7</code> may only be used with AES keys, and only with ECB and CBC modes.</p>
+
+<p>This tag is repeatable. A padding mode must be specified in the call to
+<a href="#begin">begin</a>. If the specified mode is not authorized for the key,
+the operation must fail
+with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
+
+<h3 id=km_tag_caller_nonce>KM_TAG_CALLER_NONCE</h3>
+
+<p>Specifies that the caller is allowed to provide a nonce for nonce-requiring
+operations.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is used only for AES keys, and is only relevant for CBC, CTR and GCM
+block modes. If the tag is not present, implementations should reject any
+operation which provides <a href="#km_tag_nonce">KM_TAG_NONCE</a> to <a href="#begin">begin</a>
+with <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_min_mac_length>KM_TAG_MIN_MAC_LENGTH</h3>
+
+<p>Required for HMAC keys and AES keys that support GCM mode, this tag specifies
+the minimum length of MAC that can be requested or verified with this key.</p>
+
+<p>This value is the minimum MAC length, in bits. It must be a multiple of 8. For
+HMAC keys, the value must be at least 64. For GCM keys it must be at least 96
+and must not exceed 128.</p>
+
+<h3 id=km_tag_rsa_public_exponent>KM_TAG_RSA_PUBLIC_EXPONENT</h3>
+
+<p>Specifies the value of the public exponent for an RSA key pair. This tag is
+relevant only to RSA keys, and required for all RSA keys.</p>
+
+<p>The value is a 64-bit unsigned integer that must satisfy the requirements of an
+RSA public exponent. Because it is specified by the caller and therefore cannot
+be chosen by the implementation, it must be a prime number. Trustlets are
+required to support the value 2^16+1. It is recommended that other reasonable
+values be supported, in particular the value 3. If no exponent is specified or
+if the specified exponent is not supported, key generation must fail
+with <code>KM_ERROR_INVALID_ARGUMENT</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_blob_usage_requirements>KM_TAG_BLOB_USAGE_REQUIREMENTS</h3>
+
+<p>Specifies the system environment conditions which must hold for the generated
+key to be used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_BLOB_STANDALONE = 0,
+ KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
+} keymaster_key_blob_usage_requirements_t;
+</pre>
+
+<p>This tag may be specified during key generation to require that the key be
+usable in the specified condition, and must be returned with the key
+characteristics (from <a href="#generate_key">generate_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a>). If
+the caller specifies <code>KM_TAG_BLOB_USAGE_REQUIREMENTS</code> with
+value <code>KM_BLOB_STANDALONE</code> the trustlet must return a key blob
+which can be used without file system
+support. This is critical for devices with encrypted disks, where the file
+system may not be available until after a Keymaster key is used to decrypt the
+disk.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_bootloader_only>KM_TAG_BOOTLOADER_ONLY</h3>
+
+<p>Specifies that the key may only be used by the bootloader.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>Any attempt to use a key with <code>KM_TAG_BOOTLOADER_ONLY</code> from the
+Android system must fail with <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_active_datetime>KM_TAG_ACTIVE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key becomes active. Prior to this
+time, any attempt to use the key must fail with <code>KM_ERROR_KEY_NOT_YET_VALID</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_origination_expire_datetime>KM_TAG_ORIGINATION_EXPIRE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key expires for signing and encryption
+purposes. After this time, any attempt to use a key
+with <a href="#km_tag_purpose">KM_PURPOSE_SIGN</a> or
+<a href="#km_tag_purpose">KM_PURPOSE_ENCRYPT</a> provided
+to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_usage_expire_datetime>KM_TAG_USAGE_EXPIRE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key expires for verification and
+decryption purposes. After this time, any attempt to use a key with
+<a href="#km_tag_purpose">KM_PURPOSE_VERIFY</a> or <a href="#km_tag_purpose">KM_PURPOSE DECRYPT</a>
+provided to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_min_seconds_between_ops>KM_TAG_MIN_SECONDS_BETWEEN_OPS</h3>
+
+<p>Specifies the minimum amount of time that must elapse between allowed
+operations using a key. This can be used to rate-limit uses of keys in contexts
+where unlimited use may enable brute force attacks.</p>
+
+<p>The value is a 32-bit integer representing seconds between allowed operations.</p>
+
+<p>When a key with this tag is used in an operation, a timer should be started
+during the <a href="#finish">finish</a> or <a href="#abort">abort</a> call. Any
+call to <a href="#begin">begin</a> that is received before the timer indicates
+that the interval specified by <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> has
+elapsed must fail with <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. This
+requirement implies that a trustlet must keep a table of timers for keys
+with this tag. Because Keymaster memory is often limited, it is acceptable for
+this table to have a fixed maximum size and for Keymaster to fail operations
+which attempt to use keys with this tag when the table is full. At least 32
+in-use keys must be accommodated, and table slots must be aggressively reused
+when key minimum-usage intervals expire. If an operation fails because the
+table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_max_uses_per_boot>KM_TAG_MAX_USES_PER_BOOT</h3>
+
+<p>Specifies the maximum number of times that a key may be used between system
+reboots. This is another mechanism to rate-limit key use.</p>
+
+<p>The value is a 32-bit integer representing uses per boot.</p>
+
+<p>When a key with this tag is used in an operation, a key-associated counter
+should be incremented during the <a href="#begin">begin</a> call. After the key counter
+has exceeded this value, all subsequent attempts
+to use the key must fail with <code>KM_ERROR_MAX_OPS_EXCEEDED</code>, until the device is
+restarted. This requirement implies that a trustlet must
+keep a table of use counters for keys with this tag. Because Keymaster memory
+is often limited, it is acceptable for this table to have a fixed maximum size
+and for Keymaster to fail operations that attempt to use keys with this tag
+when the table is full. At least 16 keys must be accommodated. If an operation
+fails because the table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_user_secure_id>KM_TAG_USER_SECURE_ID</h3>
+
+<p>Specifies that a key may only be used under a particular secure user
+authentication state. This tag is mutually exclusive
+with <a href="#km_tag_no_auth_required">KM_TAG_NO_AUTH_REQUIRED</a>.</p>
+
+<p>The value is a 64-bit integer specifying the authentication policy state value
+which must be present in an authentication token (provided to <a href="#begin">begin</a> with
+the <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a>) to authorize use of the key. Any
+call to <a href="#begin">begin</a> with a key with this tag that does not provide an
+authentication token, or provides an
+authentication token without a matching policy state value, must fail.</p>
+
+<p>This tag is repeatable. If any of the provided values matches any policy state
+value in the authentication token, the key is authorized for use. Otherwise the operation
+must fail with <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<h3 id=km_tag_no_auth_required>KM_TAG_NO_AUTH_REQUIRED</h3>
+
+<p>Specifies that no authentication is required to use this key. This tag is
+mutually exclusive with <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_user_auth_type>KM_TAG_USER_AUTH_TYPE</h3>
+
+<p>Specifies the types of user authenticators that may be used to authorize this
+key.</p>
+
+<p>The value is a 32-bit integer bitmask of values from the enumeration:</p>
+
+<pre>
+typedef enum {
+ HW_AUTH_NONE = 0,
+ HW_AUTH_PASSWORD = 1 << 0,
+ HW_AUTH_FINGERPRINT = 1 << 1,
+ // Additional entries should be powers of 2.
+ HW_AUTH_ANY = UINT32_MAX,
+} hw_authenticator_type_t;
+</pre>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_auth_timeout>KM_TAG_AUTH_TIMEOUT</h3>
+
+<p>Specifies the time in seconds for which the key is authorized for use, after
+authentication. If <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is present and this tag
+is not, then the key requires authentication for every
+usage (see <a href="#begin">begin</a> for the details of the authentication-per-operation flow).</p>
+
+<p>The value is a 32-bit integer specifying the time in seconds after a successful
+authentication of the user specified by <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> with
+the authentication method specified
+by <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> that the key can be used.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_all_applications>KM_TAG_ALL_APPLICATIONS</h3>
+
+<p>Reserved for future use.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_application_id>KM_TAG_APPLICATION_ID</h3>
+
+<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
+this tag specifies data that must be provided during all uses of the key. In
+particular, calls to <a href="#export_key">export_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a> must
+provide the same value in the <code>client_id</code> parameter, and
+calls to <a href="#begin">begin</a> must provide this tag and the
+same associated data as part of the <code>in_params</code> set. If the correct
+data is not provided the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_application_data>KM_TAG_APPLICATION_DATA</h3>
+
+<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
+this tag specifies data that must be provided during all uses of the key. In
+particular, calls to <a href="#export_key">export_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a> must
+provide the same value to the <code>client_id</code> parameter, and calls
+to <a href="#begin">begin</a> must provide this tag and the same associated
+data as part of the <code>in_params</code> set. If the correct data is not
+provided, the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_creation_datetime>KM_TAG_CREATION_DATETIME</h3>
+
+<p>Specifies the date and time the key was created, in milliseconds since January
+1, 1970. This tag is optional and informational only.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_origin>KM_TAG_ORIGIN</h3>
+
+<p>Specifies where the key was created, if known. This tag may not be specified
+during key generation or import, and must be added to the key characteristics
+by the trustlet.</p>
+
+<p>The possible values are defined in <code>keymaster_origin_t</code>:</p>
+
+<pre>
+typedef enum {
+ KM_ORIGIN_GENERATED = 0,
+ KM_ORIGIN_IMPORTED = 2,
+ KM_ORIGIN_UNKNOWN = 3,
+} keymaster_key_origin_t
+</pre>
+
+<p>The full meaning of the value depends not only on the value but on whether it's
+found in the hardware-enforced or software-enforced characteristics list.</p>
+
+<p><code>KM_ORIGIN_GENERATED</code> indicates that Keymaster generated the key.
+If in the hardware-enforced list,
+the key was generated in secure hardware and is permanently hardware-bound. If
+in the software-enforced list, the key was generated in SoftKeymaster and is
+not hardware-bound.</p>
+
+<p><code>KM_ORIGIN_IMPORTED</code> indicates that the key was generated outside
+of Keymaster and imported into
+Keymaster. If in the hardware-enforced list, it is permanently hardware-bound,
+although copies outside of secure hardware may exist. If in the
+software-enforces list, the key was imported into SoftKeymaster and is not
+hardware-bound.</p>
+
+<p><code>KM_ORIGIN_UNKNOWN</code> should only appear in the hardware-enforced list.
+It indicates that the key is
+hardware-bound, but it is not known whether the key was originally generated in
+secure hardware or was imported. This only occurs when keymaster0 hardware is
+being used to emulate keymaster1 services.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_rollback_resistant>KM_TAG_ROLLBACK_RESISTANT</h3>
+
+<p>Indicates that the key is rollback-resistant, meaning that when deleted
+by <a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
+the key is guaranteed to be permanently deleted and unusable. It's possible
+that keys without this tag could be deleted and then restored from backup.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_root_of_trust>KM_TAG_ROOT_OF_TRUST</h3>
+
+<p>Specifies the "root of trust," the key used by verified boot to validate the
+operating system booted (if any). This tag is never provided to or returned
+from Keymaster in the key characteristics.</p>
+
+<h3 id=km_tag_associated_data>KM_TAG_ASSOCIATED_DATA</h3>
+
+<p>Provides "associated data" for AES-GCM encryption or decryption. This tag is
+provided to <a href="#update">update</a> and specifies data that is not
+encrypted/decrypted but is used in computing
+the GCM tag.</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_nonce>KM_TAG_NONCE</h3>
+
+<p>Provides or returns a nonce or Initialization Vector (IV) for AES GCM, CBC or
+CTR encryption or decryption. This tag is provided to <a href="#begin">begin</a>
+during encryption and decryption operations. It may only be provided to <a href="#begin">begin</a>
+if the key has <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>. If not provided,
+an appropriate nonce or IV will be randomly generated by
+Keymaster and returned from begin.</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend
+on the mode: GCM nonces are 12 bytes in length; CBC and CTR IVs are 16 bytes in
+length.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_auth_token>KM_TAG_AUTH_TOKEN</h3>
+
+<p>Provides an authentication token (see the Authentication page) to
+<a href="#begin">begin</a>, <a href="#update">update</a> or <a href="#finish">finish</a>,
+to prove user authentication for a key operation that requires
+it (key has <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>).</p>
+
+<p>The value is a blob which contains a <code>hw_auth_token_t</code> structure.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_mac_length>KM_TAG_MAC_LENGTH</h3>
+
+<p>Provides the requested length of a MAC or GCM authentication tag, in bits.</p>
+
+<p>The value is the MAC length in bits. It must be a multiple of 8 and must be at
+least as large as the value of <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
+associated with the key.</p>
+
+<h2 id=functions>Functions</h2>
+
+<h3 id=deprecated_functions>Deprecated functions</h3>
+
+<p>The following functions are in the <code>keymaster1_device_t</code> definition but
+should not be implemented. The function pointers should be set
+to <code>NULL</code>:</p>
+
+<ul>
+ <li><code>generate_keypair</code>
+ <li><code>import_keypair</code>
+ <li><code>get_keypair_public</code>
+ <li><code>delete_keypair</code>
+ <li><code>delete_all</code>
+ <li><code>sign_data</code>
+ <li><code>verify_data</code>
+</ul>
+
+<h3 id=general_implementation_guidelines>General implementation guidelines</h3>
+
+<p>The following guidelines apply to all functions in the API.</p>
+
+<h4 id=input_pointer_parameters>Input pointer parameters</h4>
+
+<p>Input pointer parameters that are not used for a given call may be <code>NULL</code>.
+The caller is not required to provide placeholders. For example, some key
+types and modes may not use any values from the <code>in_params</code> argument
+to <a href="#begin">begin</a>, so the caller may set <code>in_params</code>
+to <code>NULL</code> or provide an empty parameter set. It is also acceptable for the caller to
+provide unused parameters, and Keymaster methods should not issue errors.</p>
+
+<p>If a required input parameter is NULL, Keymaster methods should return
+<code>KM_ERROR_UNEXPECTED_NULL_POINTER</code>.</p>
+
+<h4 id=output_pointer_parameters>Output pointer parameters</h4>
+
+<p>Similar to input pointer parameters, unused output pointer parameters
+may be <code>NULL</code>. If a method needs to return data in an output
+parameter found to be <code>NULL</code>, it should return <code>KM_ERROR_OUTPUT_PARAMETER_NULL</code>.</p>
+
+<h4 id=api_misuse>API misuse</h4>
+
+<p>There are many ways that callers can make requests that don't make sense or are
+foolish but not technically wrong. Keymaster1 implementations are not required
+to fail in such cases or issue a diagnostic. Use of too-small keys,
+specification of irrelevant input parameters, reuse of IVs or nonces,
+generation of keys with no purposes (hence useless) and the like should not be
+diagnosed by implementations. Omission of required parameters, specification of
+invalid required parameters, and similar errors must be diagnosed.</p>
+
+<p>It is the responsibility of apps, the framework, and Android keystore to ensure
+that the calls to Keymaster modules are sensible and useful.</p>
+
+<h3 id=get_supported_algorithms>get_supported_algorithms</h3>
+
+<p>Returns the list of algorithms supported by the Keymaster hardware
+implementation. A software implementation must return an empty list; a hybrid
+implementation must return a list containing only the algorithms that are
+supported by hardware.</p>
+
+<p>Keymaster1 implementations must support RSA, EC, AES and HMAC.</p>
+
+<h3 id=get_supported_block_modes>get_supported_block_modes</h3>
+
+<p>Returns the list of AES block modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>For RSA, EC and HMAC, which are not block ciphers, the method must return an
+empty list for all valid purposes. Invalid purposes should cause the method to
+return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
+
+<p>Keymaster1 implementations must support ECB, CBC, CTR and GCM for AES
+encryption and decryption.</p>
+
+<h3 id=get_supported_padding_modes>get_supported_padding_modes</h3>
+
+<p>Returns the list of padding modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>HMAC and EC have no notion of padding so the method must return an empty list
+for all valid purposes. Invalid purposes should cause the method to return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
+
+<p>For RSA, keymaster1 implementations must support:</p>
+
+<ul>
+ <li>Unpadded encryption, decryption, signing and verification. For unpadded
+encryption and signing, if the message is shorter than the public modulus,
+implementations must left-pad it with zeros. For unpadded decryption and
+verification, the input length must match the public modulus size.
+ <li>PKCS#1 v1.5 encryption and signing padding modes
+ <li>PSS with a minimum salt length of 20
+ <li>OAEP
+</ul>
+
+<p>For AES in ECB and CBC modes, keymaster1 implementations must support no
+padding and PKCS#7-padding. CTR and GCM modes must support only no padding.</p>
+
+<h3 id=get_supported_digests>get_supported_digests</h3>
+
+<p>Returns the list of digest modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>No AES modes support or require digesting, so the method must return an empty
+list for valid purposes.</p>
+
+<p>Keymaster1 implementations are allowed to implement a subset of the defined
+digests, but must provide SHA-256. It is strongly recommended that keymaster1
+implementations provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the
+full set of defined digests).</p>
+
+<h3 id=get_supported_import_formats>get_supported_import_formats</h3>
+
+<p>Returns the list of import formats supported by the Keymaster hardware
+implementation of a specified algorithm.</p>
+
+<p>Keymaster1 implementations must support the PKCS#8 format (without password
+protection) for importing RSA and EC key pairs, and must support RAW import of
+AES and HMAC key material.</p>
+
+<h3 id=get_supported_export_formats>get_supported_export_formats</h3>
+
+<p>Returns the list of export formats supported by the Keymaster hardware
+implementation of a specified algorithm.</p>
+
+<p>Keymaster1 implementations must support the X.509 format for exporting RSA and
+EC public keys. Export of private keys or asymmetric keys must not be
+supported.</p>
+
+<h3 id=add_rng_entropy>add_rng_entropy</h3>
+
+<p>Adds caller-provided entropy to the pool used by the Keymaster1 implementation
+for generating random numbers, for keys, IVs, etc.</p>
+
+<p>Keymaster1 implementations must <strong>securely</strong> mix the provided
+entropy into their pool, which must also contain
+internally-generated entropy from a hardware random number generator. Mixing
+must have the property that an attacker with complete control of either
+the <code>add_rng_entropy</code>-provided bits or the hardware-generated bits, but not both, cannot predict
+bits generated from the entropy pool with probability greater than ½.</p>
+
+<p>Keymaster1 implementations that attempt to estimate the entropy in their
+internal pool must assume that data provided by <code>add_rng_entropy</code> contains no entropy.</p>
+
+<h3 id=generate_key>generate_key</h3>
+
+<p>Generates a new cryptographic key, specifying associated authorizations, which
+will be permanently bound to the key. Keymaster1 implementations must make it
+impossible to use a key in any way inconsistent with the authorizations
+specified at generation time. With respect to authorizations that the secure
+hardware cannot enforce, the secure hardware's obligation is limited to
+ensuring that the unenforceable authorizations associated with the key cannot
+be modified, so that every call to <a href="#get_key_characteristics">get_key_characteristics</a>
+will return the original value. In addition, the characteristics returned by <code>generate_key</code>
+must allocate authorizations correctly between the hardware-enforced and
+software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
+for more details.</p>
+
+<p>The parameters that must be provided to <code>generate_key</code> depend on the type of key
+being generated. This section will summarize the
+required and allowed tags for each type of key. <a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>
+is always required, to specify the type.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>The following parameters are required when generating an RSA key.</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the size of the public
+ modulus, in bits. If omitted, the method must
+return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>. Values that must be supported are
+1024, 2048, 3072 and 4096. It is
+recommended to support all key sizes that are a multiple of 8.
+ <li><a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> specifies
+ the RSA public exponent value. If omitted, the method must
+ return <code>KM_ERROR_INVALID_ARGUMENT</code>.
+ Implementations must support the values 3 and 65537. It is recommended to
+support all prime values up to 2^64.
+</ul>
+
+<p>The following parameters are not required to generate an RSA key, but creating
+an RSA key without them will produce a key that is unusable.
+The <code>generate_key</code> function should not return an error if these parameters are omitted.</p>
+
+<ul>
+ <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> specifies allowed purposes.
+ All purposes must be supported for RSA keys, in
+any combination.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies digest algorithms that
+ may be used with the new key. Implementations
+that do not support all digest algorithms must accept key generation requests
+that include unsupported digests. The unsupported digests should be placed in
+the "software-enforced" list in the returned key characteristics. This is
+because the key will be usable with those other digests, but digesting will be
+performed in software. Then hardware will be called to perform the operation
+with <code>KM_DIGEST_NONE</code>.
+ <li><a href="#km_tag_padding">KM_TAG_PADDING</a> specifies the padding modes
+ that may be used with the new key. Implementations
+that do not support all digest algorithms must place <code>KM_PAD_RSA_PSS</code>
+and <code>KM_PAD_RSA_OAEP</code> in the software-enforced list of the key
+characteristics if any unsupported
+digest algorithms are specified.
+</ul>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required to generate an
+ECDSA key. It is used to select the EC group.
+Implementations must support values 224, 256, 384 and 521, which indicate the
+NIST p-224, p-256, p-384 and p521 curves, respectively.</p>
+
+<p><a href="#km_tag_digest">KM_TAG_DIGEST</a> is also needed for a useful ECDSA key,
+but is not required for generation.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required when
+generating an AES key. If omitted, the method must return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>.
+Values that must be supported are 128 and 256. It is recommended to support
+192-bit AES keys.</p>
+
+<p>The following parameters are particularly relevant for AES keys, but not
+required to generate one:</p>
+
+<ul>
+ <li><code>KM_TAG_BLOCK_MODE</code> specifies the block modes with which the new key may be used.
+ <li><code>KM_TAG_PADDING</code> specifies the padding modes that may be used. This is only relevant for ECB
+and CBC modes.
+</ul>
+
+<p>If the GCM block mode is specified, then <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
+must be provided. If omitted, the method must return
+<code>KM_ERROR_MISSING_MIN_MAC_LENGTH</code>. The value of the tag must be a multiple of 8 and must
+be at least 96 and no more than 128.</p>
+
+<h4 id=hmac_keys>HMAC keys</h4>
+
+<p>The following parameters are required for HMAC key generation:</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the key size in bits. Values
+ smaller than 64 and values that are not
+multiples of 8 must not be supported. All multiples of 8, from 64 to 512, must
+be supported. Larger values may be supported.
+ <li><a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a> specifies the minimum length of
+ MACs that can be generated or verified with
+this key. The value must be a multiple of 8 and must be at least 64.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies the digest algorithm for the key. Exactly
+ one digest must be
+specified, otherwise return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>. If the digest is not supported
+by the trustlet, return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.
+</ul>
+
+<h4 id=key_characteristics>Key characteristics</h4>
+
+<p>If the characteristics argument is non-NULL, <code>generate_key</code> must return the newly-generated
+key's characteristics divided appropriately
+into hardware-enforced and software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
+for a description of which characteristics go in which list. The returned
+characteristics must include all of the parameters specified to key generation,
+except <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> and
+<a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>.
+If these tags were included in the key parameters, they must be removed from
+the returned characteristics; it must not be possible to find their values by
+examining the returned key blob. However, they must be cryptographically bound
+to the key blob, so that if the correct values are not provided when the key is
+used, usage will fail. Similarly, <a href="#km_tag_root_of_trust">KM_TAG_ROOT_OF_TRUST</a> must
+be cryptographically bound to the key, but it may not be specified during
+key creation or import and must never be returned.</p>
+
+<p>In addition to the provided tags, the trustlet must also
+add <a href="#km_tag_origin">KM_TAG_ORIGIN</a>, with the value <code>KM_ORIGIN_GENERATED</code>,
+and if the key is rollback resistant, <a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a>.</p>
+
+<h4 id=rollback_resistance>Rollback resistance </h4>
+
+<p>Rollback resistance means that once a key is deleted with
+<a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
+it is guaranteed by secure hardware never to be usable again. Implementations
+without rollback resistance will typically return generated or imported key
+material to the caller as a key blob, an encrypted and authenticated form. When
+keystore deletes the key blob, the key is gone, but an attacker who has
+previously managed to retrieve the key material can potentially restore it to
+the device.</p>
+
+<p>A key is rollback resistant if the secure hardware guarantees that deleted keys
+cannot be restored later. This is generally done by storing additional key
+metadata in a trusted location that cannot be manipulated by an attacker. On
+mobile devices, the mechanism used for this is usually Replay Protected Memory
+Blocks (RPMB). Because the number of keys that may be created is essentially
+unbounded and the trusted storage used for rollback resistance may be limited
+in size, it is required that this method succeed even if rollback resistance
+cannot be provided for the new key. In that case,
+<a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a> should not be
+added to the key characteristics.</p>
+
+<h3 id=get_key_characteristics>get_key_characteristics</h3>
+
+<p>Returns parameters and authorizations associated with the provided key, divided
+into two sets: hardware-enforced and software-enforced. The description here
+applies equally to the key characteristics lists returned
+by <a href="#generate_key">generate_key</a> and <a href="#import_key">import_key</a>.</p>
+
+<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation
+or import, the same value must provided to
+this method in the <code>client_id</code> argument. Otherwise, the
+method must return <code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly,
+if <code>KM_TAG_APPLICATION_DATA </code>was provided during generation
+or import, the same value must be provided to
+this method in the <code>app_data</code> argument.</p>
+
+<p>The characteristics returned by this method completely describe the type and
+usage of the specified key.</p>
+
+<p>The general rule for deciding whether a given tag belongs in the
+hardware-enforced or software-enforced list is that if the meaning of the tag
+is fully assured by secure hardware, it is hardware-enforced. Otherwise, it's
+software enforced. Below is a list of specific tags whose correct allocation
+may be unclear:</p>
+
+<ul>
+ <li><a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>, <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a>,
+ and <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> are
+ intrinsic properties of the key. For any key that is secured by hardware,
+these will be in the hardware-enforced list, because the statement that, for
+example, "This RSA key material is only used as an RSA key" is enforced by
+hardware because the hardware will use it in no other way and software has no
+access to the key material and cannot use it at all.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> values that are supported by the
+ secure hardware are to be placed in the
+hardware-supported list. Unsupported digests go in the software-supported list.
+ <li><a href="#km_tag_padding">KM_TAG_PADDING</a> values generally go in the
+ hardware-supported list, but if there is a
+possibility that a specific padding mode may have to be performed by software,
+they go in the software-enforced list. Such a possibility arises for RSA keys
+that permit PSS or OAEP padding with digest algorithms that are not supported
+by the secure hardware.
+ <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> and
+ <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> are hardware-enforced
+ only if user authentication is hardware enforced. For
+that to be true, the Keymaster trustlet and the relevant authentication
+trustlet must both be secure and must share a secret HMAC key used to sign and
+validate authentication tokens. See the Authentication page for details.
+ <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a>,
+ <a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a>,
+ and <a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> tags
+ require access to a verifiably correct wall clock. Most secure hardware
+will only have access to time information provided by the non-secure OS, which
+means the tags are software-enforced.
+ <li><a href="#km_tag_origin">KM_TAG_ORIGIN</a> is always in the hardware list for
+ hardware-bound keys. Its presence in that
+list is the way higher layers determine that a key is hardware-backed.
+</ul>
+
+<h3 id=import_key>import_key</h3>
+
+<p>Imports key material into Keymaster hardware. Key definition parameters and
+output characteristics are handled the same as for <code>generate_key</code>,
+with the following exceptions:</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> and
+ <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> (for RSA keys only)
+ are not required in the input parameters. If not provided,
+the trustlet must deduce the values from the provided key material and add
+appropriate tags and values to the key characteristics. If the parameters are
+provided, the trustlet must validate them against the key material. In the
+event of a mismatch, the method must return <code>KM_ERROR_IMPORT_PARAMETER_MISMATCH</code>.
+ <li>The returned <a href="#km_tag_origin">KM_TAG_ORIGIN</a> must have the
+ value <code>KM_ORIGIN_IMPORTED</code>.
+</ul>
+
+<h3 id=export_key>export_key</h3>
+
+<p>Exports a public key from a Keymaster RSA or EC key pair.</p>
+
+<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation or import,
+the same value must provided to
+this method in the <code>client_id</code> argument. Otherwise, the method must return
+<code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly, if <code>KM_TAG_APPLICATION_DATA</code>
+was provided during generation or import, the same value must be provided to
+this method in the <code>app_data</code> argument.</p>
+
+<h3 id=delete_key>delete_key</h3>
+
+<p>Deletes the provided key. This method is optional, and will likely be
+implemented only by Keymaster modules that provide rollback resistance.</p>
+
+<h3 id=delete_all_keys>delete_all_keys</h3>
+
+<p>Deletes all keys. This method is optional, and will likely be implemented only
+by Keymaster modules that provide rollback resistance.</p>
+
+<h3 id=begin>begin</h3>
+
+<p>Begins a cryptographic operation, using the specified key, for the specified
+purpose, with the specified parameters (as appropriate), and returns an
+operation handle which is used with <a href="#update">update</a> and <a href="#finish">finish</a> to complete the operation.</p>
+
+<p>If <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> or <a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>
+were specified during key generation or import, calls to begin must include
+those tags with the originally-specified values in the <code>in_params</code> argument to this method.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>During this method, the following key authorizations must be enforced by the
+trustlet if the implementation placed them in the "hardware-enforced"
+characteristics and if the operation is not a public key operation. Public key
+operations, meaning <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>,
+with RSA or EC keys, must be allowed to succeed even if authorization
+requirements are not met.</p>
+
+<ul>
+ <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> requires that the purpose specified
+ for this method match one of the purposes
+in the key authorizations, unless the requested operation is a public key
+operation, meaning that the key is RSA or EC and the purpose is <code>KM_PURPOSE_ENCRYPT</code>
+or <code>KM_PURPOSE_VERIFY</code>. Note that <code>KM_PURPOSE_ENCRYPT</code> is not valid for EC keys.
+Begin should return <code>KM_ERROR_UNSUPPORTED_PURPOSE</code> in that case.
+ <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a> requires comparison with a trusted
+ UTC time source. If the current date and
+time is prior to the tag value, the method must return <code>KM_ERROR_KEY_NOT_YET_VALID</code>.
+ <li><a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a> requires
+ comparison with a trusted UTC time source. If the current date and
+time is later than the tag value and the purpose is <code>KM_PURPOSE_ENCRYPT</code> or <code>KM_PURPOSE_SIGN</code>,
+the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
+ <li><a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> requires comparison with a
+ trusted UTC time source. If the current date and
+time is later than the tag value and the purpose is <code>KM_PURPOSE_DECRYPT</code> or <code>KM_PURPOSE_VERIFY</code>,
+the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
+ <li><a href="#km_tag_min_seconds_between_ops">KM_TAG_MIN_SECONDS_BETWEEN_OPS</a> requires comparison with a
+ trusted relative timer indicating the last use of
+the key. If the last use time plus the tag value is less than the current time,
+the method must return <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. See the tag description for
+important implementation requirements.
+ <li><a href="#km_tag_max_uses_per_boot">KM_TAG_MAX_USES_PER_BOOT</a> requires comparison against a
+ secure counter that tracks the uses of the key
+since boot time. If the count of previous uses exceeds the tag value, the
+method must return <code>KM_ERROR_KEY_MAX_OPS_EXCEEDED</code>.
+ <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is enforced by this method only
+ if the key also has <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>. If the key has both,
+ then this method must have received a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in
+ <code>in_params</code> and that token must be valid, meaning that the HMAC field validates correctly.
+In addition, at least one of the <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>
+values from the key must match at least one of the secure ID values in the
+token. Finally, the key must also have a <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> and
+it must match the auth type in the token. If any of these requirements is
+not met, the method must return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.
+ <li><a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> allows the caller to specify a nonce
+ or initialization vector (IV). If the key
+does not have this tag but the caller provided <a href="#km_tag_nonce">KM_TAG_NONCE</a> to this method,
+<code>KM_ERROR_CALLER_NONCE_PROHIBITED</code> must be returned.
+ <li><a href="#km_tag_bootloader_only">KM_TAG_BOOTLOADER_ONLY</a> specifies that the key may only be
+ used by the bootloader. If this method is
+called with a bootloader-only key after the bootloader has finished executing,
+it must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.
+</ul>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>All RSA key operations must specify exactly one padding mode in <code>in_params</code>. If
+unspecified or specified more than once, the method must return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
+
+<p>RSA signing and verification operations require a digest, as do RSA encryption
+and decryption operations with OAEP padding mode. For those cases, the caller
+must specify exactly one digest in <code>in_params</code>. If unspecified or specified more than once,
+the method must return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.</p>
+
+<p>Private key operations (<code>KM_PURPOSE_DECYPT</code> and <code>KM_PURPOSE_SIGN</code>) require
+authorization of digest and padding, which means that the specified
+values must be in the key authorizations. If not, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>
+or <code>KM_ERROR_INCOMPATIBLE_PADDING</code>, as appropriate. Public key operations
+(<code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>) are permitted with
+unauthorized digest or padding.</p>
+
+<p>With the exception of <code>KM_PAD_NONE</code>, all RSA padding modes are applicable only to
+certain purposes. Specifically, <code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> and <code>KM_PAD_RSA_PSS</code>
+only support signing and verification, while <code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> and
+<code>KM_PAD_RSA_OAEP</code> only support encryption and decryption. The method must return
+<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code> if the specified mode does not support the specified purpose.</p>
+
+<p>There are some important interactions between padding modes and digests:</p>
+
+<ul>
+ <li><code>KM_PAD_NONE</code> indicates that a "raw" RSA operation will be performed. If signing or
+verifying, <code>KM_DIGEST_NONE </code>must be specified for the digest. No digest is required for unpadded encryption
+or decryption.
+ <li><code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> padding requires a digest, which may be <code>KM_DIGEST_NONE.</code>
+ <li><code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> padding does not require a digest.
+ <li><code>KM_PAD_RSA_PSS</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
+ If <code>KM_DIGEST_NONE</code> is specified, the method must return
+ <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>. In addition, the
+ size of the RSA key must be at least 22 bytes larger than
+the output size of the digest. Otherwise, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+ <li><code>KM_PAD_RSA_OAEP</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
+ If <code>KM_DIGEST_NONE</code> is specified, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+</ul>
+
+<h4 id=ec_keys>EC keys</h4>
+
+<p>EC key operations must specify exactly one padding mode in <code>in_params</code>.
+If unspecified or specified more than once,
+return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
+
+<p>Private key operations (<code>KM_PURPOSE_SIGN</code>) require authorization of the
+digest, which means that the specified value must be in the key authorizations.
+If not, return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+Public key operations (<code>KM_PURPOSE_VERIFY</code>) are permitted with unauthorized digest or padding.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>AES key operations must specify exactly one block mode and one padding mode in <code>in_params</code>.
+If either value is unspecified or specified more than once, return <code>KM_ERROR_UNSUPPORTED_BLOCK_MODE</code> or
+<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>. The specified modes must be authorized by the key.
+Otherwise, the method must
+return <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code> or <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_GCM</code>, <code>in_params</code> must specify <code>KM_TAG_MAC_LENGTH</code>, and the
+specified value must be a multiple of 8 and must not be greater than
+128, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations. For MAC lengths greater than 128 or non-multiples of
+8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_GCM</code> or <code>KM_MODE_CTR</code>, the specified padding mode must
+be <code>KM_PAD_NONE</code>. For <code>KM_MODE_ECB</code> or <code>KM_MODE_CBC</code>, the mode may
+be <code>KM_PAD_NONE</code> or <code>KM_PAD_PKCS7</code>. If the padding mode doesn't meet these
+requirements, return <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_CBC</code>, <code>KM_MODE_CTR</code>, or <code>KM_MODE_GCM</code>, an initialization vector or nonce is needed.
+In most cases, callers should not
+provide an IV or nonce and the Keymaster implementation must generate a random
+IV or nonce and return it via <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>out_params</code>. CBC
+and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
+authorizations contain <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>, then the caller may
+provide an IV/nonce with <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>in_params</code>. If a
+nonce is provided when <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is not authorized,
+return <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>. If a nonce is not provided when
+<a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is authorized, generate a random IV/nonce.</p>
+
+<h4 id=hmac_keys>HMAC keys</h4>
+
+<p>HMAC key operations must specify <code>KM_TAG_MAC_LENGTH</code> in <code>in_params</code>.
+The specified value must be a multiple of 8 and must not be greater than the
+digest length, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations.
+For MAC lengths greater than the digest length or
+non-multiples of 8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than
+the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
+
+<h3 id=update>update</h3>
+
+<p>Provides data to process in an ongoing operation started with <a href="#begin">begin</a>.
+The operation is specified by the <code>operation_handle</code> parameter.</p>
+
+<p>To provide more flexibility for buffer handling, implementations of this method
+have the option of consuming less data than was provided. The caller is
+responsible for looping to feed the rest of the data in subsequent calls. The
+amount of input consumed must be returned in the <code>input_consumed</code> parameter.
+Implementations must always consume at least one byte, unless the
+operation cannot accept any more; if more than zero bytes are provided and zero
+bytes are consumed, callers will consider this an error and abort the
+operation.</p>
+
+<p>Implementations may also choose how much data to return, as a result of the
+update. This is only relevant for encryption and decryption operations, since
+signing and verification return no data until <a href="#finish">finish</a>. It is recommended
+to return data as early as possible, rather than buffer it.</p>
+
+<h4 id=error_handling>Error handling</h4>
+
+<p>If this method returns an error code other than <code>KM_ERROR_OK</code>, the operation is
+aborted and the operation handle must be invalidated. Any
+future use of the handle, with this method or <a href="#finish">finish</a> or <a href="#abort">abort</a>,
+must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception
+is the case where the key has:</p>
+
+<ul>
+ <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
+ <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
+</ul>
+
+<p>In this case, the key requires an authorization per operation, and the update
+method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
+The token must be valid (HMAC must verify) and it must contain a
+matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
+contain the operation handle of the current operation in the
+challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and
+<a href="#finish">finish</a>. The implementation need only validate the token once if it prefers.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept
+the entire block to be signed or verified in a single
+update. It may not consume only a portion of the block. It still must accept
+the data in multiple updates if the caller chooses to provide it that way,
+however. If the caller provides more data to sign than can be used (length of
+data exceeds RSA key size), return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept the
+entire block to be signed or verified in a single
+update. This method may not consume only a portion of the block.</p>
+
+<p>However, this method still must accept the data in multiple updates if the
+caller chooses to provide it that way. If the caller provides more data to sign
+than can be used, the data should be silently truncated. (This differs from the
+handling of excess data provided in similar RSA operations. The reason for this
+is compatibility with legacy clients.)</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>AES GCM mode supports "associated authentication data," provided via the
+<a href="#km_tag_associated_data">KM_TAG_ASSOCIATED_DATA</a> tag in the <code>in_params</code> argument.
+The associated data may be provided in repeated calls (important if
+the data is too large to send in a single block) but must always precede data
+to be encrypted or decrypted. An update call may receive both associated data
+and data to encrypt/decrypt, but subsequent updates may not include associated
+data. If the caller provides associated data to an update call after a call
+that includes data to encrypt/decrypt, return <code>KM_ERROR_INVALID_TAG</code>.</p>
+
+<p>For GCM encryption, the tag is appended to the ciphertext by <a href="#finish">finish</a>.
+During decryption, the last <code>KM_TAG_MAC_LENGTH</code> bytes of the data provided to the last
+update call is the tag. Since a given
+invocation of <a href="#update">update</a> cannot know if it's the last invocation, it must process all but the tag
+length and buffer the possible tag data for processing during <a href="#finish">finish</a>.</p>
+
+<h3 id=finish>finish</h3>
+
+<p>Finished an ongoing operation started with <a href="#begin">begin</a>, processing all of the
+as-yet-unprocessed data provided by <a href="#update">update</a>(s).</p>
+
+<p>This method is the last one called in an operation, so all processed data must
+be returned.</p>
+
+<p>Whether it completes successfully or returns an error, this method finalizes
+the operation and therefore invalidates the provided operation handle. Any
+future use of the handle, with this method or <a href="#update">update</a> or
+<a href="#abort">abort</a>, must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
+
+<p>Signing operations return the signature as the output. Verification operations
+accept the signature in the <code>signature</code> parameter, and return no output.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception is the case where the key has:</p>
+
+<ul>
+ <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
+ <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
+</ul>
+
+<p>In this case, the key requires an authorization per operation, and the update
+method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
+The token must be valid (HMAC must verify) and it must contain a
+matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
+contain the operation handle of the current operation in the
+challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and <a href="#finish">finish</a>.
+The implementation need only validate the token once if it prefers.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>Some additional requirements, depending on the padding mode:</p>
+
+<ul>
+ <li><strong>KM_PAD_NONE</strong>. For unpadded signing and encryption operations, if the provided data is
+shorter than the key, the data must be zero-padded on the left before
+signing/encryption. If the data is the same length as the key but numerically
+larger, return <code>KM_ERROR_INVALID_ARGUMENT</code>. For verification and decryption operations, the data must be exactly as long
+as the key. Otherwise, return <code>KM_ERROR_INVALID_INPUT_LENGTH.</code>
+ <li><strong>KM_PAD_RSA_PSS</strong>. For PSS-padded signature operations, the PSS salt must be at least 20 bytes
+in length and randomly-generated. The salt may be longer; the reference
+implementation uses maximally-sized salt. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
+<code>input_params</code> on <a href="#begin">begin</a> is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest
+algorithm.
+ <li><strong>KM_PAD_RSA_OAEP</strong>. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
+ <code>input_params</code> on <a href="#begin">begin</a> is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest
+algorithm.
+</ul>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>If the data provided for unpadded signing or verification is too long, truncate
+it.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>Some additional requirements, depending on block mode:</p>
+
+<ul>
+ <li><strong>KM_MODE_ECB</strong> or <strong>KM_MODE_CBC</strong>. If padding is <code>KM_PAD_NONE</code> and the
+ data length is not a multiple of the AES block size, return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>. If
+ padding is <code>KM_PAD_PKCS7</code>, pad the data per the PKCS#7 specification. Note that PKCS#7 requires that if
+the data is a multiple of the block length, an additional padding block must be
+added.
+ <li><strong>KM_MODE_GCM</strong>. During encryption, after processing all plaintext, compute the
+ tag (<a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes) and append it to the returned ciphertext.
+ During decryption, process
+the last <a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes as the tag. If tag verification fails,
+return <code>KM_ERROR_VERIFICATION_FAILED</code>.
+</ul>
+
+<h3 id=abort>abort</h3>
+
+<p>Aborts the in-progress operation. After the call to abort, return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code> for
+any subsequent use of the provided operation handle with <a href="#update">update</a>,
+<a href="#finish">finish</a>, or <a href="#abort">abort</a>.</p>
diff --git a/src/devices/tech/security/images/access-to-keymaster.png b/src/devices/tech/security/images/access-to-keymaster.png
new file mode 100644
index 0000000..611f8e3
--- /dev/null
+++ b/src/devices/tech/security/images/access-to-keymaster.png
Binary files differ
diff --git a/src/devices/tech/security/images/fingerprint-daemon.png b/src/devices/tech/security/images/fingerprint-daemon.png
new file mode 100644
index 0000000..a57a7a4
--- /dev/null
+++ b/src/devices/tech/security/images/fingerprint-daemon.png
Binary files differ
diff --git a/src/devices/tech/security/images/fingerprint-data-flow.png b/src/devices/tech/security/images/fingerprint-data-flow.png
new file mode 100644
index 0000000..bc3ff36
--- /dev/null
+++ b/src/devices/tech/security/images/fingerprint-data-flow.png
Binary files differ
diff --git a/src/devices/tech/security/images/gatekeeper-flow.png b/src/devices/tech/security/images/gatekeeper-flow.png
new file mode 100644
index 0000000..693ebec
--- /dev/null
+++ b/src/devices/tech/security/images/gatekeeper-flow.png
Binary files differ
