Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 1eda77ae authored by Alex Klyubin's avatar Alex Klyubin
Browse files

Align AndroidKeyStore API with user auth API. 

This simplifies the AndroidKeyStore API around user authentication: no
more explicit control over which user authenticators are bound to
which keys.

User-authenticated keys with timeout are unlocked by whatever unlocks
the secure lock screen (currently, password/PIN/pattern or
fingerprint). User-authenticated keys that need authentication for
every use are unlocked by fingerprint only.

Bug: 20526234
Bug: 20642549
Change-Id: I1e5e6c988f32657d820797ad5696797477a9ebe9
parent 2301174e

api/current.txt

+9 −23
Original line number Diff line number Diff line
@@ -28526,10 +28526,9 @@ package android.security { 
    method public java.lang.String getKeystoreAlias();

    method public int getPurposes();

    method public int getUserAuthenticationValidityDurationSeconds();

    method public int getUserAuthenticators();

    method public boolean isEncryptionRequired();

    method public boolean isInvalidatedOnNewFingerprintEnrolled();

    method public boolean isRandomizedEncryptionRequired();

    method public boolean isUserAuthenticationRequired();

  }















  public static class KeyGeneratorSpec.Builder {









@@ -28539,7 +28538,6 @@ package android.security {













    method public android.security.KeyGeneratorSpec.Builder setBlockModes(java.lang.String...);















    method public android.security.KeyGeneratorSpec.Builder setEncryptionPaddings(java.lang.String...);















    method public android.security.KeyGeneratorSpec.Builder setEncryptionRequired(boolean);













    method public android.security.KeyGeneratorSpec.Builder setInvalidatedOnNewFingerprintEnrolled(boolean);















    method public android.security.KeyGeneratorSpec.Builder setKeySize(int);















    method public android.security.KeyGeneratorSpec.Builder setKeyValidityEnd(java.util.Date);















    method public android.security.KeyGeneratorSpec.Builder setKeyValidityForConsumptionEnd(java.util.Date);









@@ -28547,8 +28545,8 @@ package android.security {













    method public android.security.KeyGeneratorSpec.Builder setKeyValidityStart(java.util.Date);















    method public android.security.KeyGeneratorSpec.Builder setPurposes(int);















    method public android.security.KeyGeneratorSpec.Builder setRandomizedEncryptionRequired(boolean);













    method public android.security.KeyGeneratorSpec.Builder setUserAuthenticationRequired(boolean);















    method public android.security.KeyGeneratorSpec.Builder setUserAuthenticationValidityDurationSeconds(int);













    method public android.security.KeyGeneratorSpec.Builder setUserAuthenticators(int);















  }





























  public class KeyNotYetValidException extends java.security.InvalidKeyException {










@@ -28576,10 +28574,9 @@ package android.security {













    method public java.util.Date getStartDate();















    method public javax.security.auth.x500.X500Principal getSubjectDN();















    method public int getUserAuthenticationValidityDurationSeconds();













    method public int getUserAuthenticators();















    method public boolean isEncryptionRequired();













    method public boolean isInvalidatedOnNewFingerprintEnrolled();















    method public boolean isRandomizedEncryptionRequired();













    method public boolean isUserAuthenticationRequired();















  }





























  public static final class KeyPairGeneratorSpec.Builder {









@@ -28592,7 +28589,6 @@ package android.security {













    method public android.security.KeyPairGeneratorSpec.Builder setEncryptionPaddings(java.lang.String...);















    method public android.security.KeyPairGeneratorSpec.Builder setEncryptionRequired();















    method public android.security.KeyPairGeneratorSpec.Builder setEndDate(java.util.Date);













    method public android.security.KeyPairGeneratorSpec.Builder setInvalidatedOnNewFingerprintEnrolled(boolean);















    method public android.security.KeyPairGeneratorSpec.Builder setKeySize(int);















    method public android.security.KeyPairGeneratorSpec.Builder setKeyType(java.lang.String) throws java.security.NoSuchAlgorithmException;















    method public android.security.KeyPairGeneratorSpec.Builder setKeyValidityEnd(java.util.Date);









@@ -28605,8 +28601,8 @@ package android.security {













    method public android.security.KeyPairGeneratorSpec.Builder setSignaturePaddings(java.lang.String...);















    method public android.security.KeyPairGeneratorSpec.Builder setStartDate(java.util.Date);















    method public android.security.KeyPairGeneratorSpec.Builder setSubject(javax.security.auth.x500.X500Principal);













    method public android.security.KeyPairGeneratorSpec.Builder setUserAuthenticationRequired(boolean);















    method public android.security.KeyPairGeneratorSpec.Builder setUserAuthenticationValidityDurationSeconds(int);













    method public android.security.KeyPairGeneratorSpec.Builder setUserAuthenticators(int);















  }





























  public abstract class KeyStoreKeyProperties {









@@ -28631,14 +28627,6 @@ package android.security {













  public static abstract class KeyStoreKeyProperties.PurposeEnum implements java.lang.annotation.Annotation {















  }



























  public static abstract class KeyStoreKeyProperties.UserAuthenticator {













    field public static final int FINGERPRINT_READER = 2; // 0x2













    field public static final int LOCK_SCREEN = 1; // 0x1













  }

























  public static abstract class KeyStoreKeyProperties.UserAuthenticatorEnum implements java.lang.annotation.Annotation {













  }



























  public class KeyStoreKeySpec implements java.security.spec.KeySpec {















    method public java.lang.String[] getBlockModes();















    method public java.lang.String[] getDigests();









@@ -28651,15 +28639,15 @@ package android.security {













    method public int getOrigin();















    method public int getPurposes();















    method public java.lang.String[] getSignaturePaddings();













    method public int getTeeEnforcedUserAuthenticators();















    method public int getUserAuthenticationValidityDurationSeconds();













    method public int getUserAuthenticators();













    method public boolean isInvalidatedOnNewFingerprintEnrolled();















    method public boolean isTeeBacked();













    method public boolean isUserAuthenticationRequired();













    method public boolean isUserAuthenticationRequirementTeeEnforced();















  }





























  public final class KeyStoreParameter implements java.security.KeyStore.ProtectionParameter {















    method public java.lang.String[] getBlockModes();













    method public android.content.Context getContext();















    method public java.lang.String[] getDigests();















    method public java.lang.String[] getEncryptionPaddings();















    method public java.util.Date getKeyValidityForConsumptionEnd();









@@ -28668,11 +28656,10 @@ package android.security {













    method public int getPurposes();















    method public java.lang.String[] getSignaturePaddings();















    method public int getUserAuthenticationValidityDurationSeconds();













    method public int getUserAuthenticators();















    method public boolean isDigestsSpecified();















    method public boolean isEncryptionRequired();













    method public boolean isInvalidatedOnNewFingerprintEnrolled();















    method public boolean isRandomizedEncryptionRequired();













    method public boolean isUserAuthenticationRequired();















  }





























  public static final class KeyStoreParameter.Builder {









@@ -28682,7 +28669,6 @@ package android.security {













    method public android.security.KeyStoreParameter.Builder setDigests(java.lang.String...);















    method public android.security.KeyStoreParameter.Builder setEncryptionPaddings(java.lang.String...);















    method public android.security.KeyStoreParameter.Builder setEncryptionRequired(boolean);













    method public android.security.KeyStoreParameter.Builder setInvalidatedOnNewFingerprintEnrolled(boolean);















    method public android.security.KeyStoreParameter.Builder setKeyValidityEnd(java.util.Date);















    method public android.security.KeyStoreParameter.Builder setKeyValidityForConsumptionEnd(java.util.Date);















    method public android.security.KeyStoreParameter.Builder setKeyValidityForOriginationEnd(java.util.Date);









@@ -28690,8 +28676,8 @@ package android.security {













    method public android.security.KeyStoreParameter.Builder setPurposes(int);















    method public android.security.KeyStoreParameter.Builder setRandomizedEncryptionRequired(boolean);















    method public android.security.KeyStoreParameter.Builder setSignaturePaddings(java.lang.String...);













    method public android.security.KeyStoreParameter.Builder setUserAuthenticationRequired(boolean);















    method public android.security.KeyStoreParameter.Builder setUserAuthenticationValidityDurationSeconds(int);













    method public android.security.KeyStoreParameter.Builder setUserAuthenticators(int);















  }





























  public class NetworkSecurityPolicy {

























api/system-current.txt



+9
−23




























Original line number
Diff line number
Diff line








@@ -30533,10 +30533,9 @@ package android.security {













    method public java.lang.String getKeystoreAlias();















    method public int getPurposes();















    method public int getUserAuthenticationValidityDurationSeconds();













    method public int getUserAuthenticators();















    method public boolean isEncryptionRequired();













    method public boolean isInvalidatedOnNewFingerprintEnrolled();















    method public boolean isRandomizedEncryptionRequired();













    method public boolean isUserAuthenticationRequired();















  }





























  public static class KeyGeneratorSpec.Builder {









@@ -30546,7 +30545,6 @@ package android.security {













    method public android.security.KeyGeneratorSpec.Builder setBlockModes(java.lang.String...);















    method public android.security.KeyGeneratorSpec.Builder setEncryptionPaddings(java.lang.String...);















    method public android.security.KeyGeneratorSpec.Builder setEncryptionRequired(boolean);













    method public android.security.KeyGeneratorSpec.Builder setInvalidatedOnNewFingerprintEnrolled(boolean);















    method public android.security.KeyGeneratorSpec.Builder setKeySize(int);















    method public android.security.KeyGeneratorSpec.Builder setKeyValidityEnd(java.util.Date);















    method public android.security.KeyGeneratorSpec.Builder setKeyValidityForConsumptionEnd(java.util.Date);









@@ -30554,8 +30552,8 @@ package android.security {













    method public android.security.KeyGeneratorSpec.Builder setKeyValidityStart(java.util.Date);















    method public android.security.KeyGeneratorSpec.Builder setPurposes(int);















    method public android.security.KeyGeneratorSpec.Builder setRandomizedEncryptionRequired(boolean);













    method public android.security.KeyGeneratorSpec.Builder setUserAuthenticationRequired(boolean);















    method public android.security.KeyGeneratorSpec.Builder setUserAuthenticationValidityDurationSeconds(int);













    method public android.security.KeyGeneratorSpec.Builder setUserAuthenticators(int);















  }





























  public class KeyNotYetValidException extends java.security.InvalidKeyException {










@@ -30583,10 +30581,9 @@ package android.security {













    method public java.util.Date getStartDate();















    method public javax.security.auth.x500.X500Principal getSubjectDN();















    method public int getUserAuthenticationValidityDurationSeconds();













    method public int getUserAuthenticators();















    method public boolean isEncryptionRequired();













    method public boolean isInvalidatedOnNewFingerprintEnrolled();















    method public boolean isRandomizedEncryptionRequired();













    method public boolean isUserAuthenticationRequired();















  }





























  public static final class KeyPairGeneratorSpec.Builder {









@@ -30599,7 +30596,6 @@ package android.security {













    method public android.security.KeyPairGeneratorSpec.Builder setEncryptionPaddings(java.lang.String...);















    method public android.security.KeyPairGeneratorSpec.Builder setEncryptionRequired();















    method public android.security.KeyPairGeneratorSpec.Builder setEndDate(java.util.Date);













    method public android.security.KeyPairGeneratorSpec.Builder setInvalidatedOnNewFingerprintEnrolled(boolean);















    method public android.security.KeyPairGeneratorSpec.Builder setKeySize(int);















    method public android.security.KeyPairGeneratorSpec.Builder setKeyType(java.lang.String) throws java.security.NoSuchAlgorithmException;















    method public android.security.KeyPairGeneratorSpec.Builder setKeyValidityEnd(java.util.Date);









@@ -30612,8 +30608,8 @@ package android.security {













    method public android.security.KeyPairGeneratorSpec.Builder setSignaturePaddings(java.lang.String...);















    method public android.security.KeyPairGeneratorSpec.Builder setStartDate(java.util.Date);















    method public android.security.KeyPairGeneratorSpec.Builder setSubject(javax.security.auth.x500.X500Principal);













    method public android.security.KeyPairGeneratorSpec.Builder setUserAuthenticationRequired(boolean);















    method public android.security.KeyPairGeneratorSpec.Builder setUserAuthenticationValidityDurationSeconds(int);













    method public android.security.KeyPairGeneratorSpec.Builder setUserAuthenticators(int);















  }





























  public abstract class KeyStoreKeyProperties {









@@ -30638,14 +30634,6 @@ package android.security {













  public static abstract class KeyStoreKeyProperties.PurposeEnum implements java.lang.annotation.Annotation {















  }



























  public static abstract class KeyStoreKeyProperties.UserAuthenticator {













    field public static final int FINGERPRINT_READER = 2; // 0x2













    field public static final int LOCK_SCREEN = 1; // 0x1













  }

























  public static abstract class KeyStoreKeyProperties.UserAuthenticatorEnum implements java.lang.annotation.Annotation {













  }



























  public class KeyStoreKeySpec implements java.security.spec.KeySpec {















    method public java.lang.String[] getBlockModes();















    method public java.lang.String[] getDigests();









@@ -30658,15 +30646,15 @@ package android.security {













    method public int getOrigin();















    method public int getPurposes();















    method public java.lang.String[] getSignaturePaddings();













    method public int getTeeEnforcedUserAuthenticators();















    method public int getUserAuthenticationValidityDurationSeconds();













    method public int getUserAuthenticators();













    method public boolean isInvalidatedOnNewFingerprintEnrolled();















    method public boolean isTeeBacked();













    method public boolean isUserAuthenticationRequired();













    method public boolean isUserAuthenticationRequirementTeeEnforced();















  }





























  public final class KeyStoreParameter implements java.security.KeyStore.ProtectionParameter {















    method public java.lang.String[] getBlockModes();













    method public android.content.Context getContext();















    method public java.lang.String[] getDigests();















    method public java.lang.String[] getEncryptionPaddings();















    method public java.util.Date getKeyValidityForConsumptionEnd();









@@ -30675,11 +30663,10 @@ package android.security {













    method public int getPurposes();















    method public java.lang.String[] getSignaturePaddings();















    method public int getUserAuthenticationValidityDurationSeconds();













    method public int getUserAuthenticators();















    method public boolean isDigestsSpecified();















    method public boolean isEncryptionRequired();













    method public boolean isInvalidatedOnNewFingerprintEnrolled();















    method public boolean isRandomizedEncryptionRequired();













    method public boolean isUserAuthenticationRequired();















  }





























  public static final class KeyStoreParameter.Builder {









@@ -30689,7 +30676,6 @@ package android.security {













    method public android.security.KeyStoreParameter.Builder setDigests(java.lang.String...);















    method public android.security.KeyStoreParameter.Builder setEncryptionPaddings(java.lang.String...);















    method public android.security.KeyStoreParameter.Builder setEncryptionRequired(boolean);













    method public android.security.KeyStoreParameter.Builder setInvalidatedOnNewFingerprintEnrolled(boolean);















    method public android.security.KeyStoreParameter.Builder setKeyValidityEnd(java.util.Date);















    method public android.security.KeyStoreParameter.Builder setKeyValidityForConsumptionEnd(java.util.Date);















    method public android.security.KeyStoreParameter.Builder setKeyValidityForOriginationEnd(java.util.Date);









@@ -30697,8 +30683,8 @@ package android.security {













    method public android.security.KeyStoreParameter.Builder setPurposes(int);















    method public android.security.KeyStoreParameter.Builder setRandomizedEncryptionRequired(boolean);















    method public android.security.KeyStoreParameter.Builder setSignaturePaddings(java.lang.String...);













    method public android.security.KeyStoreParameter.Builder setUserAuthenticationRequired(boolean);















    method public android.security.KeyStoreParameter.Builder setUserAuthenticationValidityDurationSeconds(int);













    method public android.security.KeyStoreParameter.Builder setUserAuthenticators(int);















  }





























  public class NetworkSecurityPolicy {

























core/java/android/security/keymaster/KeyCharacteristics.java



+4
−4




























Original line number
Diff line number
Diff line








@@ -105,11 +105,11 @@ public class KeyCharacteristics implements Parcelable {













        }















    }





























    public boolean getBoolean(KeyCharacteristics keyCharacteristics, int tag) {













        if (keyCharacteristics.hwEnforced.containsTag(tag)) {













            return keyCharacteristics.hwEnforced.getBoolean(tag, false);













    public boolean getBoolean(int tag) {













        if (hwEnforced.containsTag(tag)) {













            return hwEnforced.getBoolean(tag, false);















        } else {













            return keyCharacteristics.swEnforced.getBoolean(tag, false);













            return swEnforced.getBoolean(tag, false);















        }















    }















}

































docs/html/training/articles/keystore.jd



+27
−1




























Original line number
Diff line number
Diff line








@@ -29,7 +29,9 @@ page.title=Android Keystore System













<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.</p>













  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>































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















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










@@ -112,3 +114,27 @@ and {@link java.security.KeyPairGenerator} or













<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













can only be used if user has been authenticated. The user is authenticated using a subset of their













secure lock screen credentials. This is a security measure which makes it possible to generate













cryptographic assertions about the user having been authenticated.



























<p>When a key is configured to require user authentication, it is also configured to operate in one













of the two modes:













<ul>













<li>User authentication is valid 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













  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#isKeyguardSecure Keyguard.isKeyguardSecure}).













  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













  involving a specific key is authorized by the user. Currently, the only means of such













  authorization is fingerprint authentication: {@link android.hardware.fingerprint.FingerprintManager#authenticate(CryptoObject, CancellationSignal, AuthenticationCallback, int) 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 all fingerprints are unenrolled.</li>













</ul>
























keystore/java/android/security/AndroidKeyStore.java



+4
−21




























Original line number
Diff line number
Diff line








@@ -529,27 +529,10 @@ public class AndroidKeyStore extends KeyStoreSpi {













                KeymasterUtils.getKeymasterPaddingsFromJcaSignaturePaddings(















                        params.getSignaturePaddings()));















        args.addInts(KeymasterDefs.KM_TAG_PADDING, keymasterPaddings);













        if (params.getUserAuthenticators() == 0) {













            args.addBoolean(KeymasterDefs.KM_TAG_NO_AUTH_REQUIRED);













        } else {













            args.addInt(KeymasterDefs.KM_TAG_USER_AUTH_TYPE,













                    KeyStoreKeyProperties.UserAuthenticator.allToKeymaster(













                            params.getUserAuthenticators()));













            long secureUserId = GateKeeper.getSecureUserId();













            if (secureUserId == 0) {













                throw new IllegalStateException("Secure lock screen must be enabled"













                        + " to import keys requiring user authentication");













            }













            args.addLong(KeymasterDefs.KM_TAG_USER_SECURE_ID, secureUserId);













        }













        if (params.isInvalidatedOnNewFingerprintEnrolled()) {













            // TODO: Add the invalidate on fingerprint enrolled constraint once Keymaster supports













            // that.













        }













        if (params.getUserAuthenticationValidityDurationSeconds() != -1) {













            args.addInt(KeymasterDefs.KM_TAG_AUTH_TIMEOUT,













        KeymasterUtils.addUserAuthArgs(args,













                params.getContext(),













                params.isUserAuthenticationRequired(),















                params.getUserAuthenticationValidityDurationSeconds());













        }















        args.addDate(KeymasterDefs.KM_TAG_ACTIVE_DATETIME,















                (params.getKeyValidityStart() != null)















                        ? params.getKeyValidityStart() : new Date(0));