tessl/maven-com-auth0--java-jwt

A comprehensive Java implementation of JSON Web Token (JWT) with creation, signing, and verification capabilities for server-side JVM applications.

—

Pending

Overview

Eval results

Files

Cryptographic Algorithms

Name: tessl/maven-com-auth0--java-jwt
Author: tessl

Comprehensive cryptographic algorithm support for JWT signing and verification, including HMAC, RSA, and ECDSA algorithms with flexible key management options.

Capabilities

HMAC Algorithms

Hash-based Message Authentication Code algorithms using SHA-256, SHA-384, and SHA-512 hash functions.

/**
 * Creates a new Algorithm instance using HmacSHA256. Tokens specify this as "HS256".
 * @param secret the secret bytes to use in the verify or signing instance
 * @return a valid HMAC256 Algorithm
 * @throws IllegalArgumentException if the provided Secret is null
 */
public static Algorithm HMAC256(byte[] secret) throws IllegalArgumentException;

/**
 * Creates a new Algorithm instance using HmacSHA256. Tokens specify this as "HS256".
 * @param secret the secret to use in the verify or signing instance
 * @return a valid HMAC256 Algorithm
 * @throws IllegalArgumentException if the provided Secret is null
 */
public static Algorithm HMAC256(String secret) throws IllegalArgumentException;

/**
 * Creates a new Algorithm instance using HmacSHA384. Tokens specify this as "HS384".
 * @param secret the secret bytes to use in the verify or signing instance
 * @return a valid HMAC384 Algorithm
 * @throws IllegalArgumentException if the provided Secret is null
 */
public static Algorithm HMAC384(byte[] secret) throws IllegalArgumentException;

/**
 * Creates a new Algorithm instance using HmacSHA384. Tokens specify this as "HS384".
 * @param secret the secret to use in the verify or signing instance
 * @return a valid HMAC384 Algorithm
 * @throws IllegalArgumentException if the provided Secret is null
 */
public static Algorithm HMAC384(String secret) throws IllegalArgumentException;

/**
 * Creates a new Algorithm instance using HmacSHA512. Tokens specify this as "HS512".
 * @param secret the secret bytes to use in the verify or signing instance
 * @return a valid HMAC512 Algorithm
 * @throws IllegalArgumentException if the provided Secret is null
 */
public static Algorithm HMAC512(byte[] secret) throws IllegalArgumentException;

/**
 * Creates a new Algorithm instance using HmacSHA512. Tokens specify this as "HS512".
 * @param secret the secret to use in the verify or signing instance
 * @return a valid HMAC512 Algorithm
 * @throws IllegalArgumentException if the provided Secret is null
 */
public static Algorithm HMAC512(String secret) throws IllegalArgumentException;

Usage Examples:

import com.auth0.jwt.algorithms.Algorithm;

// HMAC256 with String secret
Algorithm hmac256 = Algorithm.HMAC256("my-secret-key");

// HMAC256 with byte array secret (more secure)
byte[] secretBytes = "my-secret-key".getBytes(StandardCharsets.UTF_8);
Algorithm hmac256Bytes = Algorithm.HMAC256(secretBytes);

// HMAC384 algorithm
Algorithm hmac384 = Algorithm.HMAC384("my-longer-secret-key-for-384");

// HMAC512 algorithm (strongest HMAC)
Algorithm hmac512 = Algorithm.HMAC512("my-even-longer-secret-key-for-512-bit-security");

// Use with JWT creation
String token = JWT.create()
    .withIssuer("auth0")
    .sign(hmac256);

// Use with JWT verification
JWTVerifier verifier = JWT.require(hmac256)
    .withIssuer("auth0")
    .build();

RSA Algorithms

RSA signature algorithms using RSASSA-PKCS1-v1_5 with SHA-256, SHA-384, and SHA-512 hash functions.

/**
 * Creates a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
 * @return a valid RSA256 Algorithm
 * @throws IllegalArgumentException if the provided Key is null
 */
public static Algorithm RSA256(RSAKeyProvider keyProvider);

/**
 * Creates a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".
 * @param publicKey the key to use in the verify instance
 * @param privateKey the key to use in the signing instance
 * @return a valid RSA256 Algorithm
 * @throws IllegalArgumentException if both provided Keys are null
 */
public static Algorithm RSA256(RSAPublicKey publicKey, RSAPrivateKey privateKey);

/**
 * Creates a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".
 * @param key the key to use in the verify or signing instance
 * @return a valid RSA256 Algorithm
 * @throws IllegalArgumentException if the Key Provider is null
 */
public static Algorithm RSA256(RSAKey key);

/**
 * Creates a new Algorithm instance using SHA384withRSA. Tokens specify this as "RS384".
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
 * @return a valid RSA384 Algorithm
 * @throws IllegalArgumentException if the Key Provider is null
 */
public static Algorithm RSA384(RSAKeyProvider keyProvider);

/**
 * Creates a new Algorithm instance using SHA384withRSA. Tokens specify this as "RS384".
 * @param publicKey the key to use in the verify instance
 * @param privateKey the key to use in the signing instance
 * @return a valid RSA384 Algorithm
 * @throws IllegalArgumentException if both provided Keys are null
 */
public static Algorithm RSA384(RSAPublicKey publicKey, RSAPrivateKey privateKey);

/**
 * Creates a new Algorithm instance using SHA384withRSA. Tokens specify this as "RS384".
 * @param key the key to use in the verify or signing instance
 * @return a valid RSA384 Algorithm
 * @throws IllegalArgumentException if the provided Key is null
 */
public static Algorithm RSA384(RSAKey key);

/**
 * Creates a new Algorithm instance using SHA512withRSA. Tokens specify this as "RS512".
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
 * @return a valid RSA512 Algorithm
 * @throws IllegalArgumentException if the Key Provider is null
 */
public static Algorithm RSA512(RSAKeyProvider keyProvider);

/**
 * Creates a new Algorithm instance using SHA512withRSA. Tokens specify this as "RS512".
 * @param publicKey the key to use in the verify instance
 * @param privateKey the key to use in the signing instance
 * @return a valid RSA512 Algorithm
 * @throws IllegalArgumentException if both provided Keys are null
 */
public static Algorithm RSA512(RSAPublicKey publicKey, RSAPrivateKey privateKey);

/**
 * Creates a new Algorithm instance using SHA512withRSA. Tokens specify this as "RS512".
 * @param key the key to use in the verify or signing instance
 * @return a valid RSA512 Algorithm
 * @throws IllegalArgumentException if the provided Key is null
 */
public static Algorithm RSA512(RSAKey key);

Usage Examples:

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
import java.security.interfaces.RSAKey;

// Generate RSA key pair for demonstration
KeyPairGenerator keyGenerator = KeyPairGenerator.getInstance("RSA");
keyGenerator.initialize(2048);
KeyPair keyPair = keyGenerator.generateKeyPair();
RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();

// RSA256 with public and private keys
Algorithm rsa256 = Algorithm.RSA256(publicKey, privateKey);

// RSA256 with only public key (verification only)
Algorithm rsa256VerifyOnly = Algorithm.RSA256(publicKey, null);

// RSA256 with only private key (signing only)
Algorithm rsa256SignOnly = Algorithm.RSA256(null, privateKey);

// RSA256 with RSAKey interface
RSAKey rsaKey = privateKey; // RSAPrivateKey implements RSAKey
Algorithm rsa256FromKey = Algorithm.RSA256(rsaKey);

// RSA384 and RSA512 follow the same patterns
Algorithm rsa384 = Algorithm.RSA384(publicKey, privateKey);
Algorithm rsa512 = Algorithm.RSA512(publicKey, privateKey);

// Use with JWT signing (requires private key)
String token = JWT.create()
    .withIssuer("auth0")
    .sign(rsa256);

// Use with JWT verification (requires public key)
JWTVerifier verifier = JWT.require(rsa256)
    .withIssuer("auth0")
    .build();

ECDSA Algorithms

Elliptic Curve Digital Signature Algorithm using P-256, P-384, and P-521 curves with SHA-256, SHA-384, and SHA-512 hash functions.

/**
 * Creates a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
 * @return a valid ECDSA256 Algorithm
 * @throws IllegalArgumentException if the Key Provider is null
 */
public static Algorithm ECDSA256(ECDSAKeyProvider keyProvider);

/**
 * Creates a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".
 * @param publicKey the key to use in the verify instance
 * @param privateKey the key to use in the signing instance
 * @return a valid ECDSA256 Algorithm
 * @throws IllegalArgumentException if both provided Keys are null
 */
public static Algorithm ECDSA256(ECPublicKey publicKey, ECPrivateKey privateKey);

/**
 * Creates a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".
 * @param key the key to use in the verify or signing instance
 * @return a valid ECDSA256 Algorithm
 * @throws IllegalArgumentException if the provided Key is null
 */
public static Algorithm ECDSA256(ECKey key);

/**
 * Creates a new Algorithm instance using SHA384withECDSA. Tokens specify this as "ES384".
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
 * @return a valid ECDSA384 Algorithm
 * @throws IllegalArgumentException if the Key Provider is null
 */
public static Algorithm ECDSA384(ECDSAKeyProvider keyProvider);

/**
 * Creates a new Algorithm instance using SHA384withECDSA. Tokens specify this as "ES384".
 * @param publicKey the key to use in the verify instance
 * @param privateKey the key to use in the signing instance
 * @return a valid ECDSA384 Algorithm
 * @throws IllegalArgumentException if both provided Keys are null
 */
public static Algorithm ECDSA384(ECPublicKey publicKey, ECPrivateKey privateKey);

/**
 * Creates a new Algorithm instance using SHA384withECDSA. Tokens specify this as "ES384".
 * @param key the key to use in the verify or signing instance
 * @return a valid ECDSA384 Algorithm
 * @throws IllegalArgumentException if the provided Key is null
 */
public static Algorithm ECDSA384(ECKey key);

/**
 * Creates a new Algorithm instance using SHA512withECDSA. Tokens specify this as "ES512".
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
 * @return a valid ECDSA512 Algorithm
 * @throws IllegalArgumentException if the Key Provider is null
 */
public static Algorithm ECDSA512(ECDSAKeyProvider keyProvider);

/**
 * Creates a new Algorithm instance using SHA512withECDSA. Tokens specify this as "ES512".
 * @param publicKey the key to use in the verify instance
 * @param privateKey the key to use in the signing instance
 * @return a valid ECDSA512 Algorithm
 * @throws IllegalArgumentException if both provided Keys are null
 */
public static Algorithm ECDSA512(ECPublicKey publicKey, ECPrivateKey privateKey);

/**
 * Creates a new Algorithm instance using SHA512withECDSA. Tokens specify this as "ES512".
 * @param key the key to use in the verify or signing instance
 * @return a valid ECDSA512 Algorithm
 * @throws IllegalArgumentException if the provided Key is null
 */
public static Algorithm ECDSA512(ECKey key);

Usage Examples:

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.interfaces.ECPrivateKey;
import java.security.interfaces.ECPublicKey;
import java.security.interfaces.ECKey;
import java.security.spec.ECGenParameterSpec;

// Generate ECDSA key pair for ES256 (P-256 curve)
KeyPairGenerator keyGenerator = KeyPairGenerator.getInstance("EC");
keyGenerator.initialize(new ECGenParameterSpec("secp256r1")); // P-256
KeyPair keyPair = keyGenerator.generateKeyPair();
ECPublicKey publicKey = (ECPublicKey) keyPair.getPublic();
ECPrivateKey privateKey = (ECPrivateKey) keyPair.getPrivate();

// ECDSA256 with public and private keys
Algorithm ecdsa256 = Algorithm.ECDSA256(publicKey, privateKey);

// ECDSA256 with only public key (verification only)
Algorithm ecdsa256VerifyOnly = Algorithm.ECDSA256(publicKey, null);

// ECDSA256 with only private key (signing only)
Algorithm ecdsa256SignOnly = Algorithm.ECDSA256(null, privateKey);

// ECDSA256 with ECKey interface
ECKey ecKey = privateKey; // ECPrivateKey implements ECKey
Algorithm ecdsa256FromKey = Algorithm.ECDSA256(ecKey);

// Generate keys for different curves
// ES384 uses P-384 curve
KeyPairGenerator es384Generator = KeyPairGenerator.getInstance("EC");
es384Generator.initialize(new ECGenParameterSpec("secp384r1")); // P-384
KeyPair es384KeyPair = es384Generator.generateKeyPair();
Algorithm ecdsa384 = Algorithm.ECDSA384(
    (ECPublicKey) es384KeyPair.getPublic(),
    (ECPrivateKey) es384KeyPair.getPrivate()
);

// ES512 uses P-521 curve
KeyPairGenerator es512Generator = KeyPairGenerator.getInstance("EC");
es512Generator.initialize(new ECGenParameterSpec("secp521r1")); // P-521
KeyPair es512KeyPair = es512Generator.generateKeyPair();
Algorithm ecdsa512 = Algorithm.ECDSA512(
    (ECPublicKey) es512KeyPair.getPublic(),
    (ECPrivateKey) es512KeyPair.getPrivate()
);

// Use with JWT signing and verification
String token = JWT.create()
    .withIssuer("auth0")
    .sign(ecdsa256);

JWTVerifier verifier = JWT.require(ecdsa256)
    .withIssuer("auth0")
    .build();

None Algorithm

Algorithm that provides no signature for unverified JWTs.

/**
 * Creates a new Algorithm instance that doesn't use any signature.
 * Tokens specify this as "none".
 * @return a valid None Algorithm
 */
public static Algorithm none();

Usage Examples:

// Create algorithm with no signature
Algorithm noneAlgorithm = Algorithm.none();

// Create unsigned JWT (not recommended for production)
String unsignedToken = JWT.create()
    .withIssuer("auth0")
    .withSubject("user123")
    .sign(noneAlgorithm);

// Verify unsigned JWT
JWTVerifier verifier = JWT.require(noneAlgorithm)
    .withIssuer("auth0")
    .build();

DecodedJWT jwt = verifier.verify(unsignedToken);

Security Warning: The none algorithm should only be used in development or specific scenarios where signature is not required. Never use in production security-critical applications.

Algorithm Instance Methods

Common methods available on all Algorithm instances for key management and signature operations.

/**
 * Getter for the Id of the Key used to verify the signature on the JWT.
 * @return the Key Id that should be used to verify the signature on the JWT or null if not specified
 */
public String getSigningKeyId();

/**
 * Getter for this Algorithm name.
 * @return the Algorithm name (e.g., "HS256", "RS256", "ES256", "none")
 */
public String getName();

/**
 * Verify the given JWT signature.
 * @param jwt the already decoded JWT
 * @throws SignatureVerificationException if the signature is invalid
 * @throws IllegalArgumentException if the JWT is null
 */
public abstract void verify(DecodedJWT jwt) throws SignatureVerificationException;

/**
 * Sign the given content with this algorithm.
 * @param headerBytes the header content to be signed
 * @param payloadBytes the payload content to be signed
 * @return the signature bytes
 * @throws SignatureGenerationException if signature cannot be created
 */
public byte[] sign(byte[] headerBytes, byte[] payloadBytes) throws SignatureGenerationException;

/**
 * Sign the given content with this algorithm.
 * @param contentBytes the content to be signed
 * @return the signature bytes
 * @throws SignatureGenerationException if signature cannot be created
 */
public abstract byte[] sign(byte[] contentBytes) throws SignatureGenerationException;

Usage Examples:

Algorithm algorithm = Algorithm.HMAC256("secret");

// Get algorithm information
String algorithmName = algorithm.getName(); // "HS256"
String keyId = algorithm.getSigningKeyId(); // null for HMAC (no key ID)

System.out.println("Algorithm: " + algorithmName);

// Verify a JWT (typically done internally by JWTVerifier)
try {
    DecodedJWT jwt = JWT.decode(token);
    algorithm.verify(jwt); // Throws SignatureVerificationException if invalid
    System.out.println("Signature is valid");
} catch (SignatureVerificationException e) {
    System.err.println("Invalid signature: " + e.getMessage());
}

// Manual signing (typically done internally by JWT.create().sign())
try {
    byte[] headerBytes = "header".getBytes();
    byte[] payloadBytes = "payload".getBytes();
    byte[] signature = algorithm.sign(headerBytes, payloadBytes);
    System.out.println("Signature created successfully");
} catch (SignatureGenerationException e) {
    System.err.println("Failed to create signature: " + e.getMessage());
}

Algorithm Selection Guide

HMAC Algorithms (Symmetric)

Use Case: Shared secret scenarios, simple applications, microservices with shared keys
Security: Good for internal systems where key distribution is manageable
Performance: Fastest option
Key Management: Simple but requires secure key sharing

RSA Algorithms (Asymmetric)

Use Case: Token issuers different from verifiers, public key infrastructure
Security: Strong, well-established algorithm
Performance: Slower than HMAC, faster verification than signing
Key Management: Public key can be shared openly, private key must remain secure

ECDSA Algorithms (Asymmetric)

Use Case: Similar to RSA but with smaller key sizes and better performance
Security: Equivalent security to RSA with smaller keys
Performance: Better than RSA, especially for signing operations
Key Management: Same as RSA but with more efficient key sizes

None Algorithm

Use Case: Development, testing, or scenarios where signature verification is handled elsewhere
Security: No signature protection
Performance: Fastest (no cryptographic operations)
Key Management: No keys required

Types

/**
 * The Algorithm class represents an algorithm to be used in the Signing or Verification process of a Token.
 * This class and its subclasses are thread-safe.
 */
public abstract class Algorithm {
    /**
     * Get the signing key ID for this algorithm
     * @return signing key ID or null if not applicable
     */
    public String getSigningKeyId();
    
    /**
     * Get the algorithm name
     * @return algorithm name (e.g., "HS256", "RS256", "ES256", "none")
     */
    public String getName();
    
    /**
     * Verify a JWT signature
     * @param jwt decoded JWT to verify
     * @throws SignatureVerificationException if verification fails
     */
    public abstract void verify(DecodedJWT jwt) throws SignatureVerificationException;
    
    /**
     * Sign content with this algorithm
     * @param contentBytes content to sign
     * @return signature bytes
     * @throws SignatureGenerationException if signing fails
     */
    public abstract byte[] sign(byte[] contentBytes) throws SignatureGenerationException;
}

Install with Tessl CLI

npx tessl i tessl/maven-com-auth0--java-jwt

docs

tessl/maven-com-auth0--java-jwt

algorithms.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Cryptographic Algorithms

Capabilities

HMAC Algorithms

RSA Algorithms

ECDSA Algorithms

None Algorithm

Algorithm Instance Methods

Algorithm Selection Guide

HMAC Algorithms (Symmetric)

RSA Algorithms (Asymmetric)

ECDSA Algorithms (Asymmetric)

None Algorithm

Types

algorithms.mddocs/