Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit dcf3d35f authored by Alex Klyubin's avatar Alex Klyubin
Browse files

Update Javadocs to reflect meaning of digest and padding NONE. 

This also adds information about what digests and paddings may need to
be specified for keys used in TLS/SSL for client or server
authentication.

Bug: 21777596
Change-Id: Icd495458c38c4f912b21a64ca7aab2c88d76461c
parent f7bc24c5

keystore/java/android/security/keystore/AndroidKeyStoreKeyPairGeneratorSpi.java

+6 −18
Original line number Diff line number Diff line
@@ -215,14 +215,8 @@ public abstract class AndroidKeyStoreKeyPairGeneratorSpi extends KeyPairGenerato 
                                    legacySpec.getKeystoreAlias(),

                                    KeyProperties.PURPOSE_SIGN

                                    | KeyProperties.PURPOSE_VERIFY);

                            specBuilder.setDigests(

                                    KeyProperties.DIGEST_NONE,

                                    KeyProperties.DIGEST_MD5,

                                    KeyProperties.DIGEST_SHA1,

                                    KeyProperties.DIGEST_SHA224,

                                    KeyProperties.DIGEST_SHA256,

                                    KeyProperties.DIGEST_SHA384,

                                    KeyProperties.DIGEST_SHA512);

                            // Authorized to be used with any digest (including no digest).

                            specBuilder.setDigests(KeyProperties.DIGEST_NONE);

                            break;

                        case KeymasterDefs.KM_ALGORITHM_RSA:

                            specBuilder = new KeyGenParameterSpec.Builder(
@@ -231,19 +225,13 @@ public abstract class AndroidKeyStoreKeyPairGeneratorSpi extends KeyPairGenerato 
                                    | KeyProperties.PURPOSE_DECRYPT

                                    | KeyProperties.PURPOSE_SIGN

                                    | KeyProperties.PURPOSE_VERIFY);

                            specBuilder.setDigests(

                                    KeyProperties.DIGEST_NONE,

                                    KeyProperties.DIGEST_MD5,

                                    KeyProperties.DIGEST_SHA1,

                                    KeyProperties.DIGEST_SHA224,

                                    KeyProperties.DIGEST_SHA256,

                                    KeyProperties.DIGEST_SHA384,

                                    KeyProperties.DIGEST_SHA512);

                            // Authorized to be used with any digest (including no digest).

                            specBuilder.setDigests(KeyProperties.DIGEST_NONE);

                            specBuilder.setSignaturePaddings(

                                    KeyProperties.SIGNATURE_PADDING_RSA_PKCS1);

                            // Authorized to be used with any padding (including no padding).

                            specBuilder.setEncryptionPaddings(

                                    KeyProperties.ENCRYPTION_PADDING_NONE,

                                    KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1);

                                    KeyProperties.ENCRYPTION_PADDING_NONE);

                            // Disable randomized encryption requirement to support encryption

                            // padding NONE above.

                            specBuilder.setRandomizedEncryptionRequired(false);

keystore/java/android/security/keystore/AndroidKeyStoreSpi.java

+6 −18
Original line number Diff line number Diff line
@@ -247,14 +247,8 @@ public class AndroidKeyStoreSpi extends KeyStoreSpi { 
            specBuilder =

                    new KeyProtection.Builder(

                            KeyProperties.PURPOSE_SIGN | KeyProperties.PURPOSE_VERIFY);

            specBuilder.setDigests(

                    KeyProperties.DIGEST_NONE,

                    KeyProperties.DIGEST_MD5,

                    KeyProperties.DIGEST_SHA1,

                    KeyProperties.DIGEST_SHA224,

                    KeyProperties.DIGEST_SHA256,

                    KeyProperties.DIGEST_SHA384,

                    KeyProperties.DIGEST_SHA512);

            // Authorized to be used with any digest (including no digest).

            specBuilder.setDigests(KeyProperties.DIGEST_NONE);

        } else if (KeyProperties.KEY_ALGORITHM_RSA.equalsIgnoreCase(keyAlgorithm)) {

            specBuilder =

                    new KeyProtection.Builder(
@@ -262,19 +256,13 @@ public class AndroidKeyStoreSpi extends KeyStoreSpi { 
                            | KeyProperties.PURPOSE_DECRYPT

                            | KeyProperties.PURPOSE_SIGN

                            | KeyProperties.PURPOSE_VERIFY);

            specBuilder.setDigests(

                    KeyProperties.DIGEST_NONE,

                    KeyProperties.DIGEST_MD5,

                    KeyProperties.DIGEST_SHA1,

                    KeyProperties.DIGEST_SHA224,

                    KeyProperties.DIGEST_SHA256,

                    KeyProperties.DIGEST_SHA384,

                    KeyProperties.DIGEST_SHA512);

            // Authorized to be used with any digest (including no digest).

            specBuilder.setDigests(KeyProperties.DIGEST_NONE);

            specBuilder.setSignaturePaddings(

                    KeyProperties.SIGNATURE_PADDING_RSA_PKCS1);

            // Authorized to be used with any padding (including no padding).

            specBuilder.setEncryptionPaddings(

                    KeyProperties.ENCRYPTION_PADDING_NONE,

                    KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1);

                    KeyProperties.ENCRYPTION_PADDING_NONE);

            // Disable randomized encryption requirement to support encryption padding NONE

            // above.

            specBuilder.setRandomizedEncryptionRequired(false);

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

+13 −2
Original line number Diff line number Diff line
@@ -611,9 +611,14 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec { 
         *

         * <p>This must be specified for keys which are used for signing/verification. For HMAC

         * keys, the set of digests defaults to the digest associated with the key algorithm (e.g.,

         * {@code SHA-256} for key algorithm {@code HmacSHA256}

         * {@code SHA-256} for key algorithm {@code HmacSHA256}).

         *

         * @see KeyProperties.Digest

         * <p>For private keys used for TLS/SSL client or server authentication it is usually

         * necessary to authorize the use of no digest ({@link KeyProperties#DIGEST_NONE}). This is

         * because TLS/SSL stacks typically generate the necessary digest(s) themselves and then use

         * a private key to sign it.

         *

         * <p>See {@link KeyProperties}.{@code DIGEST} constants.

         */

        @NonNull

        public Builder setDigests(@KeyProperties.DigestEnum String... digests) {
@@ -629,6 +634,12 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec { 
         *

         * <p>This must be specified for keys which are used for encryption/decryption.

         *

         * <p>For RSA private keys used by TLS/SSL servers to authenticate themselves to clients it

         * is usually necessary to authorize the use of no/any padding

         * ({@link KeyProperties#ENCRYPTION_PADDING_NONE}). This is because RSA decryption is

         * required by some cipher suites, and some stacks request decryption using no padding

         * whereas others request PKCS#1 padding.

         *

         * <p>See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.

         */

        @NonNull

keystore/java/android/security/keystore/KeyProperties.java

+6 −0
Original line number Diff line number Diff line
@@ -368,6 +368,9 @@ public abstract class KeyProperties { 


    /**

     * No encryption padding.

     *

     * <p><b>NOTE</b>: If a key is authorized to be used with no padding, then it can be used with

     * any padding scheme.

     */

    public static final String ENCRYPTION_PADDING_NONE = "NoPadding";
@@ -514,6 +517,9 @@ public abstract class KeyProperties { 


    /**

     * No digest: sign/authenticate the raw message.

     *

     * <p><b>NOTE</b>: If a key is authorized to be used with no digest, then it can be used with

     * any digest.

     */

    public static final String DIGEST_NONE = "NONE";

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

+11 −0
Original line number Diff line number Diff line
@@ -374,6 +374,12 @@ public final class KeyProtection implements ProtectionParameter { 
         *

         * <p>This must be specified for keys which are used for encryption/decryption.

         *

         * <p>For RSA private keys used by TLS/SSL servers to authenticate themselves to clients it

         * is usually necessary to authorize the use of no/any padding

         * ({@link KeyProperties#ENCRYPTION_PADDING_NONE}). This is because RSA decryption is

         * required by some cipher suites, and some stacks request decryption using no padding

         * whereas others request PKCS#1 padding.

         *

         * <p>See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.

         */

        @NonNull
@@ -408,6 +414,11 @@ public final class KeyProtection implements ProtectionParameter { 
         * {@link Key#getAlgorithm()}. For asymmetric signing keys the set of digest algorithms

         * must be specified.

         *

         * <p>For private keys used for TLS/SSL client or server authentication it is usually

         * necessary to authorize the use of no digest ({@link KeyProperties#DIGEST_NONE}). This is

         * because TLS/SSL stacks typically generate the necessary digest(s) themselves and then use

         * a private key to sign it.

         *

         * <p>See {@link KeyProperties}.{@code DIGEST} constants.

         */

        @NonNull