0
# JJWT Implementation Module
1

2
The JJWT Implementation module (`io.jsonwebtoken:jjwt-impl`) provides concrete implementations of JSON Web Token (JWT) creation, parsing, verification, and cryptographic operations for Java and Android applications. This module works in conjunction with the JJWT API module to deliver a complete JWT/JWS/JWE solution.
3

4
## Package Information
5

6
| Property | Value |
7
|----------|-------|
8
| **Package Name** | `io.jsonwebtoken:jjwt-impl` |
9
| **Type** | Maven Dependency |
10
| **Language** | Java |
11
| **Version** | 0.12.6 |
12
| **License** | Apache 2.0 |
13
| **JDK Support** | Java 8+ |
14
15
## Core Imports
16

17
### Maven Dependency
18

19
```xml { .api }
20
<dependency>
21
    <groupId>io.jsonwebtoken</groupId>
22
    <artifactId>jjwt-impl</artifactId>
23
    <version>0.12.6</version>
24
    <scope>runtime</scope>
25
</dependency>
26
<!-- Also include the API module -->
27
<dependency>
28
    <groupId>io.jsonwebtoken</groupId>
29
    <artifactId>jjwt-api</artifactId>
30
    <version>0.12.6</version>
31
</dependency>
32
```
33

34
### Java Imports
35

36
```java { .api }
37
// Core JWT Operations
38
import io.jsonwebtoken.Jwts;
39
import io.jsonwebtoken.JwtBuilder;
40
import io.jsonwebtoken.JwtParser;
41

42
// Token Types
43
import io.jsonwebtoken.Jwt;
44
import io.jsonwebtoken.Jws;
45
import io.jsonwebtoken.Jwe;
46
import io.jsonwebtoken.Claims;
47

48
// Security
49
import io.jsonwebtoken.security.Keys;
50
import io.jsonwebtoken.security.SecureDigestAlgorithm;
51
import io.jsonwebtoken.security.AeadAlgorithm;
52
import io.jsonwebtoken.security.KeyAlgorithm;
53

54
// JWK Support
55
import io.jsonwebtoken.security.Jwk;
56
import io.jsonwebtoken.security.JwkSet;
57

58
// Standard Java
59
import javax.crypto.SecretKey;
60
import java.security.KeyPair;
61
import java.security.PrivateKey;
62
import java.security.PublicKey;
63
import java.util.Date;
64
```
65

66
## Basic Usage
67

68
### Creating JWTs
69

70
```java { .api }
71
// Create a secret key for HMAC signing
72
SecretKey key = Jwts.SIG.HS256.key().build();
73

74
// Create a simple JWT with claims
75
String jwt = Jwts.builder()
76
    .subject("john.doe")
77
    .issuer("my-app")
78
    .issuedAt(new Date())
79
    .expiration(new Date(System.currentTimeMillis() + 3600000)) // 1 hour
80
    .signWith(key)
81
    .compact();
82

83
// Create a JWT with custom claims
84
String customJwt = Jwts.builder()
85
    .claims()
86
        .subject("user123")
87
        .add("role", "admin")
88
        .add("permissions", Arrays.asList("read", "write"))
89
        .and()
90
    .signWith(key)
91
    .compact();
92
```
93

94
### Parsing JWTs
95

96
```java { .api }
97
// Parse and verify a signed JWT
98
JwtParser parser = Jwts.parser()
99
    .verifyWith(key)
100
    .build();
101

102
Jws<Claims> jws = parser.parseSignedClaims(jwt);
103
Claims claims = jws.getPayload();
104

105
String subject = claims.getSubject();
106
String issuer = claims.getIssuer();
107
Date expiration = claims.getExpiration();
108

109
// Access custom claims
110
String role = claims.get("role", String.class);
111
List<String> permissions = claims.get("permissions", List.class);
112
```
113

114
### Algorithm Usage
115

116
```java { .api }
117
// Use different signature algorithms
118
SecretKey hmacKey = Jwts.SIG.HS512.key().build();
119
KeyPair rsaKeyPair = Jwts.SIG.RS256.keyPair().build();
120
KeyPair ecKeyPair = Jwts.SIG.ES256.keyPair().build();
121

122
// Create JWS with different algorithms
123
String hmacJwt = Jwts.builder()
124
    .subject("user")
125
    .signWith(hmacKey, Jwts.SIG.HS512)
126
    .compact();
127

128
String rsaJwt = Jwts.builder()
129
    .subject("user")
130
    .signWith(rsaKeyPair.getPrivate(), Jwts.SIG.RS256)
131
    .compact();
132

133
// Parse with corresponding verification keys
134
Jws<Claims> hmacClaims = Jwts.parser()
135
    .verifyWith(hmacKey)
136
    .build()
137
    .parseSignedClaims(hmacJwt);
138

139
Jws<Claims> rsaClaims = Jwts.parser()
140
    .verifyWith(rsaKeyPair.getPublic())
141
    .build()
142
    .parseSignedClaims(rsaJwt);
143
```
144

145
## Architecture
146

147
The JJWT Implementation module is organized into several key packages:
148

149
### Core Implementation (`io.jsonwebtoken.impl`)
150
- **DefaultJwtBuilder**: Main JWT/JWS/JWE creation factory
151
- **DefaultJwtParserBuilder**: Parser configuration factory  
152
- **DefaultJwtParser**: JWT/JWS/JWE parsing engine
153
- **Token Models**: DefaultJwt, DefaultJws, DefaultJwe implementations
154
- **Header/Claims Builders**: Type-safe construction utilities
155

156
### Security Package (`io.jsonwebtoken.impl.security`)
157
- **Algorithm Registries**: Signature, encryption, key management algorithms
158
- **JWK Implementation**: JSON Web Key parsing, building, operations
159
- **Key Generation**: Symmetric and asymmetric key creation utilities
160
- **Cryptographic Support**: JCA provider abstractions and security utilities
161

162
### Compression Package (`io.jsonwebtoken.impl.compression`)
163
- **DEFLATE Algorithm**: RFC 1951 standard compression
164
- **GZIP Algorithm**: Common extension compression format
165
- **Abstract Base**: Extensible compression algorithm framework
166

167
### I/O and Utilities
168
- **Base64URL Codec**: RFC 4648 compliant encoding/decoding
169
- **Stream Processing**: Memory-efficient payload handling
170
- **Service Discovery**: Plugin architecture support
171
- **Parameter Validation**: Type-safe configuration utilities
172

173
## Capabilities
174

175
### [JWT Building](./jwt-building.md)
176
Comprehensive JWT, JWS, and JWE token creation with the DefaultJwtBuilder class.
177

178
```java { .api }
179
// Quick example - full JWT creation with encryption
180
SecretKey encKey = Jwts.ENC.A256GCM.key().build();
181
SecretKey kekKey = Jwts.KEY.A256KW.key().build();
182

183
String jwe = Jwts.builder()
184
    .subject("sensitive-user")
185
    .claim("ssn", "123-45-6789")
186
    .encryptWith(kekKey, Jwts.KEY.A256KW, Jwts.ENC.A256GCM)
187
    .compact();
188
```
189

190
### [JWT Parsing](./jwt-parsing.md)
191
Flexible JWT, JWS, and JWE token parsing and validation with DefaultJwtParser.
192

193
```java { .api }
194
// Quick example - parsing with clock skew tolerance
195
JwtParser parser = Jwts.parser()
196
    .decryptWith(kekKey)
197
    .clockSkewSeconds(30) // Allow 30 seconds clock skew
198
    .build();
199

200
Jwe<Claims> jwe = parser.parseEncryptedClaims(encryptedJwt);
201
```
202

203
### [Security Algorithms](./security-algorithms.md)
204
Complete JWA-compliant algorithm implementations for signatures, encryption, and key management.
205

206
```java { .api }
207
// Quick example - algorithm discovery and key generation
208
SecureDigestAlgorithm<?, ?> signAlg = Jwts.SIG.get().forKey(someKey);
209
SecretKey newKey = signAlg.key().build();
210
```
211

212
### [JWK Support](./jwk-support.md)
213
Full JSON Web Key (JWK) and JWK Set functionality with RFC 7517 compliance.
214

215
```java { .api }
216
// Quick example - JWK creation and parsing
217
Jwk<SecretKey> jwk = Jwts.JWK.builder(secretKey)
218
    .id("my-key-1")
219
    .operations().add("sign").add("verify").and()
220
    .build();
221

222
String jwkJson = jwk.toJson();
223
```
224

225
### [Compression](./compression.md)
226
Payload compression support with DEFLATE and GZIP algorithms.
227

228
```java { .api }
229
// Quick example - compressed JWT
230
String compressed = Jwts.builder()
231
    .subject("user")
232
    .claim("data", largeDataString)
233
    .compressWith(Jwts.ZIP.DEF)
234
    .signWith(key)
235
    .compact();
236
```
237

238
### [Utilities](./utilities.md)
239
Essential utilities including cryptographic key management, Base64URL encoding, stream processing, and service discovery.
240

241
```java { .api }
242
// Quick example - secure key generation
243
SecretKey hmacKey = Keys.hmacShaKeyFor(secureRandomBytes);
244
Password password = Keys.password("secret".toCharArray());
245

246
// Base64URL operations
247
Base64UrlCodec codec = new Base64UrlCodec();
248
String encoded = codec.encode("Hello World");
249
byte[] decoded = codec.decode(encoded);
250
```
251

252
## Implementation Features
253

254
### Key Characteristics
255
- **Production Ready**: Battle-tested implementation used by thousands of applications
256
- **JCA Integration**: Full Java Cryptography Architecture support with provider flexibility
257
- **Memory Efficient**: Stream-based processing for large payloads
258
- **Extensible**: Service provider interface for custom algorithms and components
259
- **Type Safe**: Generic type system prevents runtime class cast exceptions
260
- **Secure by Default**: Automatic key validation and algorithm selection
261

262
### Performance Optimizations
263
- **Algorithm Registries**: Fast O(1) algorithm lookup by identifier
264
- **Service Caching**: Cached service discovery with lazy initialization
265
- **Stream Processing**: Avoids loading entire payloads into memory
266
- **Base64URL**: Optimized encoding/decoding without intermediate String creation
267

268
### Security Features
269
- **Key Strength Validation**: Automatic validation of key lengths per algorithm
270
- **Critical Header Parameters**: Validation of critical extension parameters
271
- **Clock Skew Tolerance**: Configurable time-based claim validation
272
- **JCA Provider Support**: Pluggable cryptographic provider architecture
273

274
This implementation module provides the complete runtime functionality for JWT operations while maintaining clean separation from the API definitions, enabling flexible deployment and testing scenarios.