From a5e21f0ee2fbf3a6f03e31fca8da459e1fe9e213 Mon Sep 17 00:00:00 2001
From: Alex Klyubin <klyubin@google.com>
Date: Wed, 17 Jun 2015 11:24:45 -0700
Subject: Prefer GCM to CBC or CTR in documentation.

Bug: 21786749
Change-Id: If3824d1321ef1d8730d4384717b0c25d43518fe4
---
 .../security/keystore/KeyGenParameterSpec.java     | 18 ++++++++--------
 .../java/android/security/keystore/KeyInfo.java    |  4 ++--
 .../android/security/keystore/KeyProtection.java   | 24 +++++++++++-----------
 3 files changed, 23 insertions(+), 23 deletions(-)

(limited to 'keystore')

diff --git a/keystore/java/android/security/keystore/KeyGenParameterSpec.java b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
index 8d4bfcd..944757c 100644
--- a/keystore/java/android/security/keystore/KeyGenParameterSpec.java
+++ b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
@@ -103,7 +103,7 @@ import javax.security.auth.x500.X500Principal;
  *
  * <p><h3>Example: Symmetric key</h3>
  * The following example illustrates how to generate an AES key in the Android KeyStore system under
- * alias {@code key2} authorized to be used only for encryption/decryption in CBC mode with PKCS#7
+ * alias {@code key2} authorized to be used only for encryption/decryption in GCM mode with no
  * padding.
  * <pre> {@code
  * KeyGenerator keyGenerator = KeyGenerator.getInstance(
@@ -112,8 +112,8 @@ import javax.security.auth.x500.X500Principal;
  * keyGenerator.initialize(
  *         new KeyGenParameterSpec.Builder("key2",
  *                 KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
- *                 .setBlockModes(KeyProperties.BLOCK_MODE_CBC)
- *                 .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
+ *                 .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+ *                 .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
  *                 .build());
  * SecretKey key = keyGenerator.generateKey();
  *
@@ -368,7 +368,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
     }
 
     /**
-     * Gets the set of block modes (e.g., {@code CBC}, {@code CTR}) with which the key can be used
+     * Gets the set of block modes (e.g., {@code GCM}, {@code CBC}) with which the key can be used
      * when encrypting/decrypting. Attempts to use the key with any other block modes will be
      * rejected.
      *
@@ -681,11 +681,11 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
         }
 
         /**
-         * Sets the set of block modes (e.g., {@code CBC}, {@code CTR}, {@code ECB}) with which the
-         * key can be used when encrypting/decrypting. Attempts to use the key with any other block
-         * modes will be rejected.
+         * Sets the set of block modes (e.g., {@code GCM}, {@code CBC}) with which the key can be
+         * used when encrypting/decrypting. Attempts to use the key with any other block modes will
+         * be rejected.
          *
-         * <p>This must be specified for encryption/decryption keys.
+         * <p>This must be specified for symmetric encryption/decryption keys.
          *
          * <p>See {@link KeyProperties}.{@code BLOCK_MODE} constants.
          */
@@ -711,7 +711,7 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
          * <li>encryption/decryption transformation which do not offer {@code IND-CPA}, such as
          * {@code ECB} with a symmetric encryption algorithm, or RSA encryption/decryption without
          * padding, are prohibited;</li>
-         * <li>in block modes which use an IV, such as {@code CBC}, {@code CTR}, and {@code GCM},
+         * <li>in block modes which use an IV, such as {@code GCM}, {@code CBC}, and {@code CTR},
          * caller-provided IVs are rejected when encrypting, to ensure that only random IVs are
          * used.</li>
          * </ul>
diff --git a/keystore/java/android/security/keystore/KeyInfo.java b/keystore/java/android/security/keystore/KeyInfo.java
index 03b4100..0016e5f 100644
--- a/keystore/java/android/security/keystore/KeyInfo.java
+++ b/keystore/java/android/security/keystore/KeyInfo.java
@@ -30,7 +30,7 @@ import javax.crypto.SecretKey;
  * Keystore system</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
+ * is authorized for (e.g., only in {@code GCM} mode, or signing only), whether the key should be
  * encrypted at rest, the key's and validity start and end dates.
  *
  * <p>Instances of this class are immutable.
@@ -191,7 +191,7 @@ public class KeyInfo implements KeySpec {
     }
 
     /**
-     * Gets the set of block modes (e.g., {@code CBC}, {@code CTR}) with which the key can be used
+     * Gets the set of block modes (e.g., {@code GCM}, {@code CBC}) with which the key can be used
      * when encrypting/decrypting. Attempts to use the key with any other block modes will be
      * rejected.
      *
diff --git a/keystore/java/android/security/keystore/KeyProtection.java b/keystore/java/android/security/keystore/KeyProtection.java
index 1e0611c..f11b773 100644
--- a/keystore/java/android/security/keystore/KeyProtection.java
+++ b/keystore/java/android/security/keystore/KeyProtection.java
@@ -31,7 +31,7 @@ import javax.crypto.Cipher;
  * Specification of how a key or key pair is secured when imported into the
  * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore facility</a>. This class
  * specifies parameters such as whether user authentication is required for using the key, what uses
- * the key is authorized for (e.g., only in {@code CTR} mode, or only for signing -- decryption not
+ * the key is authorized for (e.g., only in {@code GCM} mode, or only for signing -- decryption not
  * permitted), the key's and validity start and end dates.
  *
  * <p>To import a key or key pair into the Android KeyStore, create an instance of this class using
@@ -51,8 +51,8 @@ import javax.crypto.Cipher;
  *
  * <p><h3>Example: Symmetric Key</h3>
  * The following example illustrates how to import an AES key into the Android KeyStore under alias
- * {@code key1} authorized to be used only for encryption/decryption in CBC mode with PKCS#7
- * padding. The key must export its key material via {@link Key#getEncoded()} in {@code RAW} format.
+ * {@code key1} authorized to be used only for encryption/decryption in GCM mode with no padding.
+ * The key must export its key material via {@link Key#getEncoded()} in {@code RAW} format.
  * <pre> {@code
  * SecretKey key = ...; // AES key
  *
@@ -62,8 +62,8 @@ import javax.crypto.Cipher;
  *         "key1",
  *         new KeyStore.SecretKeyEntry(key),
  *         new KeyProtection.Builder(KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
- *                 .setBlockMode(KeyProperties.BLOCK_MODE_CBC)
- *                 .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
+ *                 .setBlockMode(KeyProperties.BLOCK_MODE_GCM)
+ *                 .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
  *                 .build());
  * // Key imported, obtain a reference to it.
  * SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null);
@@ -232,7 +232,7 @@ public final class KeyProtection implements ProtectionParameter {
     }
 
     /**
-     * Gets the set of block modes (e.g., {@code CBC}, {@code CTR}) with which the key can be used
+     * Gets the set of block modes (e.g., {@code GCM}, {@code CBC}) with which the key can be used
      * when encrypting/decrypting. Attempts to use the key with any other block modes will be
      * rejected.
      *
@@ -424,11 +424,11 @@ public final class KeyProtection implements ProtectionParameter {
         }
 
         /**
-         * Sets the set of block modes (e.g., {@code CBC}, {@code CTR}, {@code ECB}) with which the
-         * key can be used when encrypting/decrypting. Attempts to use the key with any other block
-         * modes will be rejected.
+         * Sets the set of block modes (e.g., {@code GCM}, {@code CBC}) with which the key can be
+         * used when encrypting/decrypting. Attempts to use the key with any other block modes will
+         * be rejected.
          *
-         * <p>This must be specified for encryption/decryption keys.
+         * <p>This must be specified for symmetric encryption/decryption keys.
          *
          * <p>See {@link KeyProperties}.{@code BLOCK_MODE} constants.
          */
@@ -453,8 +453,8 @@ public final class KeyProtection implements ProtectionParameter {
          * <ul>
          * <li>transformation which do not offer {@code IND-CPA}, such as symmetric ciphers using
          * {@code ECB} mode or RSA encryption without padding, are prohibited;</li>
-         * <li>in transformations which use an IV, such as symmetric ciphers in {@code CBC},
-         * {@code CTR}, and {@code GCM} block modes, caller-provided IVs are rejected when
+         * <li>in transformations which use an IV, such as symmetric ciphers in {@code GCM},
+         * {@code CBC}, and {@code CTR} block modes, caller-provided IVs are rejected when
          * encrypting, to ensure that only random IVs are used.</li>
          *
          * <p>Before disabling this requirement, consider the following approaches instead:
-- 
cgit v1.1