From 0693727cfb7ab0762da82f084272978aa8af6887 Mon Sep 17 00:00:00 2001
From: David Zeuthen <zeuthen@google.com>
Date: Thu, 3 Mar 2022 11:12:21 -0500
Subject: [PATCH] identity: Add clarifications to newly added API.

Bug: 216319624
Test: Compiles
Change-Id: I9e80506cae4799c19f6ea21dc4f2b75981f1ab9d
---
 .../identity/CredentialDataRequest.java       | 28 +++++++++++++++++--
 .../identity/PresentationSession.java         |  3 ++
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/identity/java/android/security/identity/CredentialDataRequest.java b/identity/java/android/security/identity/CredentialDataRequest.java
index 2a47a02405e0..3482384a1fd9 100644
--- a/identity/java/android/security/identity/CredentialDataRequest.java
+++ b/identity/java/android/security/identity/CredentialDataRequest.java
@@ -153,7 +153,15 @@ public class CredentialDataRequest {
         /**
          * Sets whether to allow using an authentication key which use count has been exceeded.
          *
-         * By default this is set to true.
+         * <p>This is useful in situations where the application hasn't had a chance to renew
+         * authentication keys, for example if the device hasn't been connected to the Internet or
+         * if the issuing authority server has been down.
+         *
+         * <p>The reason this could be useful is that the privacy risk of reusing an authentication
+         * key for a credential presentation could be significantly smaller compared to the
+         * inconvenience of not being able to present the credential at all.
+         *
+         * <p>By default this is set to true.
          *
          * @param allowUsingExhaustedKeys whether to allow using an authentication key which use
          *                                count has been exceeded if no other key is available.
@@ -167,7 +175,16 @@ public class CredentialDataRequest {
         /**
          * Sets whether to allow using an authentication key which is expired.
          *
-         * By default this is set to false.
+         * <p>This is useful in situations where the application hasn't had a chance to renew
+         * authentication keys, for example if the device hasn't been connected to the Internet or
+         * if the issuing authority server has been down.
+         *
+         * <p>The reason this could be useful is that many verifiers are likely to accept a
+         * credential presentation using an expired authentication key (the credential itself
+         * wouldn't be expired) and it's likely better for the holder to be able to do this than
+         * not present their credential at all.
+         *
+         * <p>By default this is set to false.
          *
          * @param allowUsingExpiredKeys whether to allow using an authentication key which is
          *                              expired if no other key is available.
@@ -181,7 +198,12 @@ public class CredentialDataRequest {
         /**
          * Sets whether to increment the use-count for the authentication key used.
          *
-         * By default this is set to true.
+         * <p>Not incrementing the use-count for an authentication key is useful in situations
+         * where the authentication key is known with certainty to not be leaked. For example,
+         * consider an application doing a credential presentation for the sole purpose of
+         * displaying the credential data to the user (not for verification).
+         *
+         * <p>By default this is set to true.
          *
          * @param incrementUseCount whether to increment the use count of the authentication
          *                          key used.
diff --git a/identity/java/android/security/identity/PresentationSession.java b/identity/java/android/security/identity/PresentationSession.java
index afaafce32798..6cde611fcd63 100644
--- a/identity/java/android/security/identity/PresentationSession.java
+++ b/identity/java/android/security/identity/PresentationSession.java
@@ -26,6 +26,9 @@ import java.security.PublicKey;
 /**
  * Class for presenting multiple documents to a remote verifier.
  *
+ * <p>This should be used for all interactions with a remote verifier instead of the now deprecated
+ * {@link IdentityCredential#getEntries(byte[], Map, byte[], byte[])} method.
+ *
  * Use {@link IdentityCredentialStore#createPresentationSession(int)} to create a {@link
  * PresentationSession} instance.
  */