Migrated all uses of Jwts.SIG to Jws.alg

Author: lhazlewood

README.adoc

@@ -738,7 +738,7 @@ import java.security.Key;
 
 // We need a signing key, so we'll create one just for this example. Usually
 // the key would be read from your application configuration instead.
-SecretKey key = Jwts.SIG.HS256.key().build();
+SecretKey key = Jws.alg.HS256.key().build();
 
 String jws = Jwts.builder().subject("Joe").signWith(key).compact();
 ----
@@ -1611,7 +1611,7 @@ key algorithms:
 
 ^*2*.{sp}{fn-require-java15-plus}^
 
-These are all represented as constants in the `io.jsonwebtoken.Jwts.SIG` registry class.
+These are all represented as constants in the `io.jsonwebtoken.Jws.alg` registry class.
 
 +++<a name="jws-key">++++++</a>+++
 
@@ -1705,7 +1705,7 @@ algorithm's `key()` builder method:
 
 [,java]
 ----
-SecretKey key = Jwts.SIG.HS256.key().build(); //or HS384.key() or HS512.key()
+SecretKey key = Jws.alg.HS256.key().build(); //or HS384.key() or HS512.key()
 ----
 
 Under the hood, JJWT uses the JCA default provider's `KeyGenerator` to create a secure-random key with the correct
@@ -1716,7 +1716,7 @@ as builder arguments. For example:
 
 [,java]
 ----
-SecretKey key = Jwts.SIG.HS256.key().provider(aProvider).random(aSecureRandom).build();
+SecretKey key = Jws.alg.HS256.key().provider(aProvider).random(aSecureRandom).build();
 ----
 
 If you need to save this new `SecretKey`, you can Base64 (or Base64URL) encode it:
@@ -1739,7 +1739,7 @@ algorithms, use an algorithm's respective `keyPair()` builder method:
 
 [,java]
 ----
-KeyPair keyPair = Jwts.SIG.RS256.keyPair().build(); //or RS384, RS512, PS256, etc...
+KeyPair keyPair = Jws.alg.RS256.keyPair().build(); //or RS384, RS512, PS256, etc...
 ----
 
 Once you've generated a `KeyPair`, you can use the private key (`keyPair.getPrivate()`) to create a JWS and the
@@ -1874,7 +1874,7 @@ that accepts the `SignatureAlgorithm` as an additional argument:
 [,java]
 ----
 
-   .signWith(privateKey, Jwts.SIG.RS512) // <---
+   .signWith(privateKey, Jws.alg.RS512) // <---
 
    .compact();
 ----
@@ -2062,7 +2062,7 @@ We need to do three things during creation:
 [,java]
 ----
 // create a test key for this example:
-SecretKey testKey = Jwts.SIG.HS512.key().build();
+SecretKey testKey = Jws.alg.HS512.key().build();
 
 String message = "Hello World. It's a Beautiful Day!";
 byte[] content = message.getBytes(StandardCharsets.UTF_8);
@@ -2105,7 +2105,7 @@ period (`.`) characters_*.
 [,java]
 ----
 // create a test key for this example:
-SecretKey testKey = Jwts.SIG.HS512.key().build();
+SecretKey testKey = Jws.alg.HS512.key().build();
 
 String claimsString = "{\"sub\":\"joe\",\"iss\":\"me\"}";
 
@@ -3740,7 +3740,7 @@ Example:
 [,java]
 ----
 // Create a test key suitable for the desired HMAC-SHA algorithm:
-MacAlgorithm alg = Jwts.SIG.HS512; //or HS384 or HS256
+MacAlgorithm alg = Jws.alg.HS512; //or HS384 or HS256
 SecretKey key = alg.key().build();
 
 String message = "Hello World!";
@@ -3769,7 +3769,7 @@ public key:
 [,java]
 ----
 // Create a test key suitable for the desired RSA signature algorithm:
-SignatureAlgorithm alg = Jwts.SIG.RS512; //or PS512, RS256, etc...
+SignatureAlgorithm alg = Jws.alg.RS512; //or PS512, RS256, etc...
 KeyPair pair = alg.keyPair().build();
 
 // Bob creates the compact JWS with his RSA private key:
@@ -3802,7 +3802,7 @@ public key:
 [,java]
 ----
 // Create a test key suitable for the desired ECDSA signature algorithm:
-SignatureAlgorithm alg = Jwts.SIG.ES512; //or ES256 or ES384
+SignatureAlgorithm alg = Jws.alg.ES512; //or ES256 or ES384
 KeyPair pair = alg.keyPair().build();
 
 // Bob creates the compact JWS with his EC private key:
@@ -3854,7 +3854,7 @@ KeyPair pair = curve.keyPair().build();
 
 // Bob creates the compact JWS with his Edwards Curve private key:
 String jws = Jwts.builder().subject("Alice")
-    .signWith(pair.getPrivate(), Jwts.SIG.EdDSA) // <-- Bob's Edwards Curve private key w/ EdDSA
+    .signWith(pair.getPrivate(), Jws.alg.EdDSA) // <-- Bob's Edwards Curve private key w/ EdDSA
     .compact();
 
 // Alice receives and verifies the compact JWS came from Bob:
@@ -3922,7 +3922,7 @@ decrypt the JWT using her RSA private key:
 [,java]
 ----
 // Create a test KeyPair suitable for the desired RSA key algorithm:
-KeyPair pair = Jwts.SIG.RS512.keyPair().build();
+KeyPair pair = Jws.alg.RS512.keyPair().build();
 
 // Choose the key algorithm used encrypt the payload key:
 KeyAlgorithm<PublicKey, PrivateKey> alg = Jwts.KEY.RSA_OAEP_256; //or RSA_OAEP or RSA1_5
@@ -3994,7 +3994,7 @@ Alice can then decrypt the JWT using her Elliptic Curve private key:
 [,java]
 ----
 // Create a test KeyPair suitable for the desired EC key algorithm:
-KeyPair pair = Jwts.SIG.ES512.keyPair().build();
+KeyPair pair = Jws.alg.ES512.keyPair().build();
 
 // Choose the key algorithm used encrypt the payload key:
 KeyAlgorithm<PublicKey, PrivateKey> alg = Jwts.KEY.ECDH_ES_A256KW; //ECDH_ES_A192KW, etc...
@@ -4070,7 +4070,7 @@ Example creating and parsing a secret JWK:
 
 [,java]
 ----
-SecretKey key = Jwts.SIG.HS512.key().build(); // or HS384 or HS256
+SecretKey key = Jws.alg.HS512.key().build(); // or HS384 or HS256
 SecretJwk jwk = Jwks.builder().key(key).idFromThumbprint().build();
 
 assert jwk.getId().equals(jwk.thumbprint().toString());
@@ -4092,7 +4092,7 @@ Example creating and parsing an RSA Public JWK:
 
 [,java]
 ----
-RSAPublicKey key = (RSAPublicKey)Jwts.SIG.RS512.keyPair().build().getPublic();
+RSAPublicKey key = (RSAPublicKey)Jws.alg.RS512.keyPair().build().getPublic();
 RsaPublicJwk jwk = Jwks.builder().key(key).idFromThumbprint().build();
 
 assert jwk.getId().equals(jwk.thumbprint().toString());
@@ -4114,7 +4114,7 @@ Example creating and parsing an RSA Private JWK:
 
 [,java]
 ----
-KeyPair pair = Jwts.SIG.RS512.keyPair().build();
+KeyPair pair = Jws.alg.RS512.keyPair().build();
 RSAPublicKey pubKey = (RSAPublicKey) pair.getPublic();
 RSAPrivateKey privKey = (RSAPrivateKey) pair.getPrivate();
 
@@ -4142,7 +4142,7 @@ Example creating and parsing an Elliptic Curve Public JWK:
 
 [,java]
 ----
-ECPublicKey key = (ECPublicKey) Jwts.SIG.ES512.keyPair().build().getPublic();
+ECPublicKey key = (ECPublicKey) Jws.alg.ES512.keyPair().build().getPublic();
 EcPublicJwk jwk = Jwks.builder().key(key).idFromThumbprint().build();
 
 assert jwk.getId().equals(jwk.thumbprint().toString());
@@ -4164,7 +4164,7 @@ Example creating and parsing an Elliptic Curve Private JWK:
 
 [,java]
 ----
-KeyPair pair = Jwts.SIG.ES512.keyPair().build();
+KeyPair pair = Jws.alg.ES512.keyPair().build();
 ECPublicKey pubKey = (ECPublicKey) pair.getPublic();
 ECPrivateKey privKey = (ECPrivateKey) pair.getPrivate();
 

api/src/main/java/io/jsonwebtoken/Header.java

@@ -130,7 +130,7 @@ public interface Header extends Map<String, Object> {
      * <ul>
      *     <li>If the JWT is a Signed JWT (a JWS), the <a href="https://tools.ietf.org/html/rfc7515#section-4.1.1">
      *      <code>alg</code></a> (Algorithm) header parameter identifies the cryptographic algorithm used to secure the
-     *      JWS.  Consider using {@link Jwts.SIG}.{@link io.jsonwebtoken.lang.Registry#get(Object) get(id)}
+     *      JWS.  Consider using {@link Jws.alg}.{@link io.jsonwebtoken.lang.Registry#get(Object) get(id)}
      *      to convert this string value to a type-safe {@code SecureDigestAlgorithm} instance.</li>
      *      <li>If the JWT is an Encrypted JWT (a JWE), the
      * <a href="https://tools.ietf.org/html/rfc7516#section-4.1.1"><code>alg</code></a> (Algorithm) header parameter

api/src/main/java/io/jsonwebtoken/Jws.java

@@ -15,6 +15,14 @@
  */
 package io.jsonwebtoken;
 
+import io.jsonwebtoken.lang.Classes;
+import io.jsonwebtoken.lang.Registry;
+import io.jsonwebtoken.security.KeyPairBuilderSupplier;
+import io.jsonwebtoken.security.MacAlgorithm;
+import io.jsonwebtoken.security.SecureDigestAlgorithm;
+
+import java.security.Key;
+
 /**
  * An expanded (not compact/serialized) Signed JSON Web Token.
  *
@@ -23,6 +31,169 @@
  */
 public interface Jws<P> extends ProtectedJwt<JwsHeader, P> {
 
+    /**
+     * Constants for all JWA (RFC 7518) standard <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3">
+     * Cryptographic Algorithms for Digital Signatures and MACs</a> defined in the
+     * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-7.1">JSON Web Signature and Encryption Algorithms
+     * Registry</a>. Each standard algorithm is available as a ({@code public static final}) constant for
+     * direct type-safe reference in application code. For example:
+     * <blockquote><pre>
+     * Jwts.builder()
+     *    // ... etc ...
+     *    .signWith(aKey, <b>Jws.alg.HS512</b>) // or RS512, PS256, EdDSA, etc...
+     *    .build();</pre></blockquote>
+     * <p>They are also available together as a {@link Registry} instance via the {@link #registry()} method.</p>
+     *
+     * @see #registry()
+     * @since JJWT_RELEASE_VERSION
+     */
+    final class alg {
+
+        private static final String IMPL_CLASSNAME = "io.jsonwebtoken.impl.security.StandardSecureDigestAlgorithms";
+        private static final Registry<String, SecureDigestAlgorithm<?, ?>> REGISTRY = Classes.newInstance(IMPL_CLASSNAME);
+
+        //prevent instantiation
+        private alg() {
+        }
+
+        /**
+         * Returns all standard JWA <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3">Cryptographic
+         * Algorithms for Digital Signatures and MACs</a> defined in the
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-7.1">JSON Web Signature and Encryption
+         * Algorithms Registry</a>.
+         *
+         * @return all standard JWA digital signature and MAC algorithms.
+         */
+        public static Registry<String, SecureDigestAlgorithm<?, ?>> registry() {
+            return REGISTRY;
+        }
+
+        /**
+         * The &quot;none&quot; signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.6">RFC 7518, Section 3.6</a>.  This algorithm
+         * is used only when creating unsecured (not integrity protected) JWSs and is not usable in any other scenario.
+         * Any attempt to call its methods will result in an exception being thrown.
+         */
+        public static final SecureDigestAlgorithm<Key, Key> NONE = Jwts.get(REGISTRY, "none");
+
+        /**
+         * {@code HMAC using SHA-256} message authentication algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.2">RFC 7518, Section 3.2</a>.  This algorithm
+         * requires a 256-bit (32 byte) key.
+         */
+        public static final MacAlgorithm HS256 = Jwts.get(REGISTRY, "HS256");
+
+        /**
+         * {@code HMAC using SHA-384} message authentication algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.2">RFC 7518, Section 3.2</a>.  This algorithm
+         * requires a 384-bit (48 byte) key.
+         */
+        public static final MacAlgorithm HS384 = Jwts.get(REGISTRY, "HS384");
+
+        /**
+         * {@code HMAC using SHA-512} message authentication algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.2">RFC 7518, Section 3.2</a>.  This algorithm
+         * requires a 512-bit (64 byte) key.
+         */
+        public static final MacAlgorithm HS512 = Jwts.get(REGISTRY, "HS512");
+
+        /**
+         * {@code RSASSA-PKCS1-v1_5 using SHA-256} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3">RFC 7518, Section 3.3</a>.  This algorithm
+         * requires a 2048-bit key.
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm RS256 = Jwts.get(REGISTRY, "RS256");
+
+        /**
+         * {@code RSASSA-PKCS1-v1_5 using SHA-384} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3">RFC 7518, Section 3.3</a>.  This algorithm
+         * requires a 2048-bit key, but the JJWT team recommends a 3072-bit key.
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm RS384 = Jwts.get(REGISTRY, "RS384");
+
+        /**
+         * {@code RSASSA-PKCS1-v1_5 using SHA-512} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3">RFC 7518, Section 3.3</a>.  This algorithm
+         * requires a 2048-bit key, but the JJWT team recommends a 4096-bit key.
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm RS512 = Jwts.get(REGISTRY, "RS512");
+
+        /**
+         * {@code RSASSA-PSS using SHA-256 and MGF1 with SHA-256} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.5">RFC 7518, Section 3.5</a><b><sup>1</sup></b>.
+         * This algorithm requires a 2048-bit key.
+         *
+         * <p><b><sup>1</sup></b> Requires Java 11 or a compatible JCA Provider (like BouncyCastle) in the runtime
+         * classpath. If on Java 10 or earlier, BouncyCastle will be used automatically if found in the runtime
+         * classpath.</p>
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm PS256 = Jwts.get(REGISTRY, "PS256");
+
+        /**
+         * {@code RSASSA-PSS using SHA-384 and MGF1 with SHA-384} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.5">RFC 7518, Section 3.5</a><b><sup>1</sup></b>.
+         * This algorithm requires a 2048-bit key, but the JJWT team recommends a 3072-bit key.
+         *
+         * <p><b><sup>1</sup></b> Requires Java 11 or a compatible JCA Provider (like BouncyCastle) in the runtime
+         * classpath. If on Java 10 or earlier, BouncyCastle will be used automatically if found in the runtime
+         * classpath.</p>
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm PS384 = Jwts.get(REGISTRY, "PS384");
+
+        /**
+         * {@code RSASSA-PSS using SHA-512 and MGF1 with SHA-512} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.5">RFC 7518, Section 3.5</a><b><sup>1</sup></b>.
+         * This algorithm requires a 2048-bit key, but the JJWT team recommends a 4096-bit key.
+         *
+         * <p><b><sup>1</sup></b> Requires Java 11 or a compatible JCA Provider (like BouncyCastle) in the runtime
+         * classpath. If on Java 10 or earlier, BouncyCastle will be used automatically if found in the runtime
+         * classpath.</p>
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm PS512 = Jwts.get(REGISTRY, "PS512");
+
+        /**
+         * {@code ECDSA using P-256 and SHA-256} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.4">RFC 7518, Section 3.4</a>.  This algorithm
+         * requires a 256-bit key.
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm ES256 = Jwts.get(REGISTRY, "ES256");
+
+        /**
+         * {@code ECDSA using P-384 and SHA-384} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.4">RFC 7518, Section 3.4</a>.  This algorithm
+         * requires a 384-bit key.
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm ES384 = Jwts.get(REGISTRY, "ES384");
+
+        /**
+         * {@code ECDSA using P-521 and SHA-512} signature algorithm as defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc7518.html#section-3.4">RFC 7518, Section 3.4</a>.  This algorithm
+         * requires a 521-bit key.
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm ES512 = Jwts.get(REGISTRY, "ES512");
+
+        /**
+         * {@code EdDSA} signature algorithm defined by
+         * <a href="https://www.rfc-editor.org/rfc/rfc8037#section-3.1">RFC 8037, Section 3.1</a> that requires
+         * either {@code Ed25519} or {@code Ed448} Edwards Elliptic Curve<sup><b>1</b></sup> keys.
+         *
+         * <p><b>KeyPair Generation</b></p>
+         *
+         * <p>This instance's {@link KeyPairBuilderSupplier#keyPair() keyPair()} builder creates {@code Ed448} keys,
+         * and is essentially an alias for
+         * <code>{@link io.jsonwebtoken.security.Jwks.CRV Jwks.CRV}.{@link io.jsonwebtoken.security.Jwks.CRV#Ed448 Ed448}.{@link KeyPairBuilderSupplier#keyPair() keyPair()}</code>.</p>
+         *
+         * <p>If you would like to generate an {@code Ed25519} {@code KeyPair} for use with the {@code EdDSA} algorithm,
+         * you may use the
+         * <code>{@link io.jsonwebtoken.security.Jwks.CRV Jwks.CRV}.{@link io.jsonwebtoken.security.Jwks.CRV#Ed25519 Ed25519}.{@link KeyPairBuilderSupplier#keyPair() keyPair()}</code>
+         * builder instead.</p>
+         *
+         * <p><b><sup>1</sup>This algorithm requires at least JDK 15 or a compatible JCA Provider (like BouncyCastle) in the runtime
+         * classpath.</b></p>
+         */
+        public static final io.jsonwebtoken.security.SignatureAlgorithm EdDSA = Jwts.get(REGISTRY, "EdDSA");
+    }
+
     /**
      * Visitor implementation that ensures the visited JWT is a JSON Web Signature ('JWS') message with a
      * cryptographically authenticated/verified {@code byte[]} array payload, and rejects all others with an