More Javadocs for AndroidKeyStore public classes.

This adds more detailed class-level Javadocs (incl. examples) for the
following public API of Android KeyStore facility:
* KeyPairGeneratorSpec,
* KeyGeneratorSpec,
* KeyStoreParameter,
* KeyStoreKeySpec.

This also clarifies what encryption at rest means.

Bug: 18088752
Change-Id: I9951a528c34dea322534763b596902a2b6ac64f9

1 files changed, 38 insertions, 1 deletions

diff --git a/keystore/java/android/security/KeyStoreKeySpec.java b/keystore/java/android/security/KeyStoreKeySpec.java
index a630a0a42837..0a9acbb43698 100644
--- a/keystore/java/android/security/KeyStoreKeySpec.java
+++ b/keystore/java/android/security/KeyStoreKeySpec.java
@@ -16,12 +16,49 @@
 
 package android.security;
 
+import java.security.PrivateKey;
 import java.security.spec.KeySpec;
 import java.util.Date;
 
+import javax.crypto.SecretKey;
+
 /**
  * Information about a key from the <a href="{@docRoot}training/articles/keystore.html">Android
- * KeyStore</a>.
+ * KeyStore</a>. This class describes whether the key material is available in
+ * plaintext outside of secure hardware, whether user authentication is required for using the key
+ * and whether this requirement is enforced by secure hardware, the key's origin, what uses the key
+ * is authorized for (e.g., only in {@code CBC} mode, or signing only), whether the key should be
+ * encrypted at rest, the key's and validity start and end dates.
+ *
+ * <p><h3>Example: Symmetric Key</h3>
+ * The following example illustrates how to obtain a {@link KeyStoreKeySpec} describing the provided
+ * Android KeyStore {@link SecretKey}.
+ * <pre> {@code
+ * SecretKey key = ...; // Android KeyStore key
+ *
+ * SecretKeyFactory factory = SecretKeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
+ * KeyStoreKeySpec spec;
+ * try &#123;
+ *     spec = (KeyStoreKeySpec) factory.getKeySpec(key, KeyStoreKeySpec.class);
+ * &#125; catch (InvalidKeySpecException e) &#123;
+ *     // Not an Android KeyStore key.
+ * &#125;
+ * }</pre>
+ *
+ * <p><h3>Example: Private Key</h3>
+ * The following example illustrates how to obtain a {@link KeyStoreKeySpec} describing the provided
+ * Android KeyStore {@link PrivateKey}.
+ * <pre> {@code
+ * PrivateKey key = ...; // Android KeyStore key
+ *
+ * KeyFactory factory = KeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
+ * KeyStoreKeySpec spec;
+ * try &#123;
+ *     spec = factory.getKeySpec(key, KeyStoreKeySpec.class);
+ * &#125; catch (InvalidKeySpecException e) &#123;
+ *     // Not an Android KeyStore key.
+ * &#125;
+ * }</pre>
  */
 public class KeyStoreKeySpec implements KeySpec {
     private final String mKeystoreAlias;