src/devices/tech/security/authentication/keymaster.jd

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>