Prefer GCM to CBC or CTR in documentation. (a5e21f0e) · Commits · e / os / android_frameworks_base

keystore/java/android/security/keystore/KeyGenParameterSpec.java

+9 −9

Original line number	Diff line number	Diff line
		@@ -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>

keystore/java/android/security/keystore/KeyInfo.java

+2 −2

Original line number	Diff line number	Diff line
		@@ -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.
		*

keystore/java/android/security/keystore/KeyProtection.java

+12 −12

Original line number	Diff line number	Diff line
		@@ -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: