- enabled more IANA algorithms in StandardHashAlgorithms

lhazlewood · lhazlewood · commit 383517eac432 · 2023-03-21T19:47:47.000-07:00
- JavaDoc update
diff --git a/api/src/main/java/io/jsonwebtoken/lang/Registry.java b/api/src/main/java/io/jsonwebtoken/lang/Registry.java
@@ -17,11 +17,39 @@
 
 import java.util.Collection;
 
+/**
+ * An immutable read-only repository of key-value pairs.
+ *
+ * @param <K> key type
+ * @param <V> value type
+ * @since JJWT_RELEASE_VERSION
+ */
 public interface Registry<K, V> {
 
+    /**
+     * Returns all registry values as a read-only collection.
+     *
+     * @return all registry values as a read-only collection.
+     */
     Collection<V> values();
 
+    /**
+     * Returns the value assigned the specified key or throws an {@code IllegalArgumentException} if there is no
+     * associated value.  If a value is not required, consider using the {@link #find(Object)} method instead.
+     *
+     * @param key the registry key assigned to the required value
+     * @return the value assigned the specified key
+     * @throws IllegalArgumentException if there is no value assigned the specified key
+     * @see #find(Object)
+     */
     V get(K key) throws IllegalArgumentException;
 
+    /**
+     * Returns the value assigned the specified key or {@code null} if there is no associated value.
+     *
+     * @param key the registry key assigned to the required value
+     * @return the value assigned the specified key or {@code null} if there is no associated value.
+     * @see #get(Object)
+     */
     V find(K key);
 }
diff --git a/api/src/main/java/io/jsonwebtoken/security/StandardHashAlgorithms.java b/api/src/main/java/io/jsonwebtoken/security/StandardHashAlgorithms.java
@@ -45,6 +45,7 @@
  * @see #find(String)
  * @see #get(String)
  * @see HashAlgorithm
+ * @since JJWT_RELEASE_VERSION
  */
 public final class StandardHashAlgorithms implements Registry<String, HashAlgorithm> {
 
@@ -65,12 +66,57 @@ public static StandardHashAlgorithms get() { // named `get` to mimic java.util.f
     /**
      * <a href="https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg">IANA
      * hash algorithm</a> with an {@link Identifiable#getId() id} (aka IANA &quot;{@code Hash Name String}&quot;)
-     * value of {@code sha-256}.  Per the IANA registry, this algorithm is defined by
-     * <a href="https://www.rfc-editor.org/rfc/rfc6920.html">RFC 6920</a> and is the same as the
-     * native Java JCA {@code SHA-256} {@code MessageDigest} algorithm.
+     * value of {@code sha-256}. It is a {@code HashAlgorithm} alias for the native
+     * Java JCA {@code SHA-256} {@code MessageDigest} algorithm.
      */
     public final HashAlgorithm SHA256 = get("sha-256");
 
+    /**
+     * <a href="https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg">IANA
+     * hash algorithm</a> with an {@link Identifiable#getId() id} (aka IANA &quot;{@code Hash Name String}&quot;)
+     * value of {@code sha-384}. It is a {@code HashAlgorithm} alias for the native
+     * Java JCA {@code SHA-384} {@code MessageDigest} algorithm.
+     */
+    public final HashAlgorithm SHA384 = get("sha-384");
+
+    /**
+     * <a href="https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg">IANA
+     * hash algorithm</a> with an {@link Identifiable#getId() id} (aka IANA &quot;{@code Hash Name String}&quot;)
+     * value of {@code sha-512}. It is a {@code HashAlgorithm} alias for the native
+     * Java JCA {@code SHA-512} {@code MessageDigest} algorithm.
+     */
+    public final HashAlgorithm SHA512 = get("sha-512");
+
+    /**
+     * <a href="https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg">IANA
+     * hash algorithm</a> with an {@link Identifiable#getId() id} (aka IANA &quot;{@code Hash Name String}&quot;)
+     * value of {@code sha3-256}. It is a {@code HashAlgorithm} alias for the native
+     * Java JCA {@code SHA3-256} {@code MessageDigest} algorithm.
+     * <p><b>This algorithm requires at least JDK 9 or a compatible JCA Provider (like BouncyCastle) in the runtime
+     * classpath.</b></p>
+     */
+    public final HashAlgorithm SHA3_256 = get("sha3-256");
+
+    /**
+     * <a href="https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg">IANA
+     * hash algorithm</a> with an {@link Identifiable#getId() id} (aka IANA &quot;{@code Hash Name String}&quot;)
+     * value of {@code sha3-384}. It is a {@code HashAlgorithm} alias for the native
+     * Java JCA {@code SHA3-384} {@code MessageDigest} algorithm.
+     * <p><b>This algorithm requires at least JDK 9 or a compatible JCA Provider (like BouncyCastle) in the runtime
+     * classpath.</b></p>
+     */
+    public final HashAlgorithm SHA3_384 = get("sha3-384");
+
+    /**
+     * <a href="https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg">IANA
+     * hash algorithm</a> with an {@link Identifiable#getId() id} (aka IANA &quot;{@code Hash Name String}&quot;)
+     * value of {@code sha3-512}. It is a {@code HashAlgorithm} alias for the native
+     * Java JCA {@code SHA3-512} {@code MessageDigest} algorithm.
+     * <p><b>This algorithm requires at least JDK 9 or a compatible JCA Provider (like BouncyCastle) in the runtime
+     * classpath.</b></p>
+     */
+    public final HashAlgorithm SHA3_512 = get("sha3-512");
+
     /**
      * Prevent external instantiation.
      */
diff --git a/impl/src/main/java/io/jsonwebtoken/impl/security/AbstractJwk.java b/impl/src/main/java/io/jsonwebtoken/impl/security/AbstractJwk.java
@@ -28,6 +28,7 @@
 import io.jsonwebtoken.security.HashAlgorithm;
 import io.jsonwebtoken.security.Jwk;
 import io.jsonwebtoken.security.JwkThumbprint;
+import io.jsonwebtoken.security.Jwks;
 
 import java.nio.charset.StandardCharsets;
 import java.security.Key;
@@ -100,7 +101,7 @@ private String toThumbprintJson() {
 
     @Override
     public JwkThumbprint thumbprint() {
-        return thumbprint(DefaultHashAlgorithm.SHA256);
+        return thumbprint(Jwks.HASH.SHA256);
     }
 
     @Override
diff --git a/impl/src/main/java/io/jsonwebtoken/impl/security/AbstractJwkBuilder.java b/impl/src/main/java/io/jsonwebtoken/impl/security/AbstractJwkBuilder.java
@@ -19,6 +19,7 @@
 import io.jsonwebtoken.security.HashAlgorithm;
 import io.jsonwebtoken.security.Jwk;
 import io.jsonwebtoken.security.JwkBuilder;
+import io.jsonwebtoken.security.Jwks;
 import io.jsonwebtoken.security.MalformedKeyException;
 import io.jsonwebtoken.security.SecretJwk;
 import io.jsonwebtoken.security.SecretJwkBuilder;
@@ -108,7 +109,7 @@ public T setId(String id) {
 
     @Override
     public T setIdFromThumbprint() {
-        return setIdFromThumbprint(DefaultHashAlgorithm.SHA256);
+        return setIdFromThumbprint(Jwks.HASH.SHA256);
     }
 
     @Override
diff --git a/impl/src/main/java/io/jsonwebtoken/impl/security/DefaultHashAlgorithm.java b/impl/src/main/java/io/jsonwebtoken/impl/security/DefaultHashAlgorithm.java
@@ -22,14 +22,20 @@
 import io.jsonwebtoken.security.VerifyDigestRequest;
 
 import java.security.MessageDigest;
+import java.security.Provider;
+import java.util.Locale;
 
 public final class DefaultHashAlgorithm extends CryptoAlgorithm implements HashAlgorithm {
 
-    public static final HashAlgorithm SHA1 = new DefaultHashAlgorithm("sha-1", "SHA-1");
-    public static final HashAlgorithm SHA256 = new DefaultHashAlgorithm("sha-256", "SHA-256");
+    public static final HashAlgorithm SHA1 = new DefaultHashAlgorithm("sha-1");
 
-    DefaultHashAlgorithm(String id, String jcaName) {
+    DefaultHashAlgorithm(String id) {
+        super(id, id.toUpperCase(Locale.ENGLISH));
+    }
+
+    DefaultHashAlgorithm(String id, String jcaName, Provider provider) {
         super(id, jcaName);
+        setProvider(provider);
     }
 
     @Override
diff --git a/impl/src/main/java/io/jsonwebtoken/impl/security/DefaultX509Builder.java b/impl/src/main/java/io/jsonwebtoken/impl/security/DefaultX509Builder.java
@@ -23,6 +23,7 @@
 import io.jsonwebtoken.lang.Objects;
 import io.jsonwebtoken.security.HashAlgorithm;
 import io.jsonwebtoken.security.Request;
+import io.jsonwebtoken.security.StandardHashAlgorithms;
 import io.jsonwebtoken.security.X509Builder;
 import io.jsonwebtoken.security.X509Mutator;
 
@@ -127,7 +128,7 @@ public void apply() {
                 setX509CertificateSha1Thumbprint(thumbprint);
             }
             if (computeX509Sha256Thumbprint) {
-                byte[] thumbprint = computeThumbprint(firstCert, DefaultHashAlgorithm.SHA256);
+                byte[] thumbprint = computeThumbprint(firstCert, StandardHashAlgorithms.get().SHA256);
                 setX509CertificateSha256Thumbprint(thumbprint);
             }
         }
diff --git a/impl/src/main/java/io/jsonwebtoken/impl/security/StandardHashAlgorithmsBridge.java b/impl/src/main/java/io/jsonwebtoken/impl/security/StandardHashAlgorithmsBridge.java
@@ -15,21 +15,56 @@
  */
 package io.jsonwebtoken.impl.security;
 
+import io.jsonwebtoken.impl.lang.CheckedSupplier;
+import io.jsonwebtoken.impl.lang.Conditions;
 import io.jsonwebtoken.impl.lang.IdRegistry;
+import io.jsonwebtoken.lang.Assert;
 import io.jsonwebtoken.lang.Collections;
-import io.jsonwebtoken.security.DigestAlgorithm;
 import io.jsonwebtoken.security.HashAlgorithm;
 
+import java.security.MessageDigest;
+import java.security.Provider;
+import java.util.Locale;
+
 /**
- * Static class definitions for standard {@link DigestAlgorithm} instances.
+ * Backing implementation for the {@link io.jsonwebtoken.security.StandardHashAlgorithms} implementation.
  *
  * @since JJWT_RELEASE_VERSION
  */
 @SuppressWarnings("unused") // used via reflection in io.jsonwebtoken.security.StandardHashAlgorithms
 public class StandardHashAlgorithmsBridge extends DelegatingRegistry<HashAlgorithm> {
+
     public StandardHashAlgorithmsBridge() {
         super(new IdRegistry<>("IANA Hash Algorithm", Collections.of(
-                DefaultHashAlgorithm.SHA256
+                // We don't include DefaultHashAlgorithm.SHA1 here on purpose because 1) it's not in the JWK IANA
+                // registry so we don't need to expose it anyway, and 2) we don't want to expose a less-safe algorithm.
+                // The SHA1 instance only exists in JJWT's codebase to support RFC-required `x5t`
+                // (X.509 SHA-1 Thumbprint) computation - we don't use it anywhere else.
+                (HashAlgorithm) new DefaultHashAlgorithm("sha-256"),
+                new DefaultHashAlgorithm("sha-384"),
+                new DefaultHashAlgorithm("sha-512"),
+                fallbackProvider("sha3-256"),
+                fallbackProvider("sha3-384"),
+                fallbackProvider("sha3-512")
         )));
     }
+
+    private static DefaultHashAlgorithm fallbackProvider(String id) {
+        String jcaName = id.toUpperCase(Locale.ENGLISH);
+        Provider provider = Providers.findBouncyCastle(Conditions.notExists(new MessageDigestSupplier(jcaName)));
+        return new DefaultHashAlgorithm(id, jcaName, provider);
+    }
+
+    private static class MessageDigestSupplier implements CheckedSupplier<MessageDigest> {
+        private final String jcaName;
+
+        private MessageDigestSupplier(String jcaName) {
+            this.jcaName = Assert.hasText(jcaName, "jcaName cannot be null or empty.");
+        }
+
+        @Override
+        public MessageDigest get() throws Exception {
+            return MessageDigest.getInstance(jcaName);
+        }
+    }
 }
diff --git a/impl/src/test/groovy/io/jsonwebtoken/impl/DefaultDynamicHeaderBuilderTest.groovy b/impl/src/test/groovy/io/jsonwebtoken/impl/DefaultDynamicHeaderBuilderTest.groovy
@@ -25,6 +25,7 @@ import io.jsonwebtoken.impl.security.TestKeys
 import io.jsonwebtoken.io.Encoders
 import io.jsonwebtoken.security.Jwks
 import io.jsonwebtoken.security.Request
+import io.jsonwebtoken.security.StandardHashAlgorithms
 import org.junit.Before
 import org.junit.Test
 
@@ -181,7 +182,7 @@ class DefaultDynamicHeaderBuilderTest {
     void testSetX509CertificateSha256ThumbprintEnabled() {
         def chain = TestKeys.RS256.chain
         Request<byte[]> request = new DefaultRequest(chain[0].getEncoded(), null, null)
-        def x5tS256 = DefaultHashAlgorithm.SHA256.digest(request)
+        def x5tS256 = StandardHashAlgorithms.get().SHA256.digest(request)
         String encoded = Encoders.BASE64URL.encode(x5tS256)
         def header = builder.setX509CertificateChain(chain).withX509Sha256Thumbprint(true).build() as JwsHeader
         assertTrue header instanceof JwsHeader
diff --git a/impl/src/test/groovy/io/jsonwebtoken/impl/DefaultJwsHeaderBuilderTest.groovy b/impl/src/test/groovy/io/jsonwebtoken/impl/DefaultJwsHeaderBuilderTest.groovy
@@ -21,6 +21,7 @@ import io.jsonwebtoken.impl.security.TestKeys
 import io.jsonwebtoken.io.Encoders
 import io.jsonwebtoken.security.Jwks
 import io.jsonwebtoken.security.Request
+import io.jsonwebtoken.security.StandardHashAlgorithms
 import org.junit.Before
 import org.junit.Test
 
@@ -95,7 +96,7 @@ class DefaultJwsHeaderBuilderTest {
     @Test
     void testSetX509CertificateSha256Thumbprint() {
         Request<byte[]> request = new DefaultRequest(TestKeys.RS256.cert.getEncoded(), null, null)
-        def x5tS256 = DefaultHashAlgorithm.SHA256.digest(request)
+        def x5tS256 = StandardHashAlgorithms.get().SHA256.digest(request)
         String encoded = Encoders.BASE64URL.encode(x5tS256)
         def header = builder.setX509CertificateSha256Thumbprint(x5tS256).build()
         assertArrayEquals x5tS256, header.getX509CertificateSha256Thumbprint()
@@ -106,7 +107,7 @@ class DefaultJwsHeaderBuilderTest {
     void testSetX509CertificateSha256ThumbprintEnabled() {
         def chain = TestKeys.RS256.chain
         Request<byte[]> request = new DefaultRequest(chain[0].getEncoded(), null, null)
-        def x5tS256 = DefaultHashAlgorithm.SHA256.digest(request)
+        def x5tS256 = StandardHashAlgorithms.get().SHA256.digest(request)
         String encoded = Encoders.BASE64URL.encode(x5tS256)
         def header = builder.setX509CertificateChain(chain).withX509Sha256Thumbprint(true).build()
         assertArrayEquals x5tS256, header.getX509CertificateSha256Thumbprint()
diff --git a/impl/src/test/groovy/io/jsonwebtoken/impl/security/AbstractAsymmetricJwkBuilderTest.groovy b/impl/src/test/groovy/io/jsonwebtoken/impl/security/AbstractAsymmetricJwkBuilderTest.groovy
@@ -85,7 +85,7 @@ class AbstractAsymmetricJwkBuilderTest {
     @Test
     void testX509CertificateSha256Thumbprint() {
         Request<byte[]> request = new DefaultRequest(TestKeys.RS256.cert.getEncoded(), null, null)
-        def x5tS256 = DefaultHashAlgorithm.SHA256.digest(request)
+        def x5tS256 = StandardHashAlgorithms.get().SHA256.digest(request)
         def encoded = Encoders.BASE64URL.encode(x5tS256)
         def jwk = builder().setX509CertificateSha256Thumbprint(x5tS256).build()
         assertArrayEquals x5tS256, jwk.getX509CertificateSha256Thumbprint()
@@ -95,7 +95,7 @@ class AbstractAsymmetricJwkBuilderTest {
     @Test
     void testX509CertificateSha256ThumbprintEnabled() {
         Request<byte[]> request = new DefaultRequest(TestKeys.RS256.cert.getEncoded(), null, null)
-        def x5tS256 = DefaultHashAlgorithm.SHA256.digest(request)
+        def x5tS256 = StandardHashAlgorithms.get().SHA256.digest(request)
         def encoded = Encoders.BASE64URL.encode(x5tS256)
         def jwk = builder().setX509CertificateChain(CHAIN).withX509Sha256Thumbprint(true).build()
         assertArrayEquals x5tS256, jwk.getX509CertificateSha256Thumbprint()
diff --git a/impl/src/test/groovy/io/jsonwebtoken/impl/security/DefaultHashAlgorithmTest.groovy b/impl/src/test/groovy/io/jsonwebtoken/impl/security/DefaultHashAlgorithmTest.groovy
@@ -16,6 +16,7 @@
 package io.jsonwebtoken.impl.security
 
 import io.jsonwebtoken.security.HashAlgorithm
+import io.jsonwebtoken.security.StandardHashAlgorithms
 import org.junit.Test
 
 import java.nio.charset.StandardCharsets
@@ -24,12 +25,12 @@ import static org.junit.Assert.assertTrue
 
 class DefaultHashAlgorithmTest {
 
-    static final def algs = [DefaultHashAlgorithm.SHA1, DefaultHashAlgorithm.SHA256]
+    static final def algs = [DefaultHashAlgorithm.SHA1, StandardHashAlgorithms.get().SHA256]
 
     @Test
     void testDigestAndVerify() {
         byte[] data = "Hello World".getBytes(StandardCharsets.UTF_8)
-        for(HashAlgorithm alg : algs) {
+        for (HashAlgorithm alg : algs) {
             byte[] hash = alg.digest(new DefaultRequest<byte[]>(data, null, null))
             assertTrue alg.verify(new DefaultVerifyDigestRequest(data, null, null, hash))
         }
diff --git a/impl/src/test/groovy/io/jsonwebtoken/impl/security/DefaultJwkThumbprintTest.groovy b/impl/src/test/groovy/io/jsonwebtoken/impl/security/DefaultJwkThumbprintTest.groovy
@@ -17,6 +17,7 @@ package io.jsonwebtoken.impl.security
 
 import io.jsonwebtoken.io.Encoders
 import io.jsonwebtoken.security.HashAlgorithm
+import io.jsonwebtoken.security.StandardHashAlgorithms
 import org.junit.Before
 import org.junit.Test
 
@@ -28,7 +29,7 @@ import static org.junit.Assert.*
 class DefaultJwkThumbprintTest {
 
     private static String content = "Hello World"
-    private static HashAlgorithm alg = DefaultHashAlgorithm.SHA256
+    private static HashAlgorithm alg = StandardHashAlgorithms.get().SHA256
     private static byte[] digest = alg.digest(new DefaultRequest<byte[]>(content.getBytes(StandardCharsets.UTF_8), null, null))
     private static String expectedToString = Encoders.BASE64URL.encode(digest)
     private static String expectedUriString = DefaultJwkThumbprint.URI_PREFIX + alg.getId() + ":" + expectedToString
@@ -74,7 +75,7 @@ class DefaultJwkThumbprintTest {
     @Test
     void testNotEquals() {
         // invalid data type:
-        assertNotEquals new DefaultJwkThumbprint(digest, DefaultHashAlgorithm.SHA256), new Object()
+        assertNotEquals new DefaultJwkThumbprint(digest, alg), new Object()
 
         // same digest, different alg:
         assertFalse thumbprint == new DefaultJwkThumbprint(digest, DefaultHashAlgorithm.SHA1)
diff --git a/impl/src/test/groovy/io/jsonwebtoken/impl/security/HashAlgorithmsTest.groovy b/impl/src/test/groovy/io/jsonwebtoken/impl/security/HashAlgorithmsTest.groovy
diff --git a/impl/src/test/groovy/io/jsonwebtoken/impl/security/JwkThumbprintsTest.groovy b/impl/src/test/groovy/io/jsonwebtoken/impl/security/JwkThumbprintsTest.groovy

Original file line number	Diff line number	Diff line change
`@@ -23,6 +23,7 @@`
`23`	`23`	`import io.jsonwebtoken.lang.Objects;`
`24`	`24`	`import io.jsonwebtoken.security.HashAlgorithm;`
`25`	`25`	`import io.jsonwebtoken.security.Request;`
	`26`	`+import io.jsonwebtoken.security.StandardHashAlgorithms;`
`26`	`27`	`import io.jsonwebtoken.security.X509Builder;`
`27`	`28`	`import io.jsonwebtoken.security.X509Mutator;`
`28`	`29`
`@@ -127,7 +128,7 @@ public void apply() {`
`127`	`128`	`setX509CertificateSha1Thumbprint(thumbprint);`
`128`	`129`	`}`
`129`	`130`	`if (computeX509Sha256Thumbprint) {`
`130`		`- byte[] thumbprint = computeThumbprint(firstCert, DefaultHashAlgorithm.SHA256);`
	`131`	`+ byte[] thumbprint = computeThumbprint(firstCert, StandardHashAlgorithms.get().SHA256);`
`131`	`132`	`setX509CertificateSha256Thumbprint(thumbprint);`
`132`	`133`	`}`
`133`	`134`	`}`