Docs: Redo navigation in security and move keymaster docs
Bug: 24619742
Change-Id: Ia2655bb6659cf61347df3b66dd63b916eb383883
diff --git a/src/security/keystore/index.jd b/src/security/keystore/index.jd
new file mode 100644
index 0000000..e86f253
--- /dev/null
+++ b/src/security/keystore/index.jd
@@ -0,0 +1,100 @@
+page.title=Hardware-backed Keystore
+@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="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="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>