Update documentation for fingerprint -> biometric (9374c9f8) · Commits · e / os / android_frameworks_base

core/java/android/hardware/biometrics/CryptoObject.java

+2 −2

Original line number	Diff line number	Diff line
		@@ -25,8 +25,8 @@ import javax.crypto.Cipher;
		import javax.crypto.Mac;

		/**
		* A wrapper class for the crypto objects supported by FingerprintManager. Currently the
		* framework supports {@link Signature}, {@link Cipher} and {@link Mac} objects.
		* A wrapper class for the crypto objects supported by BiometricPrompt and FingerprintManager.
		* Currently the framework supports {@link Signature}, {@link Cipher} and {@link Mac} objects.
		* @hide
		*/
		public class CryptoObject {

keystore/java/android/security/keystore/KeyGenParameterSpec.java

+23 −22

Original line number	Diff line number	Diff line
		@@ -22,7 +22,8 @@ import android.annotation.Nullable;
		import android.annotation.TestApi;
		import android.annotation.UnsupportedAppUsage;
		import android.app.KeyguardManager;
		import android.hardware.fingerprint.FingerprintManager;
		import android.hardware.biometrics.BiometricManager;
		import android.hardware.biometrics.BiometricPrompt;
		import android.security.GateKeeper;
		import android.security.KeyStore;
		import android.text.TextUtils;
		@@ -670,9 +671,9 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		}

		/**
		* Returns {@code true} if the key is irreversibly invalidated when a new fingerprint is
		* enrolled or all enrolled fingerprints are removed. This has effect only for keys that
		* require fingerprint user authentication for every use.
		* Returns {@code true} if the key is irreversibly invalidated when a new biometric is
		* enrolled or all enrolled biometrics are removed. This has effect only for keys that
		* require biometric user authentication for every use.
		*
		* @see #isUserAuthenticationRequired()
		* @see #getUserAuthenticationValidityDurationSeconds()
		@@ -1098,19 +1099,19 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		* <li>The key can only be generated if secure lock screen is set up (see
		* {@link KeyguardManager#isDeviceSecure()}). Additionally, if the key requires that user
		* authentication takes place for every use of the key (see
		* {@link #setUserAuthenticationValidityDurationSeconds(int)}), at least one fingerprint
		* must be enrolled (see {@link FingerprintManager#hasEnrolledFingerprints()}).</li>
		* {@link #setUserAuthenticationValidityDurationSeconds(int)}), at least one biometric
		* must be enrolled (see {@link BiometricManager#canAuthenticate()}).</li>
		* <li>The use of the key must be authorized by the user by authenticating to this Android
		* device using a subset of their secure lock screen credentials such as
		* password/PIN/pattern or fingerprint.
		* password/PIN/pattern or biometric.
		* <a href="{@docRoot}training/articles/keystore.html#UserAuthentication">More
		* information</a>.
		* <li>The key will become <em>irreversibly invalidated</em> once the secure lock screen is
		* disabled (reconfigured to None, Swipe or other mode which does not authenticate the user)
		* or when the secure lock screen is forcibly reset (e.g., by a Device Administrator).
		* Additionally, if the key requires that user authentication takes place for every use of
		* the key, it is also irreversibly invalidated once a new fingerprint is enrolled or once\
		* no more fingerprints are enrolled, unless {@link
		* the key, it is also irreversibly invalidated once a new biometric is enrolled or once\
		* no more biometrics are enrolled, unless {@link
		* #setInvalidatedByBiometricEnrollment(boolean)} is used to allow validity after
		* enrollment. Attempts to initialize cryptographic operations using such keys will throw
		* {@link KeyPermanentlyInvalidatedException}.</li>
		@@ -1121,7 +1122,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		*
		* @see #setUserAuthenticationValidityDurationSeconds(int)
		* @see KeyguardManager#isDeviceSecure()
		* @see FingerprintManager#hasEnrolledFingerprints()
		* @see BiometricManager#canAuthenticate()
		*/
		@NonNull
		public Builder setUserAuthenticationRequired(boolean required) {
		@@ -1161,10 +1162,10 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		* the key.
		*
		* <p>Cryptographic operations involving keys which require user authentication to take
		* place for every operation can only use fingerprint authentication. This is achieved by
		* place for every operation can only use biometric authentication. This is achieved by
		* initializing a cryptographic operation ({@link Signature}, {@link Cipher}, {@link Mac})
		* with the key, wrapping it into a {@link FingerprintManager.CryptoObject}, invoking
		* {@code FingerprintManager.authenticate} with {@code CryptoObject}, and proceeding with
		* with the key, wrapping it into a {@link BiometricPrompt.CryptoObject}, invoking
		* {@code BiometricPrompt.authenticate} with {@code CryptoObject}, and proceeding with
		* the cryptographic operation only if the authentication flow succeeds.
		*
		* <p>Cryptographic operations involving keys which are authorized to be used for a duration
		@@ -1183,8 +1184,8 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		* for every use of the key.
		*
		* @see #setUserAuthenticationRequired(boolean)
		* @see FingerprintManager
		* @see FingerprintManager.CryptoObject
		* @see BiometricPrompt
		* @see BiometricPrompt.CryptoObject
		* @see KeyguardManager
		*/
		@NonNull
		@@ -1286,20 +1287,20 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		}

		/**
		* Sets whether this key should be invalidated on fingerprint enrollment. This
		* Sets whether this key should be invalidated on biometric enrollment. This
		* applies only to keys which require user authentication (see {@link
		* #setUserAuthenticationRequired(boolean)}) and if no positive validity duration has been
		* set (see {@link #setUserAuthenticationValidityDurationSeconds(int)}, meaning the key is
		* valid for fingerprint authentication only.
		* valid for biometric authentication only.
		*
		* <p>By default, {@code invalidateKey} is {@code true}, so keys that are valid for
		* fingerprint authentication only are <em>irreversibly invalidated</em> when a new
		* fingerprint is enrolled, or when all existing fingerprints are deleted. That may be
		* biometric authentication only are <em>irreversibly invalidated</em> when a new
		* biometric is enrolled, or when all existing biometrics are deleted. That may be
		* changed by calling this method with {@code invalidateKey} set to {@code false}.
		*
		* <p>Invalidating keys on enrollment of a new finger or unenrollment of all fingers
		* <p>Invalidating keys on enrollment of a new biometric or unenrollment of all biometrics
		* improves security by ensuring that an unauthorized person who obtains the password can't
		* gain the use of fingerprint-authenticated keys by enrolling their own finger. However,
		* gain the use of biometric-authenticated keys by enrolling their own biometric. However,
		* invalidating keys makes key-dependent operations impossible, requiring some fallback
		* procedure to authenticate the user and set up a new key.
		*/
		@@ -1322,7 +1323,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
		* Sets whether the keystore requires the screen to be unlocked before allowing decryption
		* using this key. If this is set to {@code true}, any attempt to decrypt or sign using this
		* key while the screen is locked will fail. A locked device requires a PIN, password,
		* fingerprint, or other trusted factor to access. While the screen is locked, the key can
		* biometric, or other trusted factor to access. While the screen is locked, the key can
		* still be used for encryption or signature verification.
		*/
		@NonNull

keystore/java/android/security/keystore/KeyProtection.java

+26 −25

Original line number	Diff line number	Diff line
		@@ -21,12 +21,13 @@ import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.annotation.TestApi;
		import android.app.KeyguardManager;
		import android.hardware.fingerprint.FingerprintManager;
		import android.hardware.biometrics.BiometricManager;
		import android.hardware.biometrics.BiometricPrompt;
		import android.security.GateKeeper;

		import java.security.Key;
		import java.security.Signature;
		import java.security.KeyStore.ProtectionParameter;
		import java.security.Signature;
		import java.security.cert.Certificate;
		import java.util.Date;

		@@ -479,9 +480,9 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		}

		/**
		* Returns {@code true} if the key is irreversibly invalidated when a new fingerprint is
		* enrolled or all enrolled fingerprints are removed. This has effect only for keys that
		* require fingerprint user authentication for every use.
		* Returns {@code true} if the key is irreversibly invalidated when a new biometric is
		* enrolled or all enrolled biometrics are removed. This has effect only for keys that
		* require biometric user authentication for every use.
		*
		* @see #isUserAuthenticationRequired()
		* @see #getUserAuthenticationValidityDurationSeconds()
		@@ -496,7 +497,7 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		*
		* Normally an authentication-bound key is tied to the secure user id of the current user
		* (either the root SID from GateKeeper for auth-bound keys with a timeout, or the authenticator
		* id of the current fingerprint set for keys requiring explicit fingerprint authorization).
		* id of the current biometric set for keys requiring explicit biometric authorization).
		* If this parameter is set (this method returning non-zero value), the key should be tied to
		* the specified secure user id, overriding the logic above.
		*
		@@ -762,19 +763,19 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		* <li>The key can only be import if secure lock screen is set up (see
		* {@link KeyguardManager#isDeviceSecure()}). Additionally, if the key requires that user
		* authentication takes place for every use of the key (see
		* {@link #setUserAuthenticationValidityDurationSeconds(int)}), at least one fingerprint
		* must be enrolled (see {@link FingerprintManager#hasEnrolledFingerprints()}).</li>
		* {@link #setUserAuthenticationValidityDurationSeconds(int)}), at least one biometric
		* must be enrolled (see {@link BiometricManager#canAuthenticate()}).</li>
		* <li>The use of the key must be authorized by the user by authenticating to this Android
		* device using a subset of their secure lock screen credentials such as
		* password/PIN/pattern or fingerprint.
		* password/PIN/pattern or biometric.
		* <a href="{@docRoot}training/articles/keystore.html#UserAuthentication">More
		* information</a>.
		* <li>The key will become <em>irreversibly invalidated</em> once the secure lock screen is
		* disabled (reconfigured to None, Swipe or other mode which does not authenticate the user)
		* or when the secure lock screen is forcibly reset (e.g., by a Device Administrator).
		* Additionally, if the key requires that user authentication takes place for every use of
		* the key, it is also irreversibly invalidated once a new fingerprint is enrolled or once\
		* no more fingerprints are enrolled, unless {@link
		* the key, it is also irreversibly invalidated once a new biometric is enrolled or once\
		* no more biometrics are enrolled, unless {@link
		* #setInvalidatedByBiometricEnrollment(boolean)} is used to allow validity after
		* enrollment. Attempts to initialize cryptographic operations using such keys will throw
		* {@link KeyPermanentlyInvalidatedException}.</li> </ul>
		@@ -784,7 +785,7 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		*
		* @see #setUserAuthenticationValidityDurationSeconds(int)
		* @see KeyguardManager#isDeviceSecure()
		* @see FingerprintManager#hasEnrolledFingerprints()
		* @see BiometricManager#canAuthenticate()
		*/
		@NonNull
		public Builder setUserAuthenticationRequired(boolean required) {
		@@ -824,10 +825,10 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		* the key.
		*
		* <p>Cryptographic operations involving keys which require user authentication to take
		* place for every operation can only use fingerprint authentication. This is achieved by
		* place for every operation can only use biometric authentication. This is achieved by
		* initializing a cryptographic operation ({@link Signature}, {@link Cipher}, {@link Mac})
		* with the key, wrapping it into a {@link FingerprintManager.CryptoObject}, invoking
		* {@code FingerprintManager.authenticate} with {@code CryptoObject}, and proceeding with
		* with the key, wrapping it into a {@link BiometricPrompt.CryptoObject}, invoking
		* {@code BiometricPrompt.authenticate} with {@code CryptoObject}, and proceeding with
		* the cryptographic operation only if the authentication flow succeeds.
		*
		* <p>Cryptographic operations involving keys which are authorized to be used for a duration
		@@ -846,8 +847,8 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		* for every use of the key.
		*
		* @see #setUserAuthenticationRequired(boolean)
		* @see FingerprintManager
		* @see FingerprintManager.CryptoObject
		* @see BiometricPrompt
		* @see BiometricPrompt.CryptoObject
		* @see KeyguardManager
		*/
		@NonNull
		@@ -902,20 +903,20 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		}

		/**
		* Sets whether this key should be invalidated on fingerprint enrollment. This
		* Sets whether this key should be invalidated on biometric enrollment. This
		* applies only to keys which require user authentication (see {@link
		* #setUserAuthenticationRequired(boolean)}) and if no positive validity duration has been
		* set (see {@link #setUserAuthenticationValidityDurationSeconds(int)}, meaning the key is
		* valid for fingerprint authentication only.
		* valid for biometric authentication only.
		*
		* <p>By default, {@code invalidateKey} is {@code true}, so keys that are valid for
		* fingerprint authentication only are <em>irreversibly invalidated</em> when a new
		* fingerprint is enrolled, or when all existing fingerprints are deleted. That may be
		* biometric authentication only are <em>irreversibly invalidated</em> when a new
		* biometric is enrolled, or when all existing biometrics are deleted. That may be
		* changed by calling this method with {@code invalidateKey} set to {@code false}.
		*
		* <p>Invalidating keys on enrollment of a new finger or unenrollment of all fingers
		* <p>Invalidating keys on enrollment of a new biometric or unenrollment of all biometrics
		* improves security by ensuring that an unauthorized person who obtains the password can't
		* gain the use of fingerprint-authenticated keys by enrolling their own finger. However,
		* gain the use of biometric-authenticated keys by enrolling their own biometric. However,
		* invalidating keys makes key-dependent operations impossible, requiring some fallback
		* procedure to authenticate the user and set up a new key.
		*/
		@@ -930,7 +931,7 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		*
		* Normally an authentication-bound key is tied to the secure user id of the current user
		* (either the root SID from GateKeeper for auth-bound keys with a timeout, or the
		* authenticator id of the current fingerprint set for keys requiring explicit fingerprint
		* authenticator id of the current biometric set for keys requiring explicit biometric
		* authorization). If this parameter is set (this method returning non-zero value), the key
		* should be tied to the specified secure user id, overriding the logic above.
		*
		@@ -964,7 +965,7 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
		* Sets whether the keystore requires the screen to be unlocked before allowing decryption
		* using this key. If this is set to {@code true}, any attempt to decrypt or sign using this
		* key while the screen is locked will fail. A locked device requires a PIN, password,
		* fingerprint, or other trusted factor to access. While the screen is locked, the key can
		* biometric, or other trusted factor to access. While the screen is locked, the key can
		* still be used for encryption or signature verification.
		*/
		@NonNull