Update CryptoUpcalls documentation

Explain clearly why this class exists. This explains about
hardware-backed keys in more detail.

Change-Id: I960960c3176bdf7a39ededbd4744bb29377db5ea
diff --git a/src/main/java/org/conscrypt/CryptoUpcalls.java b/src/main/java/org/conscrypt/CryptoUpcalls.java
index a39aaad..3a17f56 100644
--- a/src/main/java/org/conscrypt/CryptoUpcalls.java
+++ b/src/main/java/org/conscrypt/CryptoUpcalls.java
@@ -28,7 +28,10 @@
 
 /**
  * Provides a place where NativeCrypto can call back up to do Java language
- * calls to work on delegated key types from native code.
+ * calls to work on delegated key types from native code. Delegated keys are
+ * usually backed by hardware so we don't have access directly to the private
+ * key material. If it were a key where we can get to the private key, we
+ * would not ever call into this class.
  */
 public final class CryptoUpcalls {
 
@@ -75,7 +78,9 @@
 
         Signature signature;
 
-        // First try to get the most preferred provider as long as it isn't us.
+        // Since this is a delegated key, we cannot handle providing a signature using this key.
+        // Otherwise we wouldn't end up in this classs in the first place. The first step is to
+        // try to get the most preferred provider as long as it isn't us.
         try {
             signature = Signature.getInstance(algorithm);
             signature.initSign(javaKey);
@@ -151,7 +156,9 @@
         String transformation = "RSA/ECB/" + jcaPadding;
         Cipher c = null;
 
-        // First try to get the most preferred provider as long as it isn't us.
+        // Since this is a delegated key, we cannot handle providing a cipher using this key.
+        // Otherwise we wouldn't end up in this classs in the first place. The first step is to
+        // try to get the most preferred provider as long as it isn't us.
         try {
             c = Cipher.getInstance(transformation);
             c.init(Cipher.DECRYPT_MODE, javaKey);