From 0bc50f944204c33ef0839134bcdd76a9e4badbe9 Mon Sep 17 00:00:00 2001
From: Eran Messeri <eranm@google.com>
Date: Fri, 1 Jun 2018 16:03:39 +0100
Subject: Improve KeyChain documentation

Improve the choosePrivateKeyAlias documentation by:
(1) removing reference to host+port when a URI is being passed in.
(2) Clearing up the language about what a DPC can do.

Test: N/A
Bug: 81522642
Change-Id: I12fbf675536ea5d843dd2eec4f0379daad764bb6
---
 keystore/java/android/security/KeyChain.java | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

(limited to 'keystore/java/android/security/KeyChain.java')

diff --git a/keystore/java/android/security/KeyChain.java b/keystore/java/android/security/KeyChain.java
index 066e17ccb31d..030fa60abfd3 100644
--- a/keystore/java/android/security/KeyChain.java
+++ b/keystore/java/android/security/KeyChain.java
@@ -352,8 +352,11 @@ public final class KeyChain {
      * selected alias or null will be returned via the
      * KeyChainAliasCallback callback.
      *
-     * <p>The device or profile owner can intercept this before the activity
-     * is shown, to pick a specific private key alias.
+     * <p>A device policy controller (as a device or profile owner) can
+     * intercept the request before the activity is shown, to pick a
+     * specific private key alias by implementing
+     * {@link android.app.admin.DeviceAdminReceiver#onChoosePrivateKeyAlias
+     * onChoosePrivateKeyAlias}.
      *
      * <p>{@code keyTypes} and {@code issuers} may be used to
      * highlight suggested choices to the user, although to cope with
@@ -363,7 +366,7 @@ public final class KeyChain {
      * <p>{@code host} and {@code port} may be used to give the user
      * more context about the server requesting the credentials.
      *
-     * <p>{@code alias} allows the chooser to preselect an existing
+     * <p>{@code alias} allows the caller to preselect an existing
      * alias which will still be subject to user confirmation.
      *
      * @param activity The {@link Activity} context to use for
@@ -403,18 +406,21 @@ public final class KeyChain {
      * selected alias or null will be returned via the
      * KeyChainAliasCallback callback.
      *
-     * <p>The device or profile owner can intercept this before the activity
-     * is shown, to pick a specific private key alias.</p>
+     * <p>A device policy controller (as a device or profile owner) can
+     * intercept the request before the activity is shown, to pick a
+     * specific private key alias by implementing
+     * {@link android.app.admin.DeviceAdminReceiver#onChoosePrivateKeyAlias
+     * onChoosePrivateKeyAlias}.
      *
      * <p>{@code keyTypes} and {@code issuers} may be used to
      * highlight suggested choices to the user, although to cope with
      * sometimes erroneous values provided by servers, the user may be
      * able to override these suggestions.
      *
-     * <p>{@code host} and {@code port} may be used to give the user
-     * more context about the server requesting the credentials.
+     * <p>{@code uri} may be used to give the user more context about
+     * the server requesting the credentials.
      *
-     * <p>{@code alias} allows the chooser to preselect an existing
+     * <p>{@code alias} allows the caller to preselect an existing
      * alias which will still be subject to user confirmation.
      *
      * @param activity The {@link Activity} context to use for
-- 
cgit v1.2.3