diff options
Diffstat (limited to 'docs/html/training/articles/keystore.jd')
| -rw-r--r-- | docs/html/training/articles/keystore.jd | 123 |
1 files changed, 116 insertions, 7 deletions
diff --git a/docs/html/training/articles/keystore.jd b/docs/html/training/articles/keystore.jd index bbbda67..52cb13e 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> @@ -26,11 +27,13 @@ page.title=Android Keystore System </div> </div> -<p>The Android Keystore system lets you store private keys - in a container to make it more difficult to extract from the - device. Once keys are in the keystore, they can be used for - cryptographic operations with the private key material remaining - non-exportable.</p> +<p>The Android Keystore system lets you store cryptographic keys in a container + to make it more difficult to extract from the device. Once keys are in the + 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 keys to be used only in certain cryptographic 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 @@ -38,6 +41,70 @@ 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 outside of the apps' +processes. + +<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. This is an advanced security feature which is generally useful +only if your requirements are that a compromise of your application process after key +generation/import (but not before or during) cannot lead to unauthorized uses of the key. + +<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> @@ -59,7 +126,8 @@ Android Keystore Provider</h2> <p> To use this feature, you use the standard {@link java.security.KeyStore} -and {@link java.security.KeyPairGenerator} classes along with the +and {@link java.security.KeyPairGenerator} or +{@link javax.crypto.KeyGenerator} classes along with the {@code AndroidKeyStore} provider introduced in Android 4.3 (API level 18).</p> <p>{@code AndroidKeyStore} is registered as a {@link @@ -67,7 +135,9 @@ and {@link java.security.KeyPairGenerator} classes along with the java.security.KeyStore#getInstance(String) KeyStore.getInstance(type)} method and as a provider for use with the {@link java.security.KeyPairGenerator#getInstance(String, String) - KeyPairGenerator.getInstance(algorithm, provider)} method.</p> + KeyPairGenerator.getInstance(algorithm, provider)} and {@link + javax.crypto.KeyGenerator#getInstance(String, String) + KeyGenerator.getInstance(algorithm, provider)} methods.</p> <h3 id="GeneratingANewPrivateKey">Generating a New Private Key</h3> @@ -81,6 +151,11 @@ and {@link java.security.KeyPairGenerator} classes along with the {@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java generate} +<h3 id="GeneratingANewSecretKey">Generating a New Secret Key</h3> + +<p>To generate the key, use a {@link javax.crypto.KeyGenerator} with + {@link android.security.keystore.KeyGenParameterSpec}. + <h3 id="WorkingWithKeyStoreEntries">Working with Keystore Entries</h3> <p>Using the {@code AndroidKeyStore} provider takes place through @@ -105,3 +180,37 @@ and {@link java.security.KeyPairGenerator} classes along with the <p>Similarly, verify data with the {@link java.security.Signature#verify(byte[])} method:</p> {@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java verify} + +<h3 id="UserAuthentication">Requiring User Authentication For Key Use</h3> + +<p>When generating or importing a key into the {@code AndroidKeyStore} you can specify that the key +is only authorized to be used if the user has been authenticated. The user is authenticated using a +subset of their secure lock screen credentials (pattern/PIN/password, fingerprint). + +<p>This is an advanced security feature which is generally useful only if your requirements are that +a compromise of your application process after key generation/import (but not before or during) +cannot bypass the requirement for the user to be authenticated to use the key. + +<p>When a key is authorized to be used only if the user has been authenticated, it is configured to +operate in one of the two modes: +<ul> +<li>User authentication authorizes the use of keys for a duration of time. All keys in this mode are + authorized for use as soon as the user unlocks the secure lock screen or confirms their secure + lock screen credential using the + {@link android.app.KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence) KeyguardManager.createConfirmDeviceCredentialIntent} + flow. The duration for which the authorization remains valid is specific to each key, as specified + using {@code setUserAuthenticationValidityDurationSeconds} during key generation or import. Such + keys 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 (reconfigured to None, + Swipe or other mode which does not authenticate the user) or forcibly reset (e.g. by a Device + Administrator).</li> +<li>User authentication authorizes a specific cryptographic operation associated with one key. In + this mode, each operation involving such a key must be individually authorized by the user. + Currently, the only means of such authorization is fingerprint authentication: + {@link android.hardware.fingerprint.FingerprintManager#authenticate(CryptoObject, CancellationSignal, int, AuthenticationCallback, Handler) FingerprintManager.authenticate}. + Such keys can only be generated or imported if at least one fingerprint is enrolled (see + {@link android.hardware.fingerprint.FingerprintManager#hasEnrolledFingerprints() FingerprintManager.hasEnrolledFingerprints}). + These keys become permanently invalidated once a new fingerprint is enrolled or all fingerprints + are unenrolled.</li> +</ul>
\ No newline at end of file |