tessl/maven-io-jsonwebtoken--jjwt-impl

JJWT Implementation module providing concrete implementations of JSON Web Token (JWT) creation, parsing, verification, and cryptographic operations for Java and Android applications.

—

Pending

Overview

Eval results

Files

Security Algorithms

Name: tessl/maven-io-jsonwebtoken--jjwt-impl
Author: tessl

The Security Algorithms functionality in JJWT Implementation provides comprehensive JWA (JSON Web Algorithms) compliant implementations for digital signatures, content encryption, key management, and related cryptographic operations. The implementation includes algorithm registries, key generation utilities, and JCA provider integration.

Algorithm Registries

StandardSecureDigestAlgorithms

Registry for JWS (JSON Web Signature) algorithms providing both MAC and digital signature operations.

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.SecureDigestAlgorithm;
import io.jsonwebtoken.security.MacAlgorithm;
import io.jsonwebtoken.security.SignatureAlgorithm;
import javax.crypto.SecretKey;
import java.security.KeyPair;
import java.security.PrivateKey;
import java.security.PublicKey;

// Access signature algorithm registry
SecureDigestAlgorithm<?, ?> algorithm = Jwts.SIG.get("HS256");

// Get all available signature algorithms
Collection<SecureDigestAlgorithm<?, ?>> allAlgorithms = Jwts.SIG.values();

// Find algorithm by key type
SecretKey hmacKey = Jwts.SIG.HS256.key().build();
SecureDigestAlgorithm<?, ?> foundAlgorithm = Jwts.SIG.get().forKey(hmacKey);

HMAC Algorithms

// HMAC-SHA256 (HS256)
MacAlgorithm hs256 = Jwts.SIG.HS256;
SecretKey hs256Key = hs256.key().build();

// HMAC-SHA384 (HS384)
MacAlgorithm hs384 = Jwts.SIG.HS384;
SecretKey hs384Key = hs384.key().build();

// HMAC-SHA512 (HS512)
MacAlgorithm hs512 = Jwts.SIG.HS512;
SecretKey hs512Key = hs512.key().build();

// Key length requirements
int hs256MinLength = hs256.getKeyBitLength(); // 256 bits minimum
int hs384MinLength = hs384.getKeyBitLength(); // 384 bits minimum
int hs512MinLength = hs512.getKeyBitLength(); // 512 bits minimum

// Generate keys with specific lengths
SecretKey customHs256 = hs256.key()
    .length(hs256MinLength)
    .build();

RSA Signature Algorithms

// RSA with PKCS#1 v1.5 padding
SignatureAlgorithm rs256 = Jwts.SIG.RS256; // RSA-SHA256
SignatureAlgorithm rs384 = Jwts.SIG.RS384; // RSA-SHA384  
SignatureAlgorithm rs512 = Jwts.SIG.RS512; // RSA-SHA512

// Generate RSA key pairs
KeyPair rs256Pair = rs256.keyPair().build();
KeyPair rs384Pair = rs384.keyPair().build();
KeyPair rs512Pair = rs512.keyPair().build();

// RSA-PSS (Probabilistic Signature Scheme)
SignatureAlgorithm ps256 = Jwts.SIG.PS256; // RSA-PSS with SHA-256
SignatureAlgorithm ps384 = Jwts.SIG.PS384; // RSA-PSS with SHA-384
SignatureAlgorithm ps512 = Jwts.SIG.PS512; // RSA-PSS with SHA-512

KeyPair ps256Pair = ps256.keyPair().build();

// Custom key sizes
KeyPair rsa2048 = rs256.keyPair()
    .keySize(2048)
    .build();

KeyPair rsa3072 = rs256.keyPair()
    .keySize(3072)
    .build();

KeyPair rsa4096 = rs256.keyPair()
    .keySize(4096)
    .build();

Elliptic Curve Signature Algorithms

// ECDSA with different curves
SignatureAlgorithm es256 = Jwts.SIG.ES256; // P-256 curve (secp256r1)
SignatureAlgorithm es384 = Jwts.SIG.ES384; // P-384 curve (secp384r1)
SignatureAlgorithm es512 = Jwts.SIG.ES512; // P-521 curve (secp521r1)

// Generate EC key pairs
KeyPair p256Pair = es256.keyPair().build();
KeyPair p384Pair = es384.keyPair().build();
KeyPair p521Pair = es512.keyPair().build();

// EdDSA (Edwards-curve Digital Signature Algorithm)
SignatureAlgorithm eddsa = Jwts.SIG.EdDSA; // Ed25519 and Ed448 support

KeyPair ed25519Pair = eddsa.keyPair().build();

// Curve information
String es256CurveName = "P-256"; // Equivalent curve names
String es384CurveName = "P-384";
String es512CurveName = "P-521";

StandardEncryptionAlgorithms

Registry for JWE (JSON Web Encryption) content encryption algorithms.

import io.jsonwebtoken.security.AeadAlgorithm;

// AES-GCM algorithms
AeadAlgorithm a128gcm = Jwts.ENC.A128GCM; // AES-128-GCM
AeadAlgorithm a192gcm = Jwts.ENC.A192GCM; // AES-192-GCM
AeadAlgorithm a256gcm = Jwts.ENC.A256GCM; // AES-256-GCM

// Generate content encryption keys
SecretKey cek128 = a128gcm.key().build();
SecretKey cek192 = a192gcm.key().build();
SecretKey cek256 = a256gcm.key().build();

// AES-CBC with HMAC algorithms
AeadAlgorithm a128cbcHs256 = Jwts.ENC.A128CBC_HS256; // AES-128-CBC + HMAC-SHA256
AeadAlgorithm a192cbcHs384 = Jwts.ENC.A192CBC_HS384; // AES-192-CBC + HMAC-SHA384
AeadAlgorithm a256cbcHs512 = Jwts.ENC.A256CBC_HS512; // AES-256-CBC + HMAC-SHA512

// Key length requirements
int gcm128KeyLen = a128gcm.getKeyBitLength(); // 128 bits
int gcm256KeyLen = a256gcm.getKeyBitLength(); // 256 bits
int cbc256KeyLen = a256cbcHs512.getKeyBitLength(); // 512 bits (256 AES + 256 HMAC)

StandardKeyAlgorithms

Registry for JWE key management algorithms.

import io.jsonwebtoken.security.KeyAlgorithm;

// RSA key encryption
KeyAlgorithm rsa15 = Jwts.KEY.RSA1_5;      // RSA-PKCS1-v1.5
KeyAlgorithm rsaOaep = Jwts.KEY.RSA_OAEP;   // RSA-OAEP with SHA-1
KeyAlgorithm rsaOaep256 = Jwts.KEY.RSA_OAEP_256; // RSA-OAEP with SHA-256

// Generate RSA key pairs for encryption
KeyPair rsaEncPair = rsa15.keyPair().build();
KeyPair rsaOaepPair = rsaOaep.keyPair().build();

// AES Key Wrap
KeyAlgorithm a128kw = Jwts.KEY.A128KW; // AES-128 Key Wrap
KeyAlgorithm a192kw = Jwts.KEY.A192KW; // AES-192 Key Wrap
KeyAlgorithm a256kw = Jwts.KEY.A256KW; // AES-256 Key Wrap

// Generate key encryption keys
SecretKey kek128 = a128kw.key().build();
SecretKey kek192 = a192kw.key().build();
SecretKey kek256 = a256kw.key().build();

// Direct key agreement
KeyAlgorithm direct = Jwts.KEY.DIRECT; // Direct use of CEK

// ECDH-ES algorithms
KeyAlgorithm ecdhEs = Jwts.KEY.ECDH_ES;          // Direct key agreement
KeyAlgorithm ecdhEs128 = Jwts.KEY.ECDH_ES_A128KW; // ECDH-ES + A128KW
KeyAlgorithm ecdhEs192 = Jwts.KEY.ECDH_ES_A192KW; // ECDH-ES + A192KW
KeyAlgorithm ecdhEs256 = Jwts.KEY.ECDH_ES_A256KW; // ECDH-ES + A256KW

KeyPair ecdhPair = ecdhEs.keyPair().build();

// AES-GCM Key Wrap
KeyAlgorithm a128gcmkw = Jwts.KEY.A128GCMKW; // AES-128-GCMKW
KeyAlgorithm a192gcmkw = Jwts.KEY.A192GCMKW; // AES-192-GCMKW
KeyAlgorithm a256gcmkw = Jwts.KEY.A256GCMKW; // AES-256-GCMKW

// PBES2 algorithms (Password-Based)
KeyAlgorithm pbes2Hs256A128kw = Jwts.KEY.PBES2_HS256_A128KW;
KeyAlgorithm pbes2Hs384A192kw = Jwts.KEY.PBES2_HS384_A192KW;
KeyAlgorithm pbes2Hs512A256kw = Jwts.KEY.PBES2_HS512_A256KW;

Key Generation and Management

Secret Key Generation

import io.jsonwebtoken.impl.security.DefaultSecretKeyBuilder;
import io.jsonwebtoken.impl.security.RandomSecretKeyBuilder;
import java.security.SecureRandom;
import java.security.Provider;

// Generate HMAC keys
SecretKey hmacKey256 = Jwts.SIG.HS256.key().build();
SecretKey hmacKey384 = Jwts.SIG.HS384.key().build();
SecretKey hmacKey512 = Jwts.SIG.HS512.key().build();

// Custom key generation with specific parameters
SecretKey customKey = Jwts.SIG.HS256.key()
    .length(256)
    .algorithm("HmacSHA256")
    .provider(myProvider)
    .random(mySecureRandom)
    .build();

// AES keys for encryption
SecretKey aes128 = Jwts.ENC.A128GCM.key().build();
SecretKey aes256 = Jwts.ENC.A256GCM.key().build();

// Key encryption keys
SecretKey kek = Jwts.KEY.A256KW.key().build();

Asymmetric Key Generation

import io.jsonwebtoken.impl.security.DefaultKeyPairBuilder;

// RSA key generation with different sizes
KeyPair rsa2048 = Jwts.SIG.RS256.keyPair()
    .keySize(2048)
    .build();

KeyPair rsa3072 = Jwts.SIG.RS256.keyPair()
    .keySize(3072)
    .build();

KeyPair rsa4096 = Jwts.SIG.RS256.keyPair()
    .keySize(4096)
    .build();

// EC key generation for different curves
KeyPair ecP256 = Jwts.SIG.ES256.keyPair().build(); // P-256
KeyPair ecP384 = Jwts.SIG.ES384.keyPair().build(); // P-384
KeyPair ecP521 = Jwts.SIG.ES512.keyPair().build(); // P-521

// EdDSA key generation
KeyPair ed25519 = Jwts.SIG.EdDSA.keyPair().build();

// Custom provider and random source
KeyPair customRsa = Jwts.SIG.RS256.keyPair()
    .keySize(2048)
    .provider(customProvider)
    .random(customSecureRandom)
    .build();

Key Wrapping and Providers

import io.jsonwebtoken.impl.security.ProvidedSecretKeyBuilder;
import io.jsonwebtoken.impl.security.ProvidedPrivateKeyBuilder;

// Wrap existing keys
SecretKey existingSecret = getExistingSecretKey();
SecretKey wrappedSecret = new ProvidedSecretKeyBuilder(existingSecret).build();

PrivateKey existingPrivate = getExistingPrivateKey();
PrivateKey wrappedPrivate = new ProvidedPrivateKeyBuilder(existingPrivate).build();

// Key validation
boolean isValidForAlgorithm = Jwts.SIG.HS256.validateKey(secretKey, false);

JCA Provider Integration

Custom Provider Support

import io.jsonwebtoken.impl.security.JcaTemplate;
import java.security.Provider;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

// Use Bouncy Castle provider
Provider bcProvider = new BouncyCastleProvider();

// Algorithm with custom provider
SecretKey bcKey = Jwts.SIG.HS256.key()
    .provider(bcProvider)
    .build();

KeyPair bcKeyPair = Jwts.SIG.RS256.keyPair()
    .provider(bcProvider)
    .build();

// JCA Template usage
JcaTemplate jcaTemplate = new JcaTemplate("AES", bcProvider);

Provider Fallback Handling

// JJWT automatically handles provider fallbacks
// If specified provider doesn't support algorithm, falls back to default

SecretKey resilientKey = Jwts.SIG.HS256.key()
    .provider(possiblyUnsupportedProvider) // Fallback if unsupported
    .build();

// Check provider capabilities
boolean supportsAlgorithm = checkProviderSupport(provider, "HmacSHA256");

Algorithm Validation and Selection

Key Strength Validation

// Automatic key strength validation
try {
    // This will throw exception if key is too weak
    SecretKey weakKey = createWeakHmacKey(); // e.g., 128 bits for HS256
    String jwt = Jwts.builder()
        .subject("user")
        .signWith(weakKey, Jwts.SIG.HS256) // Will validate key strength
        .compact();
} catch (SecurityException e) {
    // Key doesn't meet algorithm requirements
    handleWeakKey(e);
}

// Manual key validation
boolean isValidKey = Jwts.SIG.HS256.validateKey(secretKey, false);
if (!isValidKey) {
    throw new SecurityException("Key does not meet HS256 requirements");
}

Algorithm Discovery

// Find appropriate algorithm for key
SecretKey someKey = getUnknownKey();
SecureDigestAlgorithm<?, ?> algorithm = Jwts.SIG.get().forKey(someKey);

String algorithmId = algorithm.getId();
int keyBitLength = algorithm.getKeyBitLength();

// Algorithm compatibility check
boolean compatible = algorithm.validateKey(someKey, false);

Advanced Security Features

Critical Header Parameter Validation

// Critical header parameters require explicit handling
Map<String, Object> criticalParams = Map.of(
    "security-level", "high",
    "custom-validation", "required"
);

String tokenWithCritical = Jwts.builder()
    .subject("user")
    .header()
        .critical().add("security-level").add("custom-validation").and()
        .add("security-level", "high")
        .add("custom-validation", "required")
        .and()
    .signWith(secretKey)
    .compact();

// Parser must handle critical parameters
JwtParser criticalParser = Jwts.parser()
    .verifyWith(secretKey)
    .critical()
        .add("security-level")
        .add("custom-validation")
        .and()
    .build();

X.509 Certificate Support

import io.jsonwebtoken.impl.security.X509BuilderSupport;
import java.security.cert.X509Certificate;

// X.509 certificate chain building
X509Certificate[] certChain = getCertificateChain();

String certJwt = Jwts.builder()
    .subject("certified-user")
    .header()
        .x509CertChain(Arrays.asList(certChain))
        .and()
    .signWith(privateKeyFromCert)
    .compact();

Algorithm-Specific Features

// ECDH-ES key agreement with additional parameters
KeyPair ecdhPair = Jwts.KEY.ECDH_ES.keyPair().build();

// PBES2 with custom iteration count and salt
Map<String, Object> pbes2Params = Map.of(
    "p2s", "custom-salt".getBytes(),
    "p2c", 4096 // iteration count
);

// AES-GCM with authentication data
byte[] additionalAuthenticatedData = "additional-data".getBytes();

Performance Considerations

Algorithm Registry Caching

// Registries are cached for performance
SecureDigestAlgorithm<?, ?> cachedAlg1 = Jwts.SIG.get("HS256");
SecureDigestAlgorithm<?, ?> cachedAlg2 = Jwts.SIG.get("HS256");
// cachedAlg1 == cachedAlg2 (same instance)

// Efficient algorithm lookup
boolean hasAlgorithm = Jwts.SIG.get().containsKey("HS256");
Set<String> availableAlgorithms = Jwts.SIG.get().keySet();

Key Generation Optimization

// Reuse SecureRandom for multiple operations
SecureRandom sharedRandom = SecureRandom.getInstanceStrong();

SecretKey key1 = Jwts.SIG.HS256.key().random(sharedRandom).build();
SecretKey key2 = Jwts.SIG.HS256.key().random(sharedRandom).build();
KeyPair pair1 = Jwts.SIG.RS256.keyPair().random(sharedRandom).build();

// Provider reuse
Provider sharedProvider = new BouncyCastleProvider();
SecretKey bcKey1 = Jwts.SIG.HS256.key().provider(sharedProvider).build();
SecretKey bcKey2 = Jwts.SIG.HS384.key().provider(sharedProvider).build();

Custom Algorithm Implementation

Extending Algorithm Registries

import io.jsonwebtoken.impl.lang.DefaultRegistry;

// Custom algorithm registration (for extensions)
// Note: This requires implementing the appropriate algorithm interfaces

// Add custom signature algorithm to registry
DefaultRegistry<SecureDigestAlgorithm<?, ?>> customSigRegistry = 
    new DefaultRegistry<>("Custom Signature Algorithms");

customSigRegistry.add(customSignatureAlgorithm);

// Add to parser
JwtParser customParser = Jwts.parser()
    .verifyWith(secretKey)
    .sig()
        .add(customSignatureAlgorithm)
        .and()
    .build();

The Security Algorithms implementation provides production-ready, JWA-compliant cryptographic operations with comprehensive key management, validation, and performance optimization features.

Install with Tessl CLI

npx tessl i tessl/maven-io-jsonwebtoken--jjwt-impl

docs

security-algorithms.md

utilities.md

tile.json

tessl/maven-io-jsonwebtoken--jjwt-impl