Merge "Document the security features of Android Keystore." into mnc-dev

  <div id="qv">

    <h2>In this document</h2>

    <ol>

      <li><a href="#SecurityFeatures">Security Features</a></li>

      <li><a href="#WhichShouldIUse">Choosing Between a Keychain or the Android Keystore Provider</a></li>

      <li><a href="#UsingAndroidKeyStore">Using Android Keystore Provider

      </a></li>

  keystore, they can be used for cryptographic operations with the key material

  remaining non-exportable. Moreover, it offers facilities to restrict when and

  how keys can be used, such as requiring user authentication for key use or

  restricting encryption keys to be used only in certain block modes.</p>

  restricting encryption keys to be used only in certain block modes. See

  <a href="#SecurityFeatures">Security Features</a> section for more information.</p>

<p>The Keystore system is used by the {@link

  android.security.KeyChain} API as well as the Android

  (API level 18). This document goes over when and how to use the

  Android Keystore provider.</p>

<h2 id="SecurityFeatures">Security Features</h2>

Android Keystore system protects key material from unauthorized use. Firstly, Android Keystore

mitigates unauthorized use of key material outside of the Android device by preventing extraction of

the key material from application processes and from the Android device as a whole. Secondly,

Android KeyStore mitigates unauthorized use of key material on the Android device by making apps

specify authorized uses of their keys and then enforcing these restrictions.

<h3 id="ExtractionPrevention">Extraction Prevention</h3>

Key material of Android Keystore keys is protected from extraction using two security measures:

<ul>

<li>Key material never enters the application process. When an application performs cryptographic

  operations using an Android Keystore key, behind the scenes plaintext, ciphertext, and messages to

  be signed or verified are fed to a system process which carries out the cryptographic operations.

  If the app's process is compromised, the attacker may be able to use the app's keys but will not

  be able to extract their key material (for example, to be used outside of the Android device).

  </li>

<li>Key material may be bound to the secure hardware (e.g., Trusted Execution Environment (TEE),

  Secure Element (SE)) of the Android device. When this feature is enabled for a key, its key

  material is never exposed outside of secure hardware. If the Android OS is compromised or an

  attacker can read the device's internal storage, the attacker may be able to use any app's Android

  Keystore keys on the Android device, but not extract them from the device. This feature is enabled

  only if the device's secure hardware supports the particular combination of key algorithm, block

  modes, padding schemes, and digests with which the key is authorized to be used. To check whether

  the feature is enabled for a key, obtain a {@link android.security.keystore.KeyInfo} for the key

  and inspect the return value of

  {@link android.security.keystore.KeyInfo#isInsideSecureHardware() KeyInfo.isInsideSecurityHardware()}.

  </li>

</ul>

<h3 id="KeyUseAuthorizations">Key Use Authorizations</h3>

To mitigate unauthorized use of keys on the Android device, Android Keystore lets apps specify

authorized uses of their keys when generating or importing the keys. Once a key is generated or

imported, its authorizations can not be changed. Authorizations are then enforced by the Android

Keystore whenever the key is used.

<p>Supported key use authorizations fall into the following categories:

<ul>

<li><em>cryptography</em>: authorized key algorithm, operations or purposes (encrypt, decrypt, sign,

  verify), padding schemes, block modes, digests with which the key can be used</li>

<li><em>temporal validity interval</em>: interval of time during which the key is authorized for

  use</li>

<li><em>user authentication</em>: the key can only be used if the user has been authenticated

  recently enough. See <a href="#UserAuthentication">Requiring User Authentication For Key Use</a>.

  </li>

</ul>

<p>As an additional security measure, for keys whose key material is inside secure hardware (see

  {@link android.security.keystore.KeyInfo#isInsideSecureHardware() KeyInfo.isInsideSecurityHardware()})

  some key use authorizations may be enforced by secure hardware, depending on the Android device.

  Cryptographic and user authentication authorizations are likely to be enforced by secure hardware.

  Temporal validity interval authorizations are unlikely to be enforced by the secure hardware

  because it normally does not have an independent secure real-time clock.

<p>Whether a key's user authentication authorization is enforced by the secure hardware can be

  queried using

  {@link android.security.keystore.KeyInfo#isUserAuthenticationRequirementEnforcedBySecureHardware() KeyInfo.isUserAuthenticationRequirementEnforcedBySecureHardware()}.

<h2 id="WhichShouldIUse">Choosing Between a Keychain or the

Android Keystore Provider</h2>

  for use as soon as the user unlocks the secure lock screen or confirms their secure lock screen

  credentials using the {@link android.app.KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence) KeyguardManager.createConfirmDeviceCredentialIntent}

  flow. Each key specifies for how long the authorization remains valid for that key. Such keys

  can only be generated or imported if the secure lock screen is enabled (see {@link android.app.KeyguardManager#isDeviceSecure()}).

  can only be generated or imported if the secure lock screen is enabled (see {@link android.app.KeyguardManager#isDeviceSecure() KeyguardManager.isDeviceSecure()}).

  These keys become permanently invalidated once the secure lock screen is disabled or forcibly

  reset (e.g. by a Device Admin).</li>

<li>User authentication is required for every use of the key. In this mode, a specific operation