Document the security features of Android Keystore.

Bug: 18088752
Change-Id: Iec995e39065d9c4f159cb4eea38486f9c75de072

1 files changed, 65 insertions, 2 deletions

diff --git a/docs/html/training/articles/keystore.jd b/docs/html/training/articles/keystore.jd
index 4005a05..20963f5 100644
--- a/docs/html/training/articles/keystore.jd
+++ b/docs/html/training/articles/keystore.jd
@@ -5,6 +5,7 @@ page.title=Android Keystore System
   <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>
@@ -31,7 +32,8 @@ page.title=Android Keystore System
   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
@@ -39,6 +41,67 @@ page.title=Android Keystore System
   (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>
 
@@ -129,7 +192,7 @@ of the two modes:
   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