0
# Cryptographic Algorithms
1

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

4
## Capabilities
5

6
### HMAC Algorithms
7

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

10
```java { .api }
11
/**
12
 * Creates a new Algorithm instance using HmacSHA256. Tokens specify this as "HS256".
13
 * @param secret the secret bytes to use in the verify or signing instance
14
 * @return a valid HMAC256 Algorithm
15
 * @throws IllegalArgumentException if the provided Secret is null
16
 */
17
public static Algorithm HMAC256(byte[] secret) throws IllegalArgumentException;
18

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

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

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

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

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

60
**Usage Examples:**
61

62
```java
63
import com.auth0.jwt.algorithms.Algorithm;
64

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

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

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

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

78
// Use with JWT creation
79
String token = JWT.create()
80
    .withIssuer("auth0")
81
    .sign(hmac256);
82

83
// Use with JWT verification
84
JWTVerifier verifier = JWT.require(hmac256)
85
    .withIssuer("auth0")
86
    .build();
87
```
88

89
### RSA Algorithms
90

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

93
```java { .api }
94
/**
95
 * Creates a new Algorithm instance using SHA256withRSA. Tokens specify this as "RS256".
96
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
97
 * @return a valid RSA256 Algorithm
98
 * @throws IllegalArgumentException if the provided Key is null
99
 */
100
public static Algorithm RSA256(RSAKeyProvider keyProvider);
101

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

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

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

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

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

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

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

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

170
**Usage Examples:**
171

172
```java
173
import java.security.KeyPair;
174
import java.security.KeyPairGenerator;
175
import java.security.interfaces.RSAPrivateKey;
176
import java.security.interfaces.RSAPublicKey;
177
import java.security.interfaces.RSAKey;
178

179
// Generate RSA key pair for demonstration
180
KeyPairGenerator keyGenerator = KeyPairGenerator.getInstance("RSA");
181
keyGenerator.initialize(2048);
182
KeyPair keyPair = keyGenerator.generateKeyPair();
183
RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
184
RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();
185

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

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

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

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

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

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

208
// Use with JWT verification (requires public key)
209
JWTVerifier verifier = JWT.require(rsa256)
210
    .withIssuer("auth0")
211
    .build();
212
```
213

214
### ECDSA Algorithms
215

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

218
```java { .api }
219
/**
220
 * Creates a new Algorithm instance using SHA256withECDSA. Tokens specify this as "ES256".
221
 * @param keyProvider the provider of the Public Key and Private Key for the verify and signing instance
222
 * @return a valid ECDSA256 Algorithm
223
 * @throws IllegalArgumentException if the Key Provider is null
224
 */
225
public static Algorithm ECDSA256(ECDSAKeyProvider keyProvider);
226

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

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

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

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

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

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

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

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

295
**Usage Examples:**
296

297
```java
298
import java.security.KeyPair;
299
import java.security.KeyPairGenerator;
300
import java.security.interfaces.ECPrivateKey;
301
import java.security.interfaces.ECPublicKey;
302
import java.security.interfaces.ECKey;
303
import java.security.spec.ECGenParameterSpec;
304

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

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

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

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

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

325
// Generate keys for different curves
326
// ES384 uses P-384 curve
327
KeyPairGenerator es384Generator = KeyPairGenerator.getInstance("EC");
328
es384Generator.initialize(new ECGenParameterSpec("secp384r1")); // P-384
329
KeyPair es384KeyPair = es384Generator.generateKeyPair();
330
Algorithm ecdsa384 = Algorithm.ECDSA384(
331
    (ECPublicKey) es384KeyPair.getPublic(),
332
    (ECPrivateKey) es384KeyPair.getPrivate()
333
);
334

335
// ES512 uses P-521 curve
336
KeyPairGenerator es512Generator = KeyPairGenerator.getInstance("EC");
337
es512Generator.initialize(new ECGenParameterSpec("secp521r1")); // P-521
338
KeyPair es512KeyPair = es512Generator.generateKeyPair();
339
Algorithm ecdsa512 = Algorithm.ECDSA512(
340
    (ECPublicKey) es512KeyPair.getPublic(),
341
    (ECPrivateKey) es512KeyPair.getPrivate()
342
);
343

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

349
JWTVerifier verifier = JWT.require(ecdsa256)
350
    .withIssuer("auth0")
351
    .build();
352
```
353

354
### None Algorithm
355

356
Algorithm that provides no signature for unverified JWTs.
357

358
```java { .api }
359
/**
360
 * Creates a new Algorithm instance that doesn't use any signature.
361
 * Tokens specify this as "none".
362
 * @return a valid None Algorithm
363
 */
364
public static Algorithm none();
365
```
366

367
**Usage Examples:**
368

369
```java
370
// Create algorithm with no signature
371
Algorithm noneAlgorithm = Algorithm.none();
372

373
// Create unsigned JWT (not recommended for production)
374
String unsignedToken = JWT.create()
375
    .withIssuer("auth0")
376
    .withSubject("user123")
377
    .sign(noneAlgorithm);
378

379
// Verify unsigned JWT
380
JWTVerifier verifier = JWT.require(noneAlgorithm)
381
    .withIssuer("auth0")
382
    .build();
383

384
DecodedJWT jwt = verifier.verify(unsignedToken);
385
```
386

387
**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.
388

389
### Algorithm Instance Methods
390

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

393
```java { .api }
394
/**
395
 * Getter for the Id of the Key used to verify the signature on the JWT.
396
 * @return the Key Id that should be used to verify the signature on the JWT or null if not specified
397
 */
398
public String getSigningKeyId();
399

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

406
/**
407
 * Verify the given JWT signature.
408
 * @param jwt the already decoded JWT
409
 * @throws SignatureVerificationException if the signature is invalid
410
 * @throws IllegalArgumentException if the JWT is null
411
 */
412
public abstract void verify(DecodedJWT jwt) throws SignatureVerificationException;
413

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

423
/**
424
 * Sign the given content with this algorithm.
425
 * @param contentBytes the content to be signed
426
 * @return the signature bytes
427
 * @throws SignatureGenerationException if signature cannot be created
428
 */
429
public abstract byte[] sign(byte[] contentBytes) throws SignatureGenerationException;
430
```
431

432
**Usage Examples:**
433

434
```java
435
Algorithm algorithm = Algorithm.HMAC256("secret");
436

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

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

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

452
// Manual signing (typically done internally by JWT.create().sign())
453
try {
454
    byte[] headerBytes = "header".getBytes();
455
    byte[] payloadBytes = "payload".getBytes();
456
    byte[] signature = algorithm.sign(headerBytes, payloadBytes);
457
    System.out.println("Signature created successfully");
458
} catch (SignatureGenerationException e) {
459
    System.err.println("Failed to create signature: " + e.getMessage());
460
}
461
```
462

463
## Algorithm Selection Guide
464

465
### HMAC Algorithms (Symmetric)
466
- **Use Case**: Shared secret scenarios, simple applications, microservices with shared keys
467
- **Security**: Good for internal systems where key distribution is manageable
468
- **Performance**: Fastest option
469
- **Key Management**: Simple but requires secure key sharing
470

471
### RSA Algorithms (Asymmetric)
472
- **Use Case**: Token issuers different from verifiers, public key infrastructure
473
- **Security**: Strong, well-established algorithm
474
- **Performance**: Slower than HMAC, faster verification than signing
475
- **Key Management**: Public key can be shared openly, private key must remain secure
476

477
### ECDSA Algorithms (Asymmetric)
478
- **Use Case**: Similar to RSA but with smaller key sizes and better performance
479
- **Security**: Equivalent security to RSA with smaller keys
480
- **Performance**: Better than RSA, especially for signing operations
481
- **Key Management**: Same as RSA but with more efficient key sizes
482

483
### None Algorithm
484
- **Use Case**: Development, testing, or scenarios where signature verification is handled elsewhere
485
- **Security**: No signature protection
486
- **Performance**: Fastest (no cryptographic operations)
487
- **Key Management**: No keys required
488

489
## Types
490

491
```java { .api }
492
/**
493
 * The Algorithm class represents an algorithm to be used in the Signing or Verification process of a Token.
494
 * This class and its subclasses are thread-safe.
495
 */
496
public abstract class Algorithm {
497
    /**
498
     * Get the signing key ID for this algorithm
499
     * @return signing key ID or null if not applicable
500
     */
501
    public String getSigningKeyId();
502
    
503
    /**
504
     * Get the algorithm name
505
     * @return algorithm name (e.g., "HS256", "RS256", "ES256", "none")
506
     */
507
    public String getName();
508
    
509
    /**
510
     * Verify a JWT signature
511
     * @param jwt decoded JWT to verify
512
     * @throws SignatureVerificationException if verification fails
513
     */
514
    public abstract void verify(DecodedJWT jwt) throws SignatureVerificationException;
515
    
516
    /**
517
     * Sign content with this algorithm
518
     * @param contentBytes content to sign
519
     * @return signature bytes
520
     * @throws SignatureGenerationException if signing fails
521
     */
522
    public abstract byte[] sign(byte[] contentBytes) throws SignatureGenerationException;
523
}
524
```