Merge "CDD: Update USB audio host mode requirements for pro audio" into mnc-dev
diff --git a/src/compatibility/android-cdd.html b/src/compatibility/android-cdd.html
index 78707b4..276bb5a 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>
@@ -4341,7 +4378,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>
@@ -4353,20 +4390,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>
@@ -4700,6 +4739,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..5744717 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>
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/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/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
