Update semantics of on-body Keystore API.
Architectural changes from the Wear team have required changes to the
semantics of the Keystore on-body feature. Although no devices will
actually implement this feature until the release of new Wear devices
with the necessary sensors, we need to get the API documentation right
now.
Bug: 29369151
Change-Id: I857e00928f994a1337313123eae7e00534c53c3c
diff --git a/keystore/java/android/security/keystore/KeyGenParameterSpec.java b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
index 869262f..cbef540 100644
--- a/keystore/java/android/security/keystore/KeyGenParameterSpec.java
+++ b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
@@ -596,10 +596,10 @@
}
/**
- * Returns {@code true} if the key will remain authorized while the device is on the user's
- * body, even after the validity duration has expired. This option has no effect on keys that
- * don't have an authentication validity duration, and has no effect if the device lacks a
- * secure on-body sensor.
+ * Returns {@code true} if the key will remain authorized only until the device is removed from
+ * the user's body, up to the validity duration. This option has no effect on keys that don't
+ * have an authentication validity duration, and has no effect if the device lacks an on-body
+ * sensor.
*
* <p>Authorization applies only to secret key and private key operations. Public key operations
* are not restricted.
@@ -1104,26 +1104,21 @@
}
/**
- * Sets whether the key is authorized for use after the authentication validity period is
- * expired (see {@link #setUserAuthenticationValidityDurationSeconds} and {@link
- * #setUserAuthenticationRequired}) if the device has a secure on-body sensor and if the
- * device has not been removed from the user's body since the last successful
- * authentication.
+ * Sets whether the key will remain authorized only until the device is removed from the
+ * user's body up to the limit of the authentication validity period (see
+ * {@link #setUserAuthenticationValidityDurationSeconds} and
+ * {@link #setUserAuthenticationRequired}). Once the device has been removed from the
+ * user's body, the key will be considered unauthorized and the user will need to
+ * re-authenticate to use it. For keys without an authentication validity period this
+ * parameter has no effect.
*
- * <p>On devices that do not have a secure on-body sensor, creating a key with this
- * parameter set to {@code true} will have no effect; the private or secret key will no
- * longer be authorized for use after the validity period ends, and a fresh authentication
- * will be required to use it again.
+ * <p>Similarly, on devices that do not have an on-body sensor, this parameter will have no
+ * effect; the device will always be considered to be "on-body" and the key will therefore
+ * remain authorized until the validity period ends.
*
- * <p>Note that "secure" on-body sensors are required by Android to have a secure path to
- * the secure hardware, but the sensors themselves may not be difficult to fool. It is
- * recommended that this feature be used to increase slightly the security of keys which
- * would otherwise have to allow unauthenticated access, or have a very long validity
- * period. Keys that require high assurance of user authorization should not use this
- * feature and should set a short validity period.
- *
- * @param remainsValid if {@code true}, and if the device supports secure on-body detection,
- * key will remain valid after authentication validity duration has expired.
+ * @param remainsValid if {@code true}, and if the device supports on-body detection, key
+ * will be invalidated when the device is removed from the user's body or when the
+ * authentication validity expires, whichever occurs first.
*/
@NonNull
public Builder setUserAuthenticationValidWhileOnBody(boolean remainsValid) {
diff --git a/keystore/java/android/security/keystore/KeyInfo.java b/keystore/java/android/security/keystore/KeyInfo.java
index fa6d8b3..f553319 100644
--- a/keystore/java/android/security/keystore/KeyInfo.java
+++ b/keystore/java/android/security/keystore/KeyInfo.java
@@ -285,10 +285,10 @@
}
/**
- * Returns {@code true} if this key will remain usable after its specified validity duration
- * for as long as the device remains on the user's body. This is possible only for keys with
- * a specified validity duration. Always returns {@code false} on devices that lack a secure
- * on-body sensor.
+ * Returns {@code true} if this key will become unusable when the device is removed from the
+ * user's body. This is possible only for keys with a specified validity duration, and only on
+ * devices with an on-body sensor. Always returns {@code false} on devices that lack an on-body
+ * sensor.
*/
public boolean isUserAuthenticationValidWhileOnBody() {
return mUserAuthenticationValidWhileOnBody;
diff --git a/keystore/java/android/security/keystore/KeyProtection.java b/keystore/java/android/security/keystore/KeyProtection.java
index a5fb833..e70d33a 100644
--- a/keystore/java/android/security/keystore/KeyProtection.java
+++ b/keystore/java/android/security/keystore/KeyProtection.java
@@ -407,10 +407,9 @@
}
/**
- * Returns {@code true} if the key will remain authorized while the device is on the user's
- * body, even after the validity duration has expired. This option has no effect on keys that
- * don't have an authentication validity duration, and has no effect if the device lacks a
- * secure on-body sensor.
+ * Returns {@code true} if the key will be de-authorized when the device is removed from the
+ * user's body. This option has no effect on keys that don't have an authentication validity
+ * duration, and has no effect if the device lacks an on-body sensor.
*
* <p>Authorization applies only to secret key and private key operations. Public key operations
* are not restricted.
@@ -728,26 +727,21 @@
}
/**
- * Sets whether the key is authorized for use after the authentication validity period is
- * expired (see {@link #setUserAuthenticationValidityDurationSeconds} and {@link
- * #setUserAuthenticationRequired}) if the device has a secure on-body sensor and if the
- * device has not been removed from the user's body since the last successful
- * authentication.
+ * Sets whether the key will remain authorized only until the device is removed from the
+ * user's body up to the limit of the authentication validity period (see
+ * {@link #setUserAuthenticationValidityDurationSeconds} and
+ * {@link #setUserAuthenticationRequired}). Once the device has been removed from the
+ * user's body, the key will be considered unauthorized and the user will need to
+ * re-authenticate to use it. For keys without an authentication validity period this
+ * parameter has no effect.
*
- * <p>On devices that do not have a secure on-body sensor, creating a key with this
- * parameter set to {@code true} will have no effect; the private or secret key will no
- * longer be authorized for use after the validity period ends, and a fresh authentication
- * will be required to use it again.
+ * <p>Similarly, on devices that do not have an on-body sensor, this parameter will have no
+ * effect; the device will always be considered to be "on-body" and the key will therefore
+ * remain authorized until the validity period ends.
*
- * <p>Note that "secure" on-body sensors are required by Android to have a secure path to
- * the secure hardware, but the sensors themselves may not be difficult to fool. It is
- * recommended that this feature be used to increase slightly the security of keys which
- * would otherwise have to allow unauthenticated access, or have a very long validity
- * period. Keys that require high assurance of user authorization should not use this
- * feature and should set a short validity period.
- *
- * @param remainsValid if {@code true}, and if the device supports secure on-body detection,
- * key will remain valid after authentication validity duration has expired.
+ * @param remainsValid if {@code true}, and if the device supports on-body detection, key
+ * will be invalidated when the device is removed from the user's body or when the
+ * authentication validity expires, whichever occurs first.
*/
@NonNull
public Builder setUserAuthenticationValidWhileOnBody(boolean remainsValid) {