KeyChain: Improve key override documentation.
Improve the documentation on the case of key override: When a new key is
generated/installed using an alias that already exists.
In particular, clarify that grants are lost and that a new call to
KeyChain.choosePrivateKeyAlias must be issued in this case.
Bug: 123563258
Test: that it builds.
Change-Id: I055e95f57b9576883736ca0cfa6a998dec08a6c2
diff --git a/keystore/java/android/security/KeyChain.java b/keystore/java/android/security/KeyChain.java
index 5d5e40f..eb169be 100644
--- a/keystore/java/android/security/KeyChain.java
+++ b/keystore/java/android/security/KeyChain.java
@@ -18,8 +18,8 @@
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.SdkConstant;
-import android.annotation.WorkerThread;
import android.annotation.SdkConstant.SdkConstantType;
+import android.annotation.WorkerThread;
import android.app.Activity;
import android.app.PendingIntent;
import android.app.Service;
@@ -29,7 +29,6 @@
import android.content.ServiceConnection;
import android.net.Uri;
import android.os.Binder;
-import android.os.Build;
import android.os.IBinder;
import android.os.Looper;
import android.os.Process;
@@ -38,6 +37,8 @@
import android.security.keystore.AndroidKeyStoreProvider;
import android.security.keystore.KeyProperties;
+import com.android.org.conscrypt.TrustedCertificateStore;
+
import java.io.ByteArrayInputStream;
import java.io.Closeable;
import java.io.Serializable;
@@ -58,8 +59,6 @@
import javax.security.auth.x500.X500Principal;
-import com.android.org.conscrypt.TrustedCertificateStore;
-
/**
* The {@code KeyChain} class provides access to private keys and
* their corresponding certificate chains in credential storage.
@@ -214,8 +213,8 @@
*
* @deprecated Use {@link #ACTION_KEYCHAIN_CHANGED}, {@link #ACTION_TRUST_STORE_CHANGED} or
* {@link #ACTION_KEY_ACCESS_CHANGED}. Apps that target a version higher than
- * {@link Build.VERSION_CODES#N_MR1} will only receive this broadcast if they register for it
- * at runtime.
+ * {@link android.os.Build.VERSION_CODES#N_MR1} will only receive this broadcast if they
+ * register for it at runtime.
*/
@SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
public static final String ACTION_STORAGE_CHANGED = "android.security.STORAGE_CHANGED";
@@ -532,8 +531,8 @@
}
/**
- * Returns the {@code PrivateKey} for the requested alias, or null
- * if there is no result.
+ * Returns the {@code PrivateKey} for the requested alias, or null if the alias does not exist
+ * or the caller has no permission to access it (see note on exceptions below).
*
* <p> This method may block while waiting for a connection to another process, and must never
* be called from the main thread.
@@ -541,6 +540,15 @@
* at any time from the main thread, it is safer to rely on a long-lived context such as one
* returned from {@link Context#getApplicationContext()}.
*
+ * <p> If the caller provides a valid alias to which it was not granted access, then the
+ * caller must invoke {@link #choosePrivateKeyAlias} again to get another valid alias
+ * or a grant to access the same alias.
+ * <p>On Android versions prior to Q, when a key associated with the specified alias is
+ * unavailable, the method will throw a {@code KeyChainException} rather than return null.
+ * If the exception's cause (as obtained by calling {@code KeyChainException.getCause()})
+ * is a throwable of type {@code IllegalStateException} then the caller lacks a grant
+ * to access the key and certificates associated with this alias.
+ *
* @param alias The alias of the desired private key, typically returned via
* {@link KeyChainAliasCallback#alias}.
* @throws KeyChainException if the alias was valid but there was some problem accessing it.
@@ -591,8 +599,10 @@
}
/**
- * Returns the {@code X509Certificate} chain for the requested
- * alias, or null if there is no result.
+ * Returns the {@code X509Certificate} chain for the requested alias, or null if the alias
+ * does not exist or the caller has no permission to access it (see note on exceptions
+ * in {@link #getPrivateKey}).
+ *
* <p>
* <strong>Note:</strong> If a certificate chain was explicitly specified when the alias was
* installed, this method will return that chain. If only the client certificate was specified
@@ -604,6 +614,9 @@
* <p> As {@link Activity} and {@link Service} contexts are short-lived and can be destroyed
* at any time from the main thread, it is safer to rely on a long-lived context such as one
* returned from {@link Context#getApplicationContext()}.
+ * <p> In case the caller specifies an alias for which it lacks a grant, it must call
+ * {@link #choosePrivateKeyAlias} again. See {@link #getPrivateKey} for more details on
+ * coping with this scenario.
*
* @param alias The alias of the desired certificate chain, typically
* returned via {@link KeyChainAliasCallback#alias}.