From 55b8d082ba1f8ab4e541469e8d4def2a5f1ea146 Mon Sep 17 00:00:00 2001 From: Eran Messeri Date: Thu, 31 Jan 2019 16:25:52 +0000 Subject: [PATCH] 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 --- .../app/admin/DevicePolicyManager.java | 16 +++++++++ keystore/java/android/security/KeyChain.java | 33 +++++++++++++------ 2 files changed, 39 insertions(+), 10 deletions(-) diff --git a/core/java/android/app/admin/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java index 3ff6973a09ffe..db7aef19507d1 100644 --- a/core/java/android/app/admin/DevicePolicyManager.java +++ b/core/java/android/app/admin/DevicePolicyManager.java @@ -4618,6 +4618,10 @@ public class DevicePolicyManager { *

If the installer must have access to the credentials, call * {@link #installKeyPair(ComponentName, PrivateKey, Certificate[], String, boolean)} instead. * + *

Note: If the provided {@code alias} is of an existing alias, all former grants that apps + * have been given to access the key and certificates associated with this alias will be + * revoked. + * * @param admin Which {@link DeviceAdminReceiver} this request is associated with, or * {@code null} if calling from a delegated certificate installer. * @param privKey The private key to install. @@ -4645,6 +4649,10 @@ public class DevicePolicyManager { * immediately, without user approval. It is a best practice not to request this unless strictly * necessary since it opens up additional security vulnerabilities. * + *

Note: If the provided {@code alias} is of an existing alias, all former grants that apps + * have been given to access the key and certificates associated with this alias will be + * revoked. + * * @param admin Which {@link DeviceAdminReceiver} this request is associated with, or * {@code null} if calling from a delegated certificate installer. * @param privKey The private key to install. @@ -4685,6 +4693,10 @@ public class DevicePolicyManager { *

Include {@link #INSTALLKEY_SET_USER_SELECTABLE} in the {@code flags} argument to allow * the user to select the key from a dialog. * + *

Note: If the provided {@code alias} is of an existing alias, all former grants that apps + * have been given to access the key and certificates associated with this alias will be + * revoked. + * * @param admin Which {@link DeviceAdminReceiver} this request is associated with, or * {@code null} if calling from a delegated certificate installer. * @param privKey The private key to install. @@ -4761,6 +4773,10 @@ public class DevicePolicyManager { *

Because this method might take several seconds to complete, it should only be called from * a worker thread. This method returns {@code null} when called from the main thread. * + *

Note: If the provided {@code alias} is of an existing alias, all former grants that apps + * have been given to access the key and certificates associated with this alias will be + * revoked. + * * @param admin Which {@link DeviceAdminReceiver} this request is associated with, or * {@code null} if calling from a delegated certificate installer. * @param algorithm The key generation algorithm, see {@link java.security.KeyPairGenerator}. diff --git a/keystore/java/android/security/KeyChain.java b/keystore/java/android/security/KeyChain.java index 5d5e40fd3ac3f..eb169be06025d 100644 --- a/keystore/java/android/security/KeyChain.java +++ b/keystore/java/android/security/KeyChain.java @@ -18,8 +18,8 @@ package android.security; 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.Intent; 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.os.UserHandle; 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 java.util.concurrent.LinkedBlockingQueue; 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 @@ public final class KeyChain { * * @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 @@ public final class KeyChain { } /** - * 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). * *

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 @@ public final class KeyChain { * 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()}. * + *

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. + *

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 @@ public final class KeyChain { } /** - * 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}). + * *

* Note: 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 @@ public final class KeyChain { *

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()}. + *

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}.