diff --git a/README.md b/README.md index 6929da94..f6f26ca4 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,12 @@ KeyFactory: AlgorithmParameters: * EC. Please refer to [system properties](https://github.com/corretto/amazon-corretto-crypto-provider#other-system-properties) for more information. +Mac algorithms with precomputed key and associated secret key factories (expert use only, refer to [HMAC with Precomputed Key](https://github.com/corretto/amazon-corretto-crypto-provider#HMAC-with-Precomputed-Key) for more information): +* HmacSHA512WithPrecomputedKey (not available in FIPS builds) +* HmacSHA384WithPrecomputedKey (not available in FIPS builds) +* HmacSHA256WithPrecomputedKey (not available in FIPS builds) +* HmacSHA1WithPrecomputedKey (not available in FIPS builds) +* HmacMD5WithPrecomputedKey (not available in FIPS builds) # Notes on ACCP-FIPS ACCP-FIPS is a variation of ACCP which uses AWS-LC-FIPS 2.x as its cryptographic module. This version of AWS-LC-FIPS has completed FIPS validation testing by an accredited lab and has been submitted to NIST for certification. Refer to the [NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List) for the latest status of the AWS-LC Cryptographic Module. We will also update our release notes and documentation to reflect any changes in FIPS certification status. We provide ACCP-FIPS for experimentation and performance testing in the interim. @@ -375,6 +381,25 @@ Thus, these should all be set on the JVM command line using `-D`. Allows one to set the temporary directory used by ACCP when loading native libraries. If this system property is not defined, the system property `java.io.tmpdir` is used. +# Additional information + +## HMAC with Precomputed Key + +EXPERT use only. Most users of ACCP just need normal `HmacXXX` algorithms and not their `WithPrecomputedKey` variants. + +The non-standard-JCA/JCE algorithms `HmacXXXWithPrecomputedKey` (where `XXX` is the digest name, e.g., `SHA384`) implement an optimization of HMAC described in NIST-FIPS-198-1 (Section 6) and in RFC2104 (Section 4). +They allow to generate a precomputed key for a given original key and a given HMAC algorithm, +and then to use this precomputed key to compute HMAC (instead of the original key). +Only use these algorithms if you know you absolutely need them. + +In more detail, the secret key factories `HmacXXXWithPrecomputedKey` allow to generate a precomputed key from a normal HMAC key. +The mac algorithms `HmacXXXWithPrecomputedKey` take a precomputed key instead of a normal HMAC key. +Precomputed keys must implement `SecretKeySpec` with format `RAW` and algorithm `HmacXXXWithPrecomputedKey`. + +Implementation uses AWS-LC functions `HMAC_set_precomputed_key_export`, `HMAC_get_precomputed_key`, and `HMAC_Init_from_precomputed_key`. + +See [example HmacWithPrecomputedKey](./examples/lib/src/test/kotlin/com/amazon/corretto/crypto/examples/HmacWithPrecomputedKey.kt). + # License This library is licensed under the Apache 2.0 license although portions of this product include software licensed under the [dual OpenSSL and SSLeay diff --git a/aws-lc b/aws-lc index 05747780..2f187975 160000 --- a/aws-lc +++ b/aws-lc @@ -1 +1 @@ -Subproject commit 05747780676652f41d0b9c570a495e4bb6608560 +Subproject commit 2f1879759b2e0fc70592665bdf10087b64f44b7d diff --git a/build.gradle b/build.gradle index b4885c51..2431fd9e 100644 --- a/build.gradle +++ b/build.gradle @@ -18,7 +18,7 @@ ext.isFips = Boolean.getBoolean('FIPS') if (ext.isFips) { ext.awsLcGitVersionId = 'AWS-LC-FIPS-2.0.13' } else { - ext.awsLcGitVersionId = 'v1.33.0' + ext.awsLcGitVersionId = 'v1.34.2' } // Check for user inputted git version ID. diff --git a/csrc/hmac.cpp b/csrc/hmac.cpp index 38e41e18..74261ee7 100644 --- a/csrc/hmac.cpp +++ b/csrc/hmac.cpp @@ -8,13 +8,19 @@ #define DO_NOT_INIT -1 #define DO_NOT_REKEY -2 +// Detect the support of precomputed keys using the fact that HMAC_SHA256_PRECOMPUTED_KEY_SIZE is only defined +// when precomputed keys are supported +#ifdef HMAC_SHA256_PRECOMPUTED_KEY_SIZE +#define HMAC_PRECOMPUTED_KEY_SUPPORT 1 +#endif + using namespace AmazonCorrettoCryptoProvider; // Some of the logic around how to manage arrays is non-standard because HMAC is extremely performance sensitive. // For the smaller data-sizes we're using, avoiding GetPrimitiveArrayCritical is worth it. namespace { -void maybe_init_ctx(raii_env& env, HMAC_CTX* ctx, jbyteArray& keyArr, jlong evpMd) +void maybe_init_ctx(raii_env& env, HMAC_CTX* ctx, jbyteArray& keyArr, jlong evpMd, jboolean usePrecomputedKey) { if (DO_NOT_INIT == evpMd) { return; @@ -33,13 +39,26 @@ void maybe_init_ctx(raii_env& env, HMAC_CTX* ctx, jbyteArray& keyArr, jlong evpM // of wrapping it in a java_buffer when we don't need it. java_buffer keyBuf = java_buffer::from_array(env, keyArr); jni_borrow key(env, keyBuf, "key"); - if (unlikely( - HMAC_Init_ex(ctx, key.data(), key.len(), reinterpret_cast(evpMd), nullptr /* ENGINE */) - != 1)) { - throw_openssl("Unable to initialize HMAC_CTX"); + if (unlikely(usePrecomputedKey)) { +#ifdef HMAC_PRECOMPUTED_KEY_SUPPORT + if (unlikely( + HMAC_Init_from_precomputed_key(ctx, key.data(), key.len(), reinterpret_cast(evpMd)) + != 1)) { + throw_openssl("Unable to initialize HMAC_CTX using precomputed key"); + } +#else + throw_java_ex(EX_ERROR, "Precomputed keys are not supported on this platform/build"); +#endif + } else { + if (unlikely(HMAC_Init_ex( + ctx, key.data(), key.len(), reinterpret_cast(evpMd), nullptr /* ENGINE */) + != 1)) { + throw_openssl("Unable to initialize HMAC_CTX"); + } } } } +} void update_ctx(raii_env& env, HMAC_CTX* ctx, jni_borrow& input) { @@ -59,6 +78,30 @@ void calculate_mac(raii_env& env, HMAC_CTX* ctx, java_buffer& result) // it can be faster to use put_bytes rather than convert it into a jni_borrow. result.put_bytes(env, scratch, 0, macSize); } + +jint get_precomputed_key_size(raii_env& env, jstring digestName) +{ +#ifdef HMAC_PRECOMPUTED_KEY_SUPPORT + jni_string name(env, digestName); + if (!strcmp("md5", name)) { + return HMAC_MD5_PRECOMPUTED_KEY_SIZE; + } else if (!strcmp("sha1", name)) { + return HMAC_SHA1_PRECOMPUTED_KEY_SIZE; + } else if (!strcmp("sha256", name)) { + return HMAC_SHA256_PRECOMPUTED_KEY_SIZE; + } else if (!strcmp("sha384", name)) { + return HMAC_SHA384_PRECOMPUTED_KEY_SIZE; + } else if (!strcmp("sha512", name)) { + return HMAC_SHA512_PRECOMPUTED_KEY_SIZE; + } else { + // This should not happen: this function should only be called with valid digest names by the Java code + throw_java_ex( + EX_ERROR, "THIS SHOULD NOT BE REACHABLE. Invalid digest name provided to get_precomputed_key_size."); + } +#else + throw_java_ex(EX_ERROR, "Precomputed keys are not supported on this platform/build"); +#endif + return 0; // just to please the static verifier, since throw_java_ex always throws an exception } #ifdef __cplusplus @@ -77,10 +120,17 @@ JNIEXPORT jint JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_getConte /* * Class: com_amazon_corretto_crypto_provider_EvpHmac * Method: updateCtxArray - * Signature: ([B[BJ[BII)V + * Signature: ([B[BJ[BIIZ)V */ -JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_updateCtxArray( - JNIEnv* pEnv, jclass, jbyteArray ctxArr, jbyteArray keyArr, jlong evpMd, jbyteArray inputArr, jint offset, jint len) +JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_updateCtxArray(JNIEnv* pEnv, + jclass, + jbyteArray ctxArr, + jbyteArray keyArr, + jlong evpMd, + jbyteArray inputArr, + jint offset, + jint len, + jboolean usePrecomputedKey) { try { raii_env env(pEnv); @@ -88,7 +138,7 @@ JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_updateCt java_buffer inputBuf = java_buffer::from_array(env, inputArr, offset, len); - maybe_init_ctx(env, ctx, keyArr, evpMd); + maybe_init_ctx(env, ctx, keyArr, evpMd, usePrecomputedKey); jni_borrow input(env, inputBuf, "input"); update_ctx(env, ctx, input); @@ -119,17 +169,18 @@ JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_doFinal( /* * Class: com_amazon_corretto_crypto_provider_EvpHmac * Method: fastHmac - * Signature: ([B[BJ[BII[B)V + * Signature: ([B[BJ[BII[BZ)V */ JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_fastHmac(JNIEnv* pEnv, - jclass clazz, + jclass, jbyteArray ctxArr, jbyteArray keyArr, jlong evpMd, jbyteArray inputArr, jint offset, jint len, - jbyteArray resultArr) + jbyteArray resultArr, + jboolean usePrecomputedKey) { // We do not depend on the other methods because it results in more use to JNI than we want and lower performance try { @@ -138,7 +189,7 @@ JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_fastHmac java_buffer inputBuf = java_buffer::from_array(env, inputArr, offset, len); java_buffer resultBuf = java_buffer::from_array(env, resultArr); - maybe_init_ctx(env, ctx, keyArr, evpMd); + maybe_init_ctx(env, ctx, keyArr, evpMd, usePrecomputedKey); { jni_borrow input(env, inputBuf, "input"); @@ -153,6 +204,70 @@ JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_fastHmac } } +/* + * Class: Java_com_amazon_corretto_crypto_provider_EvpHmac + * Method: getPrecomputedKeyLength + * Signature: (Ljava/lang/String;)I + */ +JNIEXPORT jint JNICALL Java_com_amazon_corretto_crypto_provider_EvpHmac_getPrecomputedKeyLength( + JNIEnv* pEnv, jclass, jstring digestName) +{ + try { + raii_env env(pEnv); + return get_precomputed_key_size(env, digestName); + } catch (java_ex& ex) { + ex.throw_to_java(pEnv); + } + return 0; +} + +/* + * Class: com_amazon_corretto_crypto_provider_HmacWithPrecomputedKeyKeyFactorySpi + * Method: getPrecomputedKey + * Signature: ([BI[BIJ)V + */ +JNIEXPORT void JNICALL Java_com_amazon_corretto_crypto_provider_HmacWithPrecomputedKeyKeyFactorySpi_getPrecomputedKey( + JNIEnv* pEnv, jclass, jbyteArray jOutput, jint outputLen, jbyteArray jKey, jint keyLen, jlong evpMd) +{ + try { +#ifdef HMAC_PRECOMPUTED_KEY_SUPPORT + JBinaryBlob result(pEnv, nullptr, jOutput); + JBinaryBlob key(pEnv, nullptr, jKey); + + bssl::ScopedHMAC_CTX ctx; + + if (unlikely(HMAC_Init_ex(ctx.get(), + key.get(), // key + keyLen, // keyLen + reinterpret_cast(evpMd), // EVP_MD + nullptr /* ENGINE */) + != 1)) { + throw_openssl("Unable to initialize HMAC_CTX"); + } + + if (unlikely(HMAC_set_precomputed_key_export(ctx.get()) != 1)) { + throw_openssl("Unable to call HMAC_set_precomputed_key_export"); + } + + // HMAC_get_precomputed_key takes as input the length of the buffer + // and update it to the actual length of the precomputed key. + // The Java caller always selects the right buffer size, so we should not have any error. + // But we do a sanity check that this is the case. + size_t actualOutputLen = outputLen; + if (unlikely(HMAC_get_precomputed_key(ctx.get(), result.get(), &actualOutputLen) != 1)) { + throw_openssl("Unable to call HMAC_get_precomputed_key"); + } + if (unlikely(outputLen < 0 || (size_t)outputLen != actualOutputLen)) { + throw_java_ex(EX_ERROR, "THIS SHOULD NOT BE REACHABLE. invalid output precomputed key length."); + } +#else + throw_java_ex(EX_ERROR, "Precomputed keys are not supported on this platform/build"); +#endif + } catch (java_ex& ex) { + ex.throw_to_java(pEnv); + } +} + #ifdef __cplusplus } #endif diff --git a/examples/gradle-kt-dsl/lib/src/test/kotlin/com/amazon/corretto/crypto/examples/Hmac.kt b/examples/gradle-kt-dsl/lib/src/test/kotlin/com/amazon/corretto/crypto/examples/Hmac.kt new file mode 100644 index 00000000..5e37e378 --- /dev/null +++ b/examples/gradle-kt-dsl/lib/src/test/kotlin/com/amazon/corretto/crypto/examples/Hmac.kt @@ -0,0 +1,37 @@ +package com.amazon.corretto.crypto.examples + +import com.amazon.corretto.crypto.provider.AmazonCorrettoCryptoProvider +import java.util.* +import javax.crypto.Mac +import javax.crypto.spec.SecretKeySpec +import kotlin.test.Test +import kotlin.test.assertContentEquals +import kotlin.test.assertEquals + +class Hmac { + @Test + fun hmacTest() { + val accpProviderName = "AmazonCorrettoCryptoProvider" + AmazonCorrettoCryptoProvider.install() + + val mac = Mac.getInstance("HmacSHA384") + assertEquals(accpProviderName, mac.provider.name) + + // An arbitrary 32-bytes key in base64 for the example + val keyBase64 = "62lKZjLXnX4yGvNyd3/M3q+T6yfREHgbIoJidXCEzGw=" + val key = Base64.getDecoder().decode(keyBase64) + val keySpec = SecretKeySpec(key, "Generic") + + val message = "Hello, this is just an example." + + // Compute the MAC + mac.init(keySpec); + val macResult = mac.doFinal(message.toByteArray()) + + // Verify the result matches what we expect + val expectedResultBase64 = + "w72DBgWvjTDqlv+EzOc1/R+K9Qq1jrNCHCQewXXhaOQ8Joi2jPPQdAT+HDc65KMM" + val expectedResult = Base64.getDecoder().decode(expectedResultBase64) + assertContentEquals(expectedResult, macResult) + } +} \ No newline at end of file diff --git a/examples/gradle-kt-dsl/lib/src/test/kotlin/com/amazon/corretto/crypto/examples/HmacWithPrecomputedKey.kt b/examples/gradle-kt-dsl/lib/src/test/kotlin/com/amazon/corretto/crypto/examples/HmacWithPrecomputedKey.kt new file mode 100644 index 00000000..a3f569cb --- /dev/null +++ b/examples/gradle-kt-dsl/lib/src/test/kotlin/com/amazon/corretto/crypto/examples/HmacWithPrecomputedKey.kt @@ -0,0 +1,53 @@ +package com.amazon.corretto.crypto.examples + +import com.amazon.corretto.crypto.provider.AmazonCorrettoCryptoProvider +import java.security.SecureRandom +import java.util.* +import javax.crypto.Cipher +import javax.crypto.Mac +import javax.crypto.SecretKeyFactory +import javax.crypto.spec.GCMParameterSpec +import javax.crypto.spec.SecretKeySpec +import kotlin.test.Test +import kotlin.test.assertContentEquals +import kotlin.test.assertEquals + +class HmacWithPrecomputedKey { + @Test + fun hmacWithPrecomputedKeyTest() { + // EXPERT-ONLY use + // This example is most likely NOT what you want to use. + // If you need to use Hmac, see the Hmac.kt example. + // This example shows how to use precomputed keys, which is not standard in JCA/JCE. + // See ACCP README.md for details. + + val accpProviderName = "AmazonCorrettoCryptoProvider" + AmazonCorrettoCryptoProvider.install() + + val mac = Mac.getInstance("HmacSHA384WithPrecomputedKey") + assertEquals(accpProviderName, mac.provider.name) + + val skf = SecretKeyFactory.getInstance("HmacSHA384WithPrecomputedKey") + assertEquals(accpProviderName, skf.provider.name) + + // An arbitrary 32-bytes key in base64 for the example + val keyBase64 = "62lKZjLXnX4yGvNyd3/M3q+T6yfREHgbIoJidXCEzGw="; + val key = Base64.getDecoder().decode(keyBase64); + val keySpec = SecretKeySpec(key, "Generic"); + + val message = "Hello, this is just an example." + + // Compute the HMAC precomputed key + val precomputedKey = skf.generateSecret(keySpec) + + // Compute the HMAC using the precomputed key + mac.init(precomputedKey); + val macResult = mac.doFinal(message.toByteArray()) + + // Verify the result matches what we expect + val expectedResultBase64 = + "w72DBgWvjTDqlv+EzOc1/R+K9Qq1jrNCHCQewXXhaOQ8Joi2jPPQdAT+HDc65KMM" + val expectedResult = Base64.getDecoder().decode(expectedResultBase64) + assertContentEquals(expectedResult, macResult) + } +} \ No newline at end of file diff --git a/src/com/amazon/corretto/crypto/provider/AmazonCorrettoCryptoProvider.java b/src/com/amazon/corretto/crypto/provider/AmazonCorrettoCryptoProvider.java index 060bc929..2a077032 100644 --- a/src/com/amazon/corretto/crypto/provider/AmazonCorrettoCryptoProvider.java +++ b/src/com/amazon/corretto/crypto/provider/AmazonCorrettoCryptoProvider.java @@ -10,6 +10,12 @@ import static com.amazon.corretto.crypto.provider.ConcatenationKdfSpi.CKDF_WITH_SHA256; import static com.amazon.corretto.crypto.provider.ConcatenationKdfSpi.CKDF_WITH_SHA384; import static com.amazon.corretto.crypto.provider.ConcatenationKdfSpi.CKDF_WITH_SHA512; +import static com.amazon.corretto.crypto.provider.EvpHmac.HMAC_MD5_WITH_PRECOMPUTED_KEY; +import static com.amazon.corretto.crypto.provider.EvpHmac.HMAC_SHA1_WITH_PRECOMPUTED_KEY; +import static com.amazon.corretto.crypto.provider.EvpHmac.HMAC_SHA256_WITH_PRECOMPUTED_KEY; +import static com.amazon.corretto.crypto.provider.EvpHmac.HMAC_SHA384_WITH_PRECOMPUTED_KEY; +import static com.amazon.corretto.crypto.provider.EvpHmac.HMAC_SHA512_WITH_PRECOMPUTED_KEY; +import static com.amazon.corretto.crypto.provider.EvpHmac.WITH_PRECOMPUTED_KEY; import static com.amazon.corretto.crypto.provider.HkdfSecretKeyFactorySpi.HKDF_WITH_SHA1; import static com.amazon.corretto.crypto.provider.HkdfSecretKeyFactorySpi.HKDF_WITH_SHA256; import static com.amazon.corretto.crypto.provider.HkdfSecretKeyFactorySpi.HKDF_WITH_SHA384; @@ -139,6 +145,43 @@ private void buildServiceMap() { addService("Mac", "Hmac" + hash, "EvpHmac$" + hash); } + // Once these HMAC precomputed keys are supported in a FIPS branch of AWS-LC, we can remove this + // check and update HmacTest#assumePrecomputedKeySupport and + // HmacTest#assumeNoPrecomputedKeySupport. + if (!Loader.FIPS_BUILD) { + for (String hash : new String[] {"MD5", "SHA1", "SHA256", "SHA384", "SHA512"}) { + addService( + "Mac", "Hmac" + hash + WITH_PRECOMPUTED_KEY, "EvpHmac$" + hash + WITH_PRECOMPUTED_KEY); + } + + final String hmacWithPrecomputedKeyKeyFactorySpi = "HmacWithPrecomputedKeyKeyFactorySpi"; + addService( + "SecretKeyFactory", + HMAC_MD5_WITH_PRECOMPUTED_KEY, + hmacWithPrecomputedKeyKeyFactorySpi, + false); + addService( + "SecretKeyFactory", + HMAC_SHA1_WITH_PRECOMPUTED_KEY, + hmacWithPrecomputedKeyKeyFactorySpi, + false); + addService( + "SecretKeyFactory", + HMAC_SHA256_WITH_PRECOMPUTED_KEY, + hmacWithPrecomputedKeyKeyFactorySpi, + false); + addService( + "SecretKeyFactory", + HMAC_SHA384_WITH_PRECOMPUTED_KEY, + hmacWithPrecomputedKeyKeyFactorySpi, + false); + addService( + "SecretKeyFactory", + HMAC_SHA512_WITH_PRECOMPUTED_KEY, + hmacWithPrecomputedKeyKeyFactorySpi, + false); + } + addService( "KeyAgreement", "ECDH", @@ -330,6 +373,13 @@ public Object newInstance(final Object constructorParameter) throws NoSuchAlgori if (ckdfSpi != null) { return ckdfSpi; } + + final HmacWithPrecomputedKeyKeyFactorySpi hmacWithPrecomputedKeySpi = + HmacWithPrecomputedKeyKeyFactorySpi.INSTANCES.get( + HmacWithPrecomputedKeyKeyFactorySpi.getSpiFactoryForAlgName(algo)); + if (hmacWithPrecomputedKeySpi != null) { + return hmacWithPrecomputedKeySpi; + } } if ("KeyGenerator".equalsIgnoreCase(type) && "AES".equalsIgnoreCase(algo)) { diff --git a/src/com/amazon/corretto/crypto/provider/EvpHmac.java b/src/com/amazon/corretto/crypto/provider/EvpHmac.java index a7c5b487..a345c421 100644 --- a/src/com/amazon/corretto/crypto/provider/EvpHmac.java +++ b/src/com/amazon/corretto/crypto/provider/EvpHmac.java @@ -21,6 +21,18 @@ import javax.crypto.spec.SecretKeySpec; class EvpHmac extends MacSpi implements Cloneable { + static final String HMAC_PREFIX = "Hmac"; + static final String WITH_PRECOMPUTED_KEY = "WithPrecomputedKey"; + + static final String HMAC_SHA512_WITH_PRECOMPUTED_KEY = + HMAC_PREFIX + "SHA512" + WITH_PRECOMPUTED_KEY; + static final String HMAC_SHA384_WITH_PRECOMPUTED_KEY = + HMAC_PREFIX + "SHA384" + WITH_PRECOMPUTED_KEY; + static final String HMAC_SHA256_WITH_PRECOMPUTED_KEY = + HMAC_PREFIX + "SHA256" + WITH_PRECOMPUTED_KEY; + static final String HMAC_SHA1_WITH_PRECOMPUTED_KEY = HMAC_PREFIX + "SHA1" + WITH_PRECOMPUTED_KEY; + static final String HMAC_MD5_WITH_PRECOMPUTED_KEY = HMAC_PREFIX + "MD5" + WITH_PRECOMPUTED_KEY; + /** When passed to {@code evpMd} indicates that the native code should not call HMAC_Init_ex. */ private static long DO_NOT_INIT = -1; /** @@ -33,21 +45,44 @@ class EvpHmac extends MacSpi implements Cloneable { private static native int getContextSize(); /** - * Calls {@code HMAC_Update} with {@code input}, possibly calling {@code HMAC_Init_ex} first (if - * {@code evpMd} is any value except {@link #DO_NOT_INIT}). This method should only be used via - * {@link #synchronizedUpdateCtxArray(byte[], byte[], long, byte[], int, int)}. + * Returns the length of the precomputed key for the HMAC for the hash function with name + * digestName + * + * @param digestName name of the digest (md5,sha1,sha256,sha384,sha512) + * @return the length of the precomputed key, in bytes + */ + static native int getPrecomputedKeyLength(String digestName); + + /** + * Calls {@code HMAC_Update} with {@code input}, possibly calling {@code HMAC_Init_ex} or {@code + * HMAC_Init_from_precomputed_key} first (if {@code evpMd} is any value except {@link + * #DO_NOT_INIT}). This method should only be used via {@link #synchronizedUpdateCtxArray(byte[], + * byte[], long, byte[], int, int, boolean)}. * * @param ctx opaque array containing native context */ private static native void updateCtxArray( - byte[] ctx, byte[] key, long evpMd, byte[] input, int offset, int length); + byte[] ctx, + byte[] key, + long evpMd, + byte[] input, + int offset, + int length, + boolean usePrecomputedKey); + /** - * @see {@link #updateCtxArray(byte[], byte[], long, byte[], int, int)} + * @see {@link #updateCtxArray(byte[], byte[], long, byte[], int, int, boolean)} */ private static void synchronizedUpdateCtxArray( - byte[] ctx, byte[] key, long evpMd, byte[] input, int offset, int length) { + byte[] ctx, + byte[] key, + long evpMd, + byte[] input, + int offset, + int length, + boolean usePrecomputedKey) { synchronized (ctx) { - updateCtxArray(ctx, key, evpMd, input, offset, length); + updateCtxArray(ctx, key, evpMd, input, offset, length, usePrecomputedKey); } } @@ -71,19 +106,33 @@ private static void synchronizedDoFinal(byte[] ctx, byte[] result) { /** * Calls {@code HMAC_Init_ex}, {@code HMAC_Update}, and {@code HMAC_Final} with {@code input}. * This method should only be used via {@link #synchronizedFastHmac(byte[], byte[], long, byte[], - * int, int, byte[])}. + * int, int, byte[], boolean)}. * * @param ctx opaque array containing native context */ private static native void fastHmac( - byte[] ctx, byte[] key, long evpMd, byte[] input, int offset, int length, byte[] result); + byte[] ctx, + byte[] key, + long evpMd, + byte[] input, + int offset, + int length, + byte[] result, + boolean usePrecomputedKey); /** - * @see {@link #fastHmac(byte[], byte[], long, byte[], int, int, byte[])} + * @see {@link #fastHmac(byte[], byte[], long, byte[], int, int, byte[], boolean)} */ private static void synchronizedFastHmac( - byte[] ctx, byte[] key, long evpMd, byte[] input, int offset, int length, byte[] result) { + byte[] ctx, + byte[] key, + long evpMd, + byte[] input, + int offset, + int length, + byte[] result, + boolean usePrecomputedKey) { synchronized (ctx) { - fastHmac(ctx, key, evpMd, input, offset, length, result); + fastHmac(ctx, key, evpMd, input, offset, length, result, usePrecomputedKey); } } @@ -93,12 +142,32 @@ private static void synchronizedFastHmac( private HmacState state; private InputBuffer buffer; - EvpHmac(long evpMd, int digestLength) { + private static final String WITH_PRECOMPUTE_KEY = "WithPrecomputedKey"; + + /** + * @param digestName is the name of the digest in lowercase (e.g., "sha256", "md5") + * @param baseAlgorithm the base name of the algorithm without "WithPrecomputedKey" (e.g., + * "HmacMd5") + * @param usePrecomputedKey true is using precomputed keys instead of normal keys + */ + EvpHmac(String digestName, final String baseAlgorithm, final boolean usePrecomputedKey) { + final long evpMd = Utils.getEvpMdFromName(digestName); + final int digestLength = Utils.getDigestLength(evpMd); + int precomputedKeyLength = 0; + if (usePrecomputedKey) { + precomputedKeyLength = getPrecomputedKeyLength(digestName); + } + if (evpMd == DO_NOT_INIT || evpMd == DO_NOT_REKEY) { throw new AssertionError( "Unexpected value for evpMd conflicting with reserved negative value: " + evpMd); } - this.state = new HmacState(evpMd, digestLength); + String algorithm = baseAlgorithm; + if (usePrecomputedKey) { + algorithm += WITH_PRECOMPUTE_KEY; + } + this.state = + new HmacState(evpMd, digestLength, algorithm, usePrecomputedKey, precomputedKeyLength); this.buffer = new InputBuffer(1024); configureLambdas(); } @@ -113,14 +182,16 @@ private void configureLambdas() { if (state.needsRekey) { evpMd = state.evpMd; } - synchronizedUpdateCtxArray(state.context, rawKey, evpMd, src, offset, length); + synchronizedUpdateCtxArray( + state.context, rawKey, evpMd, src, offset, length, state.usePrecomputedKey); state.needsRekey = false; return null; }) .withUpdater( (ignored, src, offset, length) -> { assertInitialized(); - synchronizedUpdateCtxArray(state.context, null, DO_NOT_INIT, src, offset, length); + synchronizedUpdateCtxArray( + state.context, null, DO_NOT_INIT, src, offset, length, state.usePrecomputedKey); }) .withDoFinal( (ignored) -> { @@ -138,7 +209,15 @@ private void configureLambdas() { if (state.needsRekey) { evpMd = state.evpMd; } - synchronizedFastHmac(state.context, rawKey, evpMd, src, offset, length, result); + synchronizedFastHmac( + state.context, + rawKey, + evpMd, + src, + offset, + length, + result, + state.usePrecomputedKey); state.needsRekey = false; return result; }); @@ -200,14 +279,44 @@ public EvpHmac clone() throws CloneNotSupportedException { private static final class HmacState implements Cloneable { private SecretKey key; private final long evpMd; + /** + * Name of the algorithm used to create this instance. This is used to ensure that the key is + * appropriate for the algorithm, when using precomputed keys. + */ + private final String algorithm; + private final int digestLength; private byte[] context = new byte[CONTEXT_SIZE]; private byte[] encoded_key; + /** + * True if precomputed keys are used instead of raw HMAC keys, that is for algorithms + * `HmacXXXWithPrecomputedKey`. + */ + private final boolean usePrecomputedKey; + + private final int precomputedKeyLength; + boolean needsRekey = true; - private HmacState(long evpMd, int digestLength) { + /** + * @param evpMd the evpMd corresponding to the digest used + * @param digestLength the length of the digest in bytes + * @param algorithm the full name algorithm (e.g., "HmacMD5" or "HmacMD5WithPrecomputedKey") + * @param usePrecomputedKey false = normal HMAC, true = uses precomputed keys + * @param precomputedKeyLength length of precomputed keys in bytes (can be 0 if + * usePrecomputedKey = false) + */ + private HmacState( + final long evpMd, + final int digestLength, + final String algorithm, + final boolean usePrecomputedKey, + final int precomputedKeyLength) { this.evpMd = evpMd; this.digestLength = digestLength; + this.algorithm = Objects.requireNonNull(algorithm); + this.usePrecomputedKey = usePrecomputedKey; + this.precomputedKeyLength = precomputedKeyLength; } private void setKey(SecretKey key) throws InvalidKeyException { @@ -218,10 +327,19 @@ private void setKey(SecretKey key) throws InvalidKeyException { if (!"RAW".equalsIgnoreCase(key.getFormat())) { throw new InvalidKeyException("Key must support RAW encoding"); } + if (usePrecomputedKey && !algorithm.equalsIgnoreCase(key.getAlgorithm())) { + throw new InvalidKeyException( + "Key must be for algorithm \"" + algorithm + "\" when using precomputed keys"); + } + byte[] encoded = key.getEncoded(); if (encoded == null) { throw new InvalidKeyException("Key encoding must not be null"); } + if (usePrecomputedKey && encoded.length != precomputedKeyLength) { + throw new InvalidKeyException( + "Key must be of length \"" + precomputedKeyLength + "\" when using precomputed keys"); + } this.encoded_key = encoded; this.key = key; this.needsRekey = true; @@ -312,78 +430,143 @@ private static SelfTestResult runSelfTest(String macName, Class getInstances() { final Map result = new HashMap<>(); diff --git a/src/com/amazon/corretto/crypto/provider/HmacWithPrecomputedKeyKeyFactorySpi.java b/src/com/amazon/corretto/crypto/provider/HmacWithPrecomputedKeyKeyFactorySpi.java new file mode 100644 index 00000000..fd20b176 --- /dev/null +++ b/src/com/amazon/corretto/crypto/provider/HmacWithPrecomputedKeyKeyFactorySpi.java @@ -0,0 +1,107 @@ +// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 +package com.amazon.corretto.crypto.provider; + +import java.security.spec.InvalidKeySpecException; +import java.security.spec.KeySpec; +import java.util.Collections; +import java.util.HashMap; +import java.util.Map; +import javax.crypto.SecretKey; +import javax.crypto.SecretKeyFactorySpi; +import javax.crypto.spec.SecretKeySpec; + +class HmacWithPrecomputedKeyKeyFactorySpi extends SecretKeyFactorySpi { + + private final long evpMd; + private final int precomputedKeyLength; + private final String algorithmName; + + /** + * Compute the HMAC precomputed key for digest {@code evpMd} and HMAC key {@code key} and store it + * in {@code result}. + * + * @param output resulting precomputed key + * @param outputLen length of output + * @param key input key + * @param keyLen length of key + * @param evpMd digest used + */ + private static native void getPrecomputedKey( + byte[] output, int outputLen, byte[] key, int keyLen, long evpMd); + + private HmacWithPrecomputedKeyKeyFactorySpi(final String algorithmName, final String digestName) { + this.evpMd = Utils.getEvpMdFromName(digestName); + this.precomputedKeyLength = EvpHmac.getPrecomputedKeyLength(digestName); + this.algorithmName = algorithmName; + } + + @Override + protected SecretKey engineGenerateSecret(final KeySpec keySpec) throws InvalidKeySpecException { + if (!(keySpec instanceof SecretKeySpec)) { + throw new InvalidKeySpecException("KeySpec must be an instance of SecretKeySpec"); + } + final SecretKeySpec spec = (SecretKeySpec) keySpec; + + if (!"RAW".equalsIgnoreCase(spec.getFormat())) { + throw new InvalidKeySpecException("KeySpec must support RAW encoding"); + } + + byte[] precomputedKey = new byte[precomputedKeyLength]; + + byte[] key = spec.getEncoded(); + if (key == null) { + throw new InvalidKeySpecException("Key encoding must not be null"); + } + getPrecomputedKey(precomputedKey, precomputedKeyLength, key, key.length, evpMd); + + return new SecretKeySpec(precomputedKey, algorithmName); + } + + @Override + protected KeySpec engineGetKeySpec(final SecretKey key, final Class keySpec) { + throw new UnsupportedOperationException(); + } + + @Override + protected SecretKey engineTranslateKey(final SecretKey key) { + throw new UnsupportedOperationException(); + } + + static final Map INSTANCES = getInstances(); + + private static final String MD5_DIGEST_NAME = "md5"; + private static final String SHA1_DIGEST_NAME = "sha1"; + private static final String SHA256_DIGEST_NAME = "sha256"; + private static final String SHA384_DIGEST_NAME = "sha384"; + private static final String SHA512_DIGEST_NAME = "sha512"; + + private static Map getInstances() { + final Map result = new HashMap<>(); + result.put( + getSpiFactoryForAlgName(EvpHmac.HMAC_MD5_WITH_PRECOMPUTED_KEY), + new HmacWithPrecomputedKeyKeyFactorySpi( + EvpHmac.HMAC_MD5_WITH_PRECOMPUTED_KEY, MD5_DIGEST_NAME)); + result.put( + getSpiFactoryForAlgName(EvpHmac.HMAC_SHA1_WITH_PRECOMPUTED_KEY), + new HmacWithPrecomputedKeyKeyFactorySpi( + EvpHmac.HMAC_SHA1_WITH_PRECOMPUTED_KEY, SHA1_DIGEST_NAME)); + result.put( + getSpiFactoryForAlgName(EvpHmac.HMAC_SHA256_WITH_PRECOMPUTED_KEY), + new HmacWithPrecomputedKeyKeyFactorySpi( + EvpHmac.HMAC_SHA256_WITH_PRECOMPUTED_KEY, SHA256_DIGEST_NAME)); + result.put( + getSpiFactoryForAlgName(EvpHmac.HMAC_SHA384_WITH_PRECOMPUTED_KEY), + new HmacWithPrecomputedKeyKeyFactorySpi( + EvpHmac.HMAC_SHA384_WITH_PRECOMPUTED_KEY, SHA384_DIGEST_NAME)); + result.put( + getSpiFactoryForAlgName(EvpHmac.HMAC_SHA512_WITH_PRECOMPUTED_KEY), + new HmacWithPrecomputedKeyKeyFactorySpi( + EvpHmac.HMAC_SHA512_WITH_PRECOMPUTED_KEY, SHA512_DIGEST_NAME)); + return Collections.unmodifiableMap(result); + } + + static String getSpiFactoryForAlgName(final String alg) { + return alg.toUpperCase(); + } +} diff --git a/tst/com/amazon/corretto/crypto/provider/test/HmacTest.java b/tst/com/amazon/corretto/crypto/provider/test/HmacTest.java index 19819041..6f2e4536 100644 --- a/tst/com/amazon/corretto/crypto/provider/test/HmacTest.java +++ b/tst/com/amazon/corretto/crypto/provider/test/HmacTest.java @@ -19,8 +19,11 @@ import java.security.GeneralSecurityException; import java.security.InvalidAlgorithmParameterException; import java.security.InvalidKeyException; +import java.security.NoSuchAlgorithmException; import java.security.Provider.Service; import java.security.PublicKey; +import java.security.spec.InvalidKeySpecException; +import java.security.spec.KeySpec; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; @@ -29,12 +32,15 @@ import java.util.List; import java.util.Map; import java.util.Scanner; +import java.util.stream.Stream; import java.util.zip.GZIPInputStream; import javax.crypto.Mac; import javax.crypto.SecretKey; +import javax.crypto.SecretKeyFactory; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Hex; +import org.junit.jupiter.api.Assumptions; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.junit.jupiter.api.parallel.Execution; @@ -54,7 +60,9 @@ public class HmacTest { static { List macs = new ArrayList<>(); for (final Service s : NATIVE_PROVIDER.getServices()) { - if (s.getType().equals("Mac") && s.getAlgorithm().startsWith("Hmac")) { + if (s.getType().equals("Mac") + && s.getAlgorithm().startsWith("Hmac") + && !s.getAlgorithm().endsWith("WithPrecomputedKey")) { macs.add(s.getAlgorithm()); } } @@ -66,10 +74,75 @@ public class HmacTest { } } + // TODO: This version needs to be updated once known. + private static final String MINIMUM_VERSION_WITH_PRECOMPUTED_KEY = "2.4.1"; + + /** + * Call this function before any tests that use precomputed keys. + * + *

TODO: This function will need to be changed once FIPS support precomputed keys. + */ + private void assumePrecomputedKeySupport() { + TestUtil.assumeMinimumVersion( + MINIMUM_VERSION_WITH_PRECOMPUTED_KEY, AmazonCorrettoCryptoProvider.INSTANCE); + Assumptions.assumeFalse( + TestUtil.isFips(), "precomputed keys are only supported in non-FIPS builds"); + } + + /** + * Call this function before any tests that assume precomputed keys are not supported. + * + *

TODO: This function will need to be changed once FIPS support precomputed keys. + */ + private void assumeNoPrecomputedKeySupport() { + Assumptions.assumeTrue(TestUtil.isFips()); + } + private static List supportedHmacs() { return SUPPORTED_HMACS; } + private int getPrecomputedKeyLength(String algorithm) { + int precomputedKeySize; + switch (algorithm) { + case "HmacMD5": + precomputedKeySize = 16; + break; + case "HmacSHA1": + precomputedKeySize = 20; + break; + case "HmacSHA256": + precomputedKeySize = 32; + break; + case "HmacSHA384": + case "HmacSHA512": + precomputedKeySize = 64; + break; + default: + throw new IllegalArgumentException("Unknown algorithm: " + algorithm); + } + return precomputedKeySize; + } + + @Test + public void precomputedKeysAreNotAvailableInFipsMode() { + assumeNoPrecomputedKeySupport(); + Stream.of( + "HmacMD5WithPrecomputedKey", + "HmacSHA1WithPrecomputedKey", + "HmacSHA256WithPrecomputedKey", + "HmacSHA384WithPrecomputedKey", + "HmacSHA512WithPrecomputedKey") + .forEach( + alg -> { + assertThrows( + NoSuchAlgorithmException.class, + () -> SecretKeyFactory.getInstance(alg, NATIVE_PROVIDER)); + assertThrows( + NoSuchAlgorithmException.class, () -> Mac.getInstance(alg, NATIVE_PROVIDER)); + }); + } + @Test public void requireInitialization() throws GeneralSecurityException { final Mac hmac = Mac.getInstance("HmacSHA256", NATIVE_PROVIDER); @@ -415,6 +488,112 @@ public byte[] getEncoded() { assertThrows(InvalidKeyException.class, () -> mac.init(nullFormat)); } + @SuppressWarnings("serial") + @ParameterizedTest + @MethodSource("supportedHmacs") + public void engineInitErrorsWithPrecomputedKey(final String algorithm) throws Exception { + assumePrecomputedKeySupport(); + + final int precomputedKeyLength = getPrecomputedKeyLength(algorithm); + byte[] precomputedKey = new byte[precomputedKeyLength]; + + // Compare to Hmac, HmacWithPrecomputedKey requires the algorithm to be + // "HmacXXXWithPrecomputedKey" + // where XXX is the digest + final String keyAlgorithm = algorithm + "WithPrecomputedKey"; + + final SecretKey validKey = new SecretKeySpec(precomputedKey, keyAlgorithm); + final PublicKey pubKey = + new PublicKey() { + @Override + public String getFormat() { + return "RAW"; + } + + @Override + public byte[] getEncoded() { + return precomputedKey; + } + + @Override + public String getAlgorithm() { + return "RAW"; + } + }; + final SecretKey badLength = new SecretKeySpec(new byte[precomputedKeyLength + 1], keyAlgorithm); + final SecretKey badAlgorithm = new SecretKeySpec(precomputedKey, "Generic"); + final SecretKey badFormat = + new SecretKeySpec(precomputedKey, keyAlgorithm) { + @Override + public String getFormat() { + return "UnexpectedFormat"; + } + }; + final SecretKey nullFormat = + new SecretKeySpec(precomputedKey, keyAlgorithm) { + @Override + public String getFormat() { + return null; + } + }; + final SecretKey nullEncoding = + new SecretKeySpec(precomputedKey, keyAlgorithm) { + @Override + public byte[] getEncoded() { + return null; + } + }; + + final Mac mac = Mac.getInstance(algorithm + "WithPrecomputedKey", NATIVE_PROVIDER); + + assertThrows( + InvalidAlgorithmParameterException.class, + () -> mac.init(validKey, new IvParameterSpec(new byte[0]))); + assertThrows(InvalidKeyException.class, () -> mac.init(pubKey)); + assertThrows(InvalidKeyException.class, () -> mac.init(badFormat)); + assertThrows(InvalidKeyException.class, () -> mac.init(badLength)); + assertThrows(InvalidKeyException.class, () -> mac.init(badAlgorithm)); + assertThrows(InvalidKeyException.class, () -> mac.init(nullEncoding)); + assertThrows(InvalidKeyException.class, () -> mac.init(nullFormat)); + } + + @SuppressWarnings("serial") + @ParameterizedTest + @MethodSource("supportedHmacs") + public void incorrectKeySpecForKeyFactory(final String algorithm) throws Exception { + assumePrecomputedKeySupport(); + + final SecretKeyFactory skf = + SecretKeyFactory.getInstance(algorithm + "WithPrecomputedKey", NATIVE_PROVIDER); + + final KeySpec nonSecretKeySpec = new KeySpec() {}; + final KeySpec badFormat = + new SecretKeySpec("yellowsubmarine".getBytes(StandardCharsets.UTF_8), "Generic") { + @Override + public String getFormat() { + return "UnexpectedFormat"; + } + }; + final KeySpec nullFormat = + new SecretKeySpec("yellowsubmarine".getBytes(StandardCharsets.UTF_8), "Generic") { + @Override + public String getFormat() { + return null; + } + }; + final KeySpec nullEncoding = + new SecretKeySpec("yellowsubmarine".getBytes(StandardCharsets.UTF_8), "Generic") { + @Override + public byte[] getEncoded() { + return null; + } + }; + + assertThrows(InvalidKeySpecException.class, () -> skf.generateSecret(badFormat)); + assertThrows(InvalidKeySpecException.class, () -> skf.generateSecret(nullEncoding)); + assertThrows(InvalidKeySpecException.class, () -> skf.generateSecret(nullFormat)); + } + @ParameterizedTest @MethodSource("supportedHmacs") public void supportsCloneable(final String algorithm) throws Exception { @@ -536,6 +715,39 @@ public void testDraggedState(final String algorithm) throws Exception { assertArraysHexEquals(expected2, duplicate.doFinal(suffix2)); } + @ParameterizedTest + @MethodSource("supportedHmacs") + // Suppress redundant cast warnings; they're redundant in java 9 but not java 8 + @SuppressWarnings({"cast", "RedundantCast"}) + public void testWithPrecomputedKey(final String algorithm) throws Exception { + assumePrecomputedKeySupport(); + + final SecretKeySpec key = + new SecretKeySpec("YellowSubmarine".getBytes(StandardCharsets.US_ASCII), "Generic"); + final byte[] msg = "This is a test message".getBytes(StandardCharsets.US_ASCII); + final Mac jceMac = Mac.getInstance(algorithm, "SunJCE"); + jceMac.init(key); + jceMac.update(msg); + final byte[] expected = jceMac.doFinal(); + + // Compute without precomputed key (sanity check) + Mac nativeMac = Mac.getInstance(algorithm, NATIVE_PROVIDER); + nativeMac.init(key); + nativeMac.update(msg); + assertArrayEquals(expected, nativeMac.doFinal()); + + // Compute the precomputed key + SecretKeyFactory skf = + SecretKeyFactory.getInstance(algorithm + "WithPrecomputedKey", NATIVE_PROVIDER); + SecretKey precomputedKey = skf.generateSecret(key); + + // Check that the computation with the precomputed key matches + nativeMac = Mac.getInstance(algorithm + "WithPrecomputedKey", NATIVE_PROVIDER); + nativeMac.init(precomputedKey); + nativeMac.update(msg); + assertArrayEquals(expected, nativeMac.doFinal()); + } + @ParameterizedTest @MethodSource("supportedHmacs") public void selfTest(final String algorithm) throws Throwable {