keystore: Add documentation for user presence required.

Test: make -j50 docs
Bug: 77600728
Change-Id: I6334bc0fc7a7d4faced6b03522c350ce74303443
Signed-off-by: Allen Webb <allenwebb@google.com>

2 files changed, 31 insertions, 2 deletions

diff --git a/keystore/java/android/security/keystore/KeyGenParameterSpec.java b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
index 58332a20093f..b2e0f675f5f9 100644
--- a/keystore/java/android/security/keystore/KeyGenParameterSpec.java
+++ b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
@@ -595,6 +595,14 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
     /**
      * Returns {@code true} if the key is authorized to be used only if a test of user presence has
      * been performed between the {@code Signature.initSign()} and {@code Signature.sign()} calls.
+     * It requires that the KeyStore implementation have a direct way to validate the user presence
+     * for example a KeyStore hardware backed strongbox can use a button press that is observable
+     * in hardware. A test for user presence is tangential to authentication. The test can be part
+     * of an authentication step as long as this step can be validated by the hardware protecting
+     * the key and cannot be spoofed. For example, a physical button press can be used as a test of
+     * user presence if the other pins connected to the button are not able to simulate a button
+     * press. There must be no way for the primary processor to fake a button press, or that
+     * button must not be used as a test of user presence.
      */
     public boolean isUserPresenceRequired() {
         return mUserPresenceRequired;
@@ -1181,6 +1189,14 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec, UserAu
         /**
          * Sets whether a test of user presence is required to be performed between the
          * {@code Signature.initSign()} and {@code Signature.sign()} method calls.
+         * It requires that the KeyStore implementation have a direct way to validate the user
+         * presence for example a KeyStore hardware backed strongbox can use a button press that
+         * is observable in hardware. A test for user presence is tangential to authentication. The
+         * test can be part of an authentication step as long as this step can be validated by the
+         * hardware protecting the key and cannot be spoofed. For example, a physical button press
+         * can be used as a test of user presence if the other pins connected to the button are not
+         * able to simulate a button press.There must be no way for the primary processor to fake a
+         * button press, or that button must not be used as a test of user presence.
          */
         @NonNull
         public Builder setUserPresenceRequired(boolean required) {
diff --git a/keystore/java/android/security/keystore/KeyProtection.java b/keystore/java/android/security/keystore/KeyProtection.java
index 92bee8dec819..fdcad85bd70d 100644
--- a/keystore/java/android/security/keystore/KeyProtection.java
+++ b/keystore/java/android/security/keystore/KeyProtection.java
@@ -448,7 +448,12 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
      * been performed between the {@code Signature.initSign()} and {@code Signature.sign()} calls.
      * It requires that the KeyStore implementation have a direct way to validate the user presence
      * for example a KeyStore hardware backed strongbox can use a button press that is observable
-     * in hardware.
+     * in hardware. A test for user presence is tangential to authentication. The test can be part
+     * of an authentication step as long as this step can be validated by the hardware protecting
+     * the key and cannot be spoofed. For example, a physical button press can be used as a test of
+     * user presence if the other pins connected to the button are not able to simulate a button
+     * press. There must be no way for the primary processor to fake a button press, or that
+     * button must not be used as a test of user presence.
      */
     public boolean isUserPresenceRequired() {
         return mUserPresenceRequred;
@@ -845,7 +850,15 @@ public final class KeyProtection implements ProtectionParameter, UserAuthArgs {
 
         /**
          * Sets whether a test of user presence is required to be performed between the
-         * {@code Signature.initSign()} and {@code Signature.sign()} method calls.
+         * {@code Signature.initSign()} and {@code Signature.sign()} method calls. It requires that
+         * the KeyStore implementation have a direct way to validate the user presence for example
+         * a KeyStore hardware backed strongbox can use a button press that is observable in
+         * hardware. A test for user presence is tangential to authentication. The test can be part
+         * of an authentication step as long as this step can be validated by the hardware
+         * protecting the key and cannot be spoofed. For example, a physical button press can be
+         * used as a test of user presence if the other pins connected to the button are not able
+         * to simulate a button press. There must be no way for the primary processor to fake a
+         * button press, or that button must not be used as a test of user presence.
          */
         @NonNull
         public Builder setUserPresenceRequired(boolean required) {