io.jsonwebtoken.Jwts Maven / Gradle / Ivy
/*
* Copyright (C) 2014 jsonwebtoken.io
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.jsonwebtoken;
import io.jsonwebtoken.io.CompressionAlgorithm;
import io.jsonwebtoken.lang.Builder;
import io.jsonwebtoken.lang.Classes;
import io.jsonwebtoken.lang.Registry;
import io.jsonwebtoken.security.AeadAlgorithm;
import io.jsonwebtoken.security.KeyAlgorithm;
import io.jsonwebtoken.security.KeyPairBuilderSupplier;
import io.jsonwebtoken.security.MacAlgorithm;
import io.jsonwebtoken.security.Password;
import io.jsonwebtoken.security.SecretKeyAlgorithm;
import io.jsonwebtoken.security.SecureDigestAlgorithm;
import io.jsonwebtoken.security.SignatureAlgorithm;
import io.jsonwebtoken.security.X509Builder;
import javax.crypto.SecretKey;
import java.security.Key;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.util.Map;
/**
* Factory class useful for creating instances of JWT interfaces. Using this factory class can be a good
* alternative to tightly coupling your code to implementation classes.
*
* Standard Algorithm References
* Standard JSON Web Token algorithms used during JWS or JWE building or parsing are available organized by
* algorithm type. Each organized collection of algorithms is available via a constant to allow
* for easy code-completion in IDEs, showing available algorithm instances. For example, when typing:
*
* Jwts.// press code-completion hotkeys to suggest available algorithm registry fields
* Jwts.{@link SIG SIG}.// press hotkeys to suggest individual Digital Signature or MAC algorithms or utility methods
* Jwts.{@link ENC ENC}.// press hotkeys to suggest individual encryption algorithms or utility methods
* Jwts.{@link KEY KEY}.// press hotkeys to suggest individual key algorithms or utility methods
*
* @since 0.1
*/
public final class Jwts {
// do not change this visibility. Raw type method signature not be publicly exposed:
@SuppressWarnings("unchecked")
private static T get(Registry registry, String id) {
return (T) registry.forKey(id);
}
/**
* Constants for all standard JWA
* Cryptographic Algorithms for Content
* Encryption defined in the JSON
* Web Signature and Encryption Algorithms Registry. Each standard algorithm is available as a
* ({@code public static final}) constant for direct type-safe reference in application code. For example:
*
* Jwts.builder()
* // ... etc ...
* .encryptWith(aKey, Jwts.ENC.A256GCM) // or A128GCM, A192GCM, etc...
* .build();
* They are also available together as a {@link Registry} instance via the {@link #get()} method.
*
* @see #get()
* @since 0.12.0
*/
public static final class ENC {
private static final String IMPL_CLASSNAME = "io.jsonwebtoken.impl.security.StandardEncryptionAlgorithms";
private static final Registry REGISTRY = Classes.newInstance(IMPL_CLASSNAME);
/**
* Returns all standard JWA Cryptographic
* Algorithms for Content Encryption defined in the
* JSON Web Signature and Encryption
* Algorithms Registry.
*
* @return all standard JWA content encryption algorithms.
*/
public static Registry get() {
return REGISTRY;
}
// prevent instantiation
private ENC() {
}
/**
* {@code AES_128_CBC_HMAC_SHA_256} authenticated encryption algorithm as defined by
* RFC 7518, Section 5.2.3. This algorithm
* requires a 256-bit (32 byte) key.
*/
public static final AeadAlgorithm A128CBC_HS256 = get().forKey("A128CBC-HS256");
/**
* {@code AES_192_CBC_HMAC_SHA_384} authenticated encryption algorithm, as defined by
* RFC 7518, Section 5.2.4. This algorithm
* requires a 384-bit (48 byte) key.
*/
public static final AeadAlgorithm A192CBC_HS384 = get().forKey("A192CBC-HS384");
/**
* {@code AES_256_CBC_HMAC_SHA_512} authenticated encryption algorithm, as defined by
* RFC 7518, Section 5.2.5. This algorithm
* requires a 512-bit (64 byte) key.
*/
public static final AeadAlgorithm A256CBC_HS512 = get().forKey("A256CBC-HS512");
/**
* "AES GCM using 128-bit key" as defined by
* RFC 7518, Section 5.31. This
* algorithm requires a 128-bit (16 byte) key.
*
* 1 Requires Java 8 or a compatible JCA Provider (like BouncyCastle) in the runtime
* classpath. If on Java 7 or earlier, BouncyCastle will be used automatically if found in the runtime
* classpath.
*/
public static final AeadAlgorithm A128GCM = get().forKey("A128GCM");
/**
* "AES GCM using 192-bit key" as defined by
* RFC 7518, Section 5.31. This
* algorithm requires a 192-bit (24 byte) key.
*
* 1 Requires Java 8 or a compatible JCA Provider (like BouncyCastle) in the runtime
* classpath. If on Java 7 or earlier, BouncyCastle will be used automatically if found in the runtime
* classpath.
*/
public static final AeadAlgorithm A192GCM = get().forKey("A192GCM");
/**
* "AES GCM using 256-bit key" as defined by
* RFC 7518, Section 5.31. This
* algorithm requires a 256-bit (32 byte) key.
*
* 1 Requires Java 8 or a compatible JCA Provider (like BouncyCastle) in the runtime
* classpath. If on Java 7 or earlier, BouncyCastle will be used automatically if found in the runtime
* classpath.
*/
public static final AeadAlgorithm A256GCM = get().forKey("A256GCM");
}
/**
* Constants for all JWA (RFC 7518) standard
* Cryptographic Algorithms for Digital Signatures and MACs defined in the
* JSON Web Signature and Encryption Algorithms
* Registry. Each standard algorithm is available as a ({@code public static final}) constant for
* direct type-safe reference in application code. For example:
*
* Jwts.builder()
* // ... etc ...
* .signWith(aKey, Jwts.SIG.HS512) // or RS512, PS256, EdDSA, etc...
* .build();
* They are also available together as a {@link Registry} instance via the {@link #get()} method.
*
* @see #get()
* @since 0.12.0
*/
public static final class SIG {
private static final String IMPL_CLASSNAME = "io.jsonwebtoken.impl.security.StandardSecureDigestAlgorithms";
private static final Registry> REGISTRY = Classes.newInstance(IMPL_CLASSNAME);
//prevent instantiation
private SIG() {
}
/**
* Returns all standard JWA Cryptographic
* Algorithms for Digital Signatures and MACs defined in the
* JSON Web Signature and Encryption
* Algorithms Registry.
*
* @return all standard JWA digital signature and MAC algorithms.
*/
public static Registry> get() {
return REGISTRY;
}
/**
* The "none" signature algorithm as defined by
* RFC 7518, Section 3.6. 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 NONE = Jwts.get(REGISTRY, "none");
/**
* {@code HMAC using SHA-256} message authentication algorithm as defined by
* RFC 7518, Section 3.2. 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
* RFC 7518, Section 3.2. 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
* RFC 7518, Section 3.2. 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
* RFC 7518, Section 3.3. This algorithm
* requires a 2048-bit key.
*/
public static final SignatureAlgorithm RS256 = Jwts.get(REGISTRY, "RS256");
/**
* {@code RSASSA-PKCS1-v1_5 using SHA-384} signature algorithm as defined by
* RFC 7518, Section 3.3. This algorithm
* requires a 2048-bit key, but the JJWT team recommends a 3072-bit key.
*/
public static final SignatureAlgorithm RS384 = Jwts.get(REGISTRY, "RS384");
/**
* {@code RSASSA-PKCS1-v1_5 using SHA-512} signature algorithm as defined by
* RFC 7518, Section 3.3. This algorithm
* requires a 2048-bit key, but the JJWT team recommends a 4096-bit key.
*/
public static final SignatureAlgorithm RS512 = Jwts.get(REGISTRY, "RS512");
/**
* {@code RSASSA-PSS using SHA-256 and MGF1 with SHA-256} signature algorithm as defined by
* RFC 7518, Section 3.51.
* This algorithm requires a 2048-bit key.
*
* 1 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.
*/
public static final SignatureAlgorithm PS256 = Jwts.get(REGISTRY, "PS256");
/**
* {@code RSASSA-PSS using SHA-384 and MGF1 with SHA-384} signature algorithm as defined by
* RFC 7518, Section 3.51.
* This algorithm requires a 2048-bit key, but the JJWT team recommends a 3072-bit key.
*
* 1 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.
*/
public static final SignatureAlgorithm PS384 = Jwts.get(REGISTRY, "PS384");
/**
* {@code RSASSA-PSS using SHA-512 and MGF1 with SHA-512} signature algorithm as defined by
* RFC 7518, Section 3.51.
* This algorithm requires a 2048-bit key, but the JJWT team recommends a 4096-bit key.
*
* 1 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.
*/
public static final SignatureAlgorithm PS512 = Jwts.get(REGISTRY, "PS512");
/**
* {@code ECDSA using P-256 and SHA-256} signature algorithm as defined by
* RFC 7518, Section 3.4. This algorithm
* requires a 256-bit key.
*/
public static final SignatureAlgorithm ES256 = Jwts.get(REGISTRY, "ES256");
/**
* {@code ECDSA using P-384 and SHA-384} signature algorithm as defined by
* RFC 7518, Section 3.4. This algorithm
* requires a 384-bit key.
*/
public static final SignatureAlgorithm ES384 = Jwts.get(REGISTRY, "ES384");
/**
* {@code ECDSA using P-521 and SHA-512} signature algorithm as defined by
* RFC 7518, Section 3.4. This algorithm
* requires a 521-bit key.
*/
public static final SignatureAlgorithm ES512 = Jwts.get(REGISTRY, "ES512");
/**
* {@code EdDSA} signature algorithm defined by
* RFC 8037, Section 3.1 that requires
* either {@code Ed25519} or {@code Ed448} Edwards Elliptic Curve1 keys.
*
* KeyPair Generation
*
* This instance's {@link KeyPairBuilderSupplier#keyPair() keyPair()} builder creates {@code Ed448} keys,
* and is essentially an alias for
* {@link io.jsonwebtoken.security.Jwks.CRV Jwks.CRV}.{@link io.jsonwebtoken.security.Jwks.CRV#Ed448 Ed448}.{@link KeyPairBuilderSupplier#keyPair() keyPair()}.
*
* If you would like to generate an {@code Ed25519} {@code KeyPair} for use with the {@code EdDSA} algorithm,
* you may use the
* {@link io.jsonwebtoken.security.Jwks.CRV Jwks.CRV}.{@link io.jsonwebtoken.security.Jwks.CRV#Ed25519 Ed25519}.{@link KeyPairBuilderSupplier#keyPair() keyPair()}
* builder instead.
*
* 1This algorithm requires at least JDK 15 or a compatible JCA Provider (like BouncyCastle) in the runtime
* classpath.
*/
public static final SignatureAlgorithm EdDSA = Jwts.get(REGISTRY, "EdDSA");
}
/**
* Constants for all standard JWA (RFC 7518)
* Cryptographic Algorithms for Key Management. Each standard algorithm is available as a
* ({@code public static final}) constant for direct type-safe reference in application code. For example:
*
* Jwts.builder()
* // ... etc ...
* .encryptWith(aKey, Jwts.KEY.ECDH_ES_A256KW, Jwts.ENC.A256GCM)
* .build();
* They are also available together as a {@link Registry} instance via the {@link #get()} method.
*
* @see #get()
* @since 0.12.0
*/
public static final class KEY {
private static final String IMPL_CLASSNAME = "io.jsonwebtoken.impl.security.StandardKeyAlgorithms";
private static final Registry> REGISTRY = Classes.newInstance(IMPL_CLASSNAME);
/**
* Returns all standard JWA standard Cryptographic
* Algorithms for Key Management..
*
* @return all standard JWA Key Management algorithms.
*/
public static Registry> get() {
return REGISTRY;
}
/**
* Key algorithm reflecting direct use of a shared symmetric key as the JWE AEAD encryption key, as defined
* by RFC 7518 (JWA), Section 4.5. This
* algorithm does not produce encrypted key ciphertext.
*/
public static final KeyAlgorithm DIRECT = Jwts.get(REGISTRY, "dir");
/**
* AES Key Wrap algorithm with default initial value using a 128-bit key, as defined by
* RFC 7518 (JWA), Section 4.4.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with a 128-bit shared symmetric key using the
* AES Key Wrap algorithm, producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the 128-bit shared symmetric key,
* using the AES Key Unwrap algorithm, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final SecretKeyAlgorithm A128KW = Jwts.get(REGISTRY, "A128KW");
/**
* AES Key Wrap algorithm with default initial value using a 192-bit key, as defined by
* RFC 7518 (JWA), Section 4.4.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with a 192-bit shared symmetric key using the
* AES Key Wrap algorithm, producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the 192-bit shared symmetric key,
* using the AES Key Unwrap algorithm, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final SecretKeyAlgorithm A192KW = Jwts.get(REGISTRY, "A192KW");
/**
* AES Key Wrap algorithm with default initial value using a 256-bit key, as defined by
* RFC 7518 (JWA), Section 4.4.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with a 256-bit shared symmetric key using the
* AES Key Wrap algorithm, producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the 256-bit shared symmetric key,
* using the AES Key Unwrap algorithm, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final SecretKeyAlgorithm A256KW = Jwts.get(REGISTRY, "A256KW");
/**
* Key wrap algorithm with AES GCM using a 128-bit key, as defined by
* RFC 7518 (JWA), Section 4.7.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Generates a new secure-random 96-bit Initialization Vector to use during key wrap/encryption.
* - Encrypts this newly-generated {@code SecretKey} with a 128-bit shared symmetric key using the
* AES GCM Key Wrap algorithm with the generated Initialization Vector, producing encrypted key ciphertext
* and GCM authentication tag.
* - Sets the generated initialization vector as the required
* "iv"
* (Initialization Vector) Header Parameter
* - Sets the resulting GCM authentication tag as the required
* "tag"
* (Authentication Tag) Header Parameter
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Obtains the required initialization vector from the
* "iv"
* (Initialization Vector) Header Parameter
* - Obtains the required GCM authentication tag from the
* "tag"
* (Authentication Tag) Header Parameter
* - Decrypts the encrypted key ciphertext with the 128-bit shared symmetric key, the initialization vector
* and GCM authentication tag using the AES GCM Key Unwrap algorithm, producing the decryption key
* plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final SecretKeyAlgorithm A128GCMKW = Jwts.get(REGISTRY, "A128GCMKW");
/**
* Key wrap algorithm with AES GCM using a 192-bit key, as defined by
* RFC 7518 (JWA), Section 4.7.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Generates a new secure-random 96-bit Initialization Vector to use during key wrap/encryption.
* - Encrypts this newly-generated {@code SecretKey} with a 192-bit shared symmetric key using the
* AES GCM Key Wrap algorithm with the generated Initialization Vector, producing encrypted key ciphertext
* and GCM authentication tag.
* - Sets the generated initialization vector as the required
* "iv"
* (Initialization Vector) Header Parameter
* - Sets the resulting GCM authentication tag as the required
* "tag"
* (Authentication Tag) Header Parameter
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Obtains the required initialization vector from the
* "iv"
* (Initialization Vector) Header Parameter
* - Obtains the required GCM authentication tag from the
* "tag"
* (Authentication Tag) Header Parameter
* - Decrypts the encrypted key ciphertext with the 192-bit shared symmetric key, the initialization vector
* and GCM authentication tag using the AES GCM Key Unwrap algorithm, producing the decryption key \
* plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final SecretKeyAlgorithm A192GCMKW = Jwts.get(REGISTRY, "A192GCMKW");
/**
* Key wrap algorithm with AES GCM using a 256-bit key, as defined by
* RFC 7518 (JWA), Section 4.7.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Generates a new secure-random 96-bit Initialization Vector to use during key wrap/encryption.
* - Encrypts this newly-generated {@code SecretKey} with a 256-bit shared symmetric key using the
* AES GCM Key Wrap algorithm with the generated Initialization Vector, producing encrypted key ciphertext
* and GCM authentication tag.
* - Sets the generated initialization vector as the required
* "iv"
* (Initialization Vector) Header Parameter
* - Sets the resulting GCM authentication tag as the required
* "tag"
* (Authentication Tag) Header Parameter
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Obtains the required initialization vector from the
* "iv"
* (Initialization Vector) Header Parameter
* - Obtains the required GCM authentication tag from the
* "tag"
* (Authentication Tag) Header Parameter
* - Decrypts the encrypted key ciphertext with the 256-bit shared symmetric key, the initialization vector
* and GCM authentication tag using the AES GCM Key Unwrap algorithm, producing the decryption key \
* plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final SecretKeyAlgorithm A256GCMKW = Jwts.get(REGISTRY, "A256GCMKW");
/**
* Key encryption algorithm using PBES2 with HMAC SHA-256 and "A128KW" wrapping
* as defined by
* RFC 7518 (JWA), Section 4.8.
*
* During JWE creation, this algorithm:
*
* - Determines the number of PBDKF2 iterations via the JWE header's
* {@link JweHeader#getPbes2Count() pbes2Count} value. If that value is not set, a suitable number of
* iterations will be chosen based on
* OWASP
* PBKDF2 recommendations and then that value is set as the JWE header {@code pbes2Count} value.
* - Generates a new secure-random salt input and sets it as the JWE header
* {@link JweHeader#getPbes2Salt() pbes2Salt} value.
* - Derives a 128-bit Key Encryption Key with the PBES2-HS256 password-based key derivation algorithm,
* using the provided password, iteration count, and input salt as arguments.
* - Generates a new secure-random Content Encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated Content Encryption {@code SecretKey} with the {@code A128KW} key wrap
* algorithm using the 128-bit derived password-based Key Encryption Key from step {@code #3},
* producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* Content Encryption {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated
* {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the required PBKDF2 input salt from the
* "p2s"
* (PBES2 Salt Input) Header Parameter
* - Obtains the required PBKDF2 iteration count from the
* "p2c"
* (PBES2 Count) Header Parameter
* - Derives the 128-bit Key Encryption Key with the PBES2-HS256 password-based key derivation algorithm,
* using the provided password, obtained salt input, and obtained iteration count as arguments.
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with with the {@code A128KW} key unwrap
* algorithm using the 128-bit derived password-based Key Encryption Key from step {@code #3},
* producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm PBES2_HS256_A128KW = Jwts.get(REGISTRY, "PBES2-HS256+A128KW");
/**
* Key encryption algorithm using PBES2 with HMAC SHA-384 and "A192KW" wrapping
* as defined by
* RFC 7518 (JWA), Section 4.8.
*
* During JWE creation, this algorithm:
*
* - Determines the number of PBDKF2 iterations via the JWE header's
* {@link JweHeader#getPbes2Count() pbes2Count} value. If that value is not set, a suitable number of
* iterations will be chosen based on
* OWASP
* PBKDF2 recommendations and then that value is set as the JWE header {@code pbes2Count} value.
* - Generates a new secure-random salt input and sets it as the JWE header
* {@link JweHeader#getPbes2Salt() pbes2Salt} value.
* - Derives a 192-bit Key Encryption Key with the PBES2-HS384 password-based key derivation algorithm,
* using the provided password, iteration count, and input salt as arguments.
* - Generates a new secure-random Content Encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated Content Encryption {@code SecretKey} with the {@code A192KW} key wrap
* algorithm using the 192-bit derived password-based Key Encryption Key from step {@code #3},
* producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* Content Encryption {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated
* {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the required PBKDF2 input salt from the
* "p2s"
* (PBES2 Salt Input) Header Parameter
* - Obtains the required PBKDF2 iteration count from the
* "p2c"
* (PBES2 Count) Header Parameter
* - Derives the 192-bit Key Encryption Key with the PBES2-HS384 password-based key derivation algorithm,
* using the provided password, obtained salt input, and obtained iteration count as arguments.
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with with the {@code A192KW} key unwrap
* algorithm using the 192-bit derived password-based Key Encryption Key from step {@code #3},
* producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm PBES2_HS384_A192KW = Jwts.get(REGISTRY, "PBES2-HS384+A192KW");
/**
* Key encryption algorithm using PBES2 with HMAC SHA-512 and "A256KW" wrapping
* as defined by
* RFC 7518 (JWA), Section 4.8.
*
* During JWE creation, this algorithm:
*
* - Determines the number of PBDKF2 iterations via the JWE header's
* {@link JweHeader#getPbes2Count() pbes2Count} value. If that value is not set, a suitable number of
* iterations will be chosen based on
* OWASP
* PBKDF2 recommendations and then that value is set as the JWE header {@code pbes2Count} value.
* - Generates a new secure-random salt input and sets it as the JWE header
* {@link JweHeader#getPbes2Salt() pbes2Salt} value.
* - Derives a 256-bit Key Encryption Key with the PBES2-HS512 password-based key derivation algorithm,
* using the provided password, iteration count, and input salt as arguments.
* - Generates a new secure-random Content Encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated Content Encryption {@code SecretKey} with the {@code A256KW} key wrap
* algorithm using the 256-bit derived password-based Key Encryption Key from step {@code #3},
* producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* Content Encryption {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated
* {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the required PBKDF2 input salt from the
* "p2s"
* (PBES2 Salt Input) Header Parameter
* - Obtains the required PBKDF2 iteration count from the
* "p2c"
* (PBES2 Count) Header Parameter
* - Derives the 256-bit Key Encryption Key with the PBES2-HS512 password-based key derivation algorithm,
* using the provided password, obtained salt input, and obtained iteration count as arguments.
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with with the {@code A256KW} key unwrap
* algorithm using the 256-bit derived password-based Key Encryption Key from step {@code #3},
* producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm PBES2_HS512_A256KW = Jwts.get(REGISTRY, "PBES2-HS512+A256KW");
/**
* Key Encryption with {@code RSAES-PKCS1-v1_5}, as defined by
* RFC 7518 (JWA), Section 4.2.
* This algorithm requires a key size of 2048 bits or larger.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with the RSA key wrap algorithm, using the JWE
* recipient's RSA Public Key, producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Receives the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the RSA key unwrap algorithm, using the JWE recipient's
* RSA Private Key, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm RSA1_5 = Jwts.get(REGISTRY, "RSA1_5");
/**
* Key Encryption with {@code RSAES OAEP using default parameters}, as defined by
* RFC 7518 (JWA), Section 4.3.
* This algorithm requires a key size of 2048 bits or larger.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with the RSA OAEP with SHA-1 and MGF1 key wrap algorithm,
* using the JWE recipient's RSA Public Key, producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Receives the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the RSA OAEP with SHA-1 and MGF1 key unwrap algorithm,
* using the JWE recipient's RSA Private Key, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm RSA_OAEP = Jwts.get(REGISTRY, "RSA-OAEP");
/**
* Key Encryption with {@code RSAES OAEP using SHA-256 and MGF1 with SHA-256}, as defined by
* RFC 7518 (JWA), Section 4.3.
* This algorithm requires a key size of 2048 bits or larger.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with the RSA OAEP with SHA-256 and MGF1 key wrap
* algorithm, using the JWE recipient's RSA Public Key, producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Receives the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the RSA OAEP with SHA-256 and MGF1 key unwrap algorithm,
* using the JWE recipient's RSA Private Key, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm RSA_OAEP_256 = Jwts.get(REGISTRY, "RSA-OAEP-256");
/**
* Key Agreement with {@code ECDH-ES using Concat KDF} as defined by
* RFC 7518 (JWA), Section 4.6.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random Elliptic Curve public/private key pair on the same curve as the
* JWE recipient's EC Public Key.
* - Generates a shared secret with the ECDH key agreement algorithm using the generated EC Private Key
* and the JWE recipient's EC Public Key.
* - Derives a symmetric Content
* Encryption {@code SecretKey} with the Concat KDF algorithm using the
* generated shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Sets the generated EC key pair's Public Key as the required
* "epk"
* (Ephemeral Public Key) Header Parameter to be transmitted in the JWE.
* - Returns the derived symmetric {@code SecretKey} for JJWT to use to encrypt the entire JWE with the
* associated {@link AeadAlgorithm}. Encrypted key ciphertext is not produced with this algorithm, so
* the resulting JWE will not contain any embedded key ciphertext.
*
* For JWE decryption, this algorithm:
*
* - Obtains the required ephemeral Elliptic Curve Public Key from the
* "epk"
* (Ephemeral Public Key) Header Parameter.
* - Validates that the ephemeral Public Key is on the same curve as the recipient's EC Private Key.
* - Obtains the shared secret with the ECDH key agreement algorithm using the obtained EC Public Key
* and the JWE recipient's EC Private Key.
* - Derives the symmetric Content
* Encryption {@code SecretKey} with the Concat KDF algorithm using the
* obtained shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Returns the derived symmetric {@code SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm ECDH_ES = Jwts.get(REGISTRY, "ECDH-ES");
/**
* Key Agreement with Key Wrapping via
* ECDH-ES using Concat KDF and CEK wrapped with "A128KW" as defined by
* RFC 7518 (JWA), Section 4.6.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random Elliptic Curve public/private key pair on the same curve as the
* JWE recipient's EC Public Key.
* - Generates a shared secret with the ECDH key agreement algorithm using the generated EC Private Key
* and the JWE recipient's EC Public Key.
* - Derives a 128-bit symmetric Key
* Encryption {@code SecretKey} with the Concat KDF algorithm using the
* generated shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Sets the generated EC key pair's Public Key as the required
* "epk"
* (Ephemeral Public Key) Header Parameter to be transmitted in the JWE.
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with the {@code A128KW} key wrap
* algorithm using the derived symmetric Key Encryption Key from step {@code #3}, producing encrypted key ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the required ephemeral Elliptic Curve Public Key from the
* "epk"
* (Ephemeral Public Key) Header Parameter.
* - Validates that the ephemeral Public Key is on the same curve as the recipient's EC Private Key.
* - Obtains the shared secret with the ECDH key agreement algorithm using the obtained EC Public Key
* and the JWE recipient's EC Private Key.
* - Derives the symmetric Key
* Encryption {@code SecretKey} with the Concat KDF algorithm using the
* obtained shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the AES Key Unwrap algorithm using the
* 128-bit derived symmetric key from step {@code #4}, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm ECDH_ES_A128KW = Jwts.get(REGISTRY, "ECDH-ES+A128KW");
/**
* Key Agreement with Key Wrapping via
* ECDH-ES using Concat KDF and CEK wrapped with "A192KW" as defined by
* RFC 7518 (JWA), Section 4.6.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random Elliptic Curve public/private key pair on the same curve as the
* JWE recipient's EC Public Key.
* - Generates a shared secret with the ECDH key agreement algorithm using the generated EC Private Key
* and the JWE recipient's EC Public Key.
* - Derives a 192-bit symmetric Key
* Encryption {@code SecretKey} with the Concat KDF algorithm using the
* generated shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Sets the generated EC key pair's Public Key as the required
* "epk"
* (Ephemeral Public Key) Header Parameter to be transmitted in the JWE.
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with the {@code A192KW} key wrap
* algorithm using the derived symmetric Key Encryption Key from step {@code #3}, producing encrypted key
* ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the required ephemeral Elliptic Curve Public Key from the
* "epk"
* (Ephemeral Public Key) Header Parameter.
* - Validates that the ephemeral Public Key is on the same curve as the recipient's EC Private Key.
* - Obtains the shared secret with the ECDH key agreement algorithm using the obtained EC Public Key
* and the JWE recipient's EC Private Key.
* - Derives the 192-bit symmetric
* Key Encryption {@code SecretKey} with the Concat KDF algorithm using the
* obtained shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the AES Key Unwrap algorithm using the
* 192-bit derived symmetric key from step {@code #4}, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm ECDH_ES_A192KW = Jwts.get(REGISTRY, "ECDH-ES+A192KW");
/**
* Key Agreement with Key Wrapping via
* ECDH-ES using Concat KDF and CEK wrapped with "A256KW" as defined by
* RFC 7518 (JWA), Section 4.6.
*
* During JWE creation, this algorithm:
*
* - Generates a new secure-random Elliptic Curve public/private key pair on the same curve as the
* JWE recipient's EC Public Key.
* - Generates a shared secret with the ECDH key agreement algorithm using the generated EC Private Key
* and the JWE recipient's EC Public Key.
* - Derives a 256-bit symmetric Key
* Encryption {@code SecretKey} with the Concat KDF algorithm using the
* generated shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Sets the generated EC key pair's Public Key as the required
* "epk"
* (Ephemeral Public Key) Header Parameter to be transmitted in the JWE.
* - Generates a new secure-random content encryption {@link SecretKey} suitable for use with a
* specified {@link AeadAlgorithm} (using {@link AeadAlgorithm#key()}).
* - Encrypts this newly-generated {@code SecretKey} with the {@code A256KW} key wrap
* algorithm using the derived symmetric Key Encryption Key from step {@code #3}, producing encrypted key
* ciphertext.
* - Returns the encrypted key ciphertext for inclusion in the final JWE as well as the newly-generated
* {@code SecretKey} for JJWT to use to encrypt the entire JWE with associated {@link AeadAlgorithm}.
*
* For JWE decryption, this algorithm:
*
* - Obtains the required ephemeral Elliptic Curve Public Key from the
* "epk"
* (Ephemeral Public Key) Header Parameter.
* - Validates that the ephemeral Public Key is on the same curve as the recipient's EC Private Key.
* - Obtains the shared secret with the ECDH key agreement algorithm using the obtained EC Public Key
* and the JWE recipient's EC Private Key.
* - Derives the 256-bit symmetric
* Key Encryption {@code SecretKey} with the Concat KDF algorithm using the
* obtained shared secret and any available
* {@link JweHeader#getAgreementPartyUInfo() PartyUInfo} and
* {@link JweHeader#getAgreementPartyVInfo() PartyVInfo}.
* - Obtains the encrypted key ciphertext embedded in the received JWE.
* - Decrypts the encrypted key ciphertext with the AES Key Unwrap algorithm using the
* 256-bit derived symmetric key from step {@code #4}, producing the decryption key plaintext.
* - Returns the decryption key plaintext as a {@link SecretKey} for JJWT to use to decrypt the entire
* JWE using the JWE's identified "enc" {@link AeadAlgorithm}.
*
*/
public static final KeyAlgorithm ECDH_ES_A256KW = Jwts.get(REGISTRY, "ECDH-ES+A256KW");
//prevent instantiation
private KEY() {
}
}
/**
* Constants for JWA (RFC 7518) compression algorithms referenced in the {@code zip} header defined in the
* JSON Web Encryption Compression Algorithms
* Registry. Each algorithm is available as a ({@code public static final}) constant for
* direct type-safe reference in application code. For example:
*
* Jwts.builder()
* // ... etc ...
* .compressWith(Jwts.ZIP.DEF)
* .build();
* They are also available together as a {@link Registry} instance via the {@link #get()} method.
*
* @see #get()
* @since 0.12.0
*/
public static final class ZIP {
private static final String IMPL_CLASSNAME = "io.jsonwebtoken.impl.io.StandardCompressionAlgorithms";
private static final Registry REGISTRY = Classes.newInstance(IMPL_CLASSNAME);
/**
* Returns various useful
* Compression Algorithms.
*
* @return various standard and non-standard useful compression algorithms.
*/
public static Registry get() {
return REGISTRY;
}
/**
* The JWE-standard DEFLATE
* compression algorithm with a {@code zip} header value of {@code "DEF"}.
*
* @see JWE RFC 7516, Section 4.1.3
*/
public static final CompressionAlgorithm DEF = get().forKey("DEF");
/**
* A commonly used, but NOT JWA-STANDARD
* gzip compression algorithm with a {@code zip} header value
* of {@code "GZIP"}.
*
* Compatibility Warning
*
* This is not a standard JWE compression algorithm. Be sure to use this only when you are confident
* that all parties accessing the token support the "GZIP" identifier and associated algorithm.
*
* If you're concerned about compatibility, {@link #DEF DEF} is the only JWA standards-compliant algorithm.
*
* @see #DEF
*/
public static final CompressionAlgorithm GZIP = get().forKey("GZIP");
//prevent instantiation
private ZIP() {
}
}
/**
* A {@link Builder} that dynamically determines the type of {@link Header} to create based on builder state.
*
* @since 0.12.0
*/
public interface HeaderBuilder extends JweHeaderMutator, X509Builder, Builder {
}
/**
* Returns a new {@link HeaderBuilder} that can build any type of {@link Header} instance depending on
* which builder properties are set.
*
* @return a new {@link HeaderBuilder} that can build any type of {@link Header} instance depending on
* which builder properties are set.
* @since 0.12.0
*/
public static HeaderBuilder header() {
return Classes.newInstance("io.jsonwebtoken.impl.DefaultJwtHeaderBuilder");
}
/**
* Returns a new {@link Claims} builder instance to be used to populate JWT claims, which in aggregate will be
* the JWT payload.
*
* @return a new {@link Claims} builder instance to be used to populate JWT claims, which in aggregate will be
* the JWT payload.
*/
public static ClaimsBuilder claims() {
return Classes.newInstance("io.jsonwebtoken.impl.DefaultClaimsBuilder");
}
/**
* Deprecated since 0.12.0 in favor of
* {@code Jwts.}{@link #claims()}{@code .add(map).build()}.
* This method will be removed before 1.0.
*
* Returns a new {@link Claims} instance populated with the specified name/value pairs.
*
* @param claims the name/value pairs to populate the new Claims instance.
* @return a new {@link Claims} instance populated with the specified name/value pairs.
* @deprecated since 0.12.0 in favor of {@code Jwts.}{@link #claims()}{@code .putAll(map).build()}.
* This method will be removed before 1.0.
*/
@Deprecated
public static Claims claims(Map claims) {
return claims().add(claims).build();
}
/**
* Returns a new {@link JwtBuilder} instance that can be configured and then used to create JWT compact serialized
* strings.
*
* @return a new {@link JwtBuilder} instance that can be configured and then used to create JWT compact serialized
* strings.
*/
public static JwtBuilder builder() {
return Classes.newInstance("io.jsonwebtoken.impl.DefaultJwtBuilder");
}
/**
* Returns a new {@link JwtParserBuilder} instance that can be configured to create an immutable/thread-safe {@link JwtParser}.
*
* @return a new {@link JwtParser} instance that can be configured create an immutable/thread-safe {@link JwtParser}.
*/
public static JwtParserBuilder parser() {
return Classes.newInstance("io.jsonwebtoken.impl.DefaultJwtParserBuilder");
}
/**
* Private constructor, prevent instantiation.
*/
private Jwts() {
}
}