0
# Cryptographic Operations
1
2
Comprehensive cryptographic support for signing, verification, key management, and algorithm abstraction with support for modern cryptographic standards including RSA, ECDSA, EdDSA, and HMAC.
3
4
## Capabilities
5
6
### Signature Contexts
7
8
Core interfaces for cryptographic signing and verification operations with pluggable algorithm support.
9
10
```java { .api }
11
/**
12
* Interface for cryptographic signature creation
13
*/
14
public interface SignatureSignerContext {
15
/**
16
* Create a signature for the provided data
17
* @param data Data to sign
18
* @return Signature bytes
19
* @throws SignatureException if signing fails
20
*/
21
byte[] sign(byte[] data) throws SignatureException;
22
23
/**
24
* Get the signing algorithm identifier
25
* @return Algorithm name (e.g., "RS256", "ES256", "HS256")
26
*/
27
String getAlgorithm();
28
29
/**
30
* Get the key identifier used for signing
31
* @return Key ID or null if not available
32
*/
33
String getKid();
34
}
35
36
/**
37
* Interface for cryptographic signature verification
38
*/
39
public interface SignatureVerifierContext {
40
/**
41
* Verify a signature against the provided data
42
* @param data Original data that was signed
43
* @param signature Signature bytes to verify
44
* @return true if signature is valid
45
* @throws SignatureException if verification fails
46
*/
47
boolean verify(byte[] data, byte[] signature) throws SignatureException;
48
49
/**
50
* Get the verification algorithm identifier
51
* @return Algorithm name (e.g., "RS256", "ES256", "HS256")
52
*/
53
String getAlgorithm();
54
55
/**
56
* Get the key identifier used for verification
57
* @return Key ID or null if not available
58
*/
59
String getKid();
60
}
61
```
62
63
### Key Management
64
65
Comprehensive key wrapper and metadata management system for cryptographic keys.
66
67
```java { .api }
68
/**
69
* Container for cryptographic keys with associated metadata
70
*/
71
public class KeyWrapper {
72
/**
73
* Get the key identifier
74
* @return Key ID string
75
*/
76
public String getKid();
77
78
/**
79
* Get the cryptographic algorithm for this key
80
* @return Algorithm identifier
81
*/
82
public String getAlgorithm();
83
84
/**
85
* Get the key type
86
* @return KeyType enum value
87
*/
88
public KeyType getType();
89
90
/**
91
* Get the intended key usage
92
* @return KeyUse enum value
93
*/
94
public KeyUse getUse();
95
96
/**
97
* Get the key status
98
* @return KeyStatus enum value
99
*/
100
public KeyStatus getStatus();
101
102
/**
103
* Get the public key (if available)
104
* @return PublicKey instance or null
105
*/
106
public PublicKey getPublicKey();
107
108
/**
109
* Get the secret key (if available)
110
* @return SecretKey instance or null
111
*/
112
public SecretKey getSecretKey();
113
114
/**
115
* Get the private key (if available)
116
* @return PrivateKey instance or null
117
*/
118
public PrivateKey getPrivateKey();
119
120
/**
121
* Get the X.509 certificate (if available)
122
* @return Certificate instance or null
123
*/
124
public Certificate getCertificate();
125
126
/**
127
* Get the certificate chain (if available)
128
* @return Certificate array or null
129
*/
130
public Certificate[] getCertificateChain();
131
}
132
133
/**
134
* Container for multiple public keys with lookup capabilities
135
*/
136
public class PublicKeysWrapper {
137
/**
138
* Get all public keys
139
* @return List of KeyWrapper instances
140
*/
141
public List<KeyWrapper> getKeys();
142
143
/**
144
* Get a public key by key ID
145
* @param kid Key identifier
146
* @return KeyWrapper instance or null if not found
147
*/
148
public KeyWrapper getKeyByKid(String kid);
149
150
/**
151
* Get keys by algorithm
152
* @param algorithm Algorithm identifier
153
* @return List of matching KeyWrapper instances
154
*/
155
public List<KeyWrapper> getKeysByAlg(String algorithm);
156
}
157
```
158
159
### Key Type and Status Enums
160
161
```java { .api }
162
/**
163
* Cryptographic key type constants interface
164
*/
165
public interface KeyType {
166
/** Elliptic Curve keys */
167
String EC = "EC";
168
/** RSA keys */
169
String RSA = "RSA";
170
/** Octet sequence (symmetric) keys */
171
String OCT = "OCT";
172
/** Octet string key pairs (EdDSA) */
173
String OKP = "OKP";
174
}
175
176
/**
177
* Key usage enumeration
178
*/
179
public enum KeyUse {
180
/** Signature and verification operations */
181
SIG,
182
/** Encryption and decryption operations */
183
ENC
184
}
185
186
/**
187
* Key status management enumeration
188
*/
189
public enum KeyStatus {
190
/** Currently active key for signing and encryption */
191
ACTIVE,
192
/** Passive key for verification and decryption only */
193
PASSIVE,
194
/** Disabled key not used for any operations */
195
DISABLED
196
}
197
```
198
199
### Algorithm Constants
200
201
Comprehensive algorithm identifier constants for various cryptographic operations.
202
203
```java { .api }
204
/**
205
* Cryptographic algorithm constants interface
206
*/
207
public interface Algorithm {
208
// RSA PKCS#1 v1.5 algorithms
209
String RS256 = "RS256";
210
String RS384 = "RS384";
211
String RS512 = "RS512";
212
213
// RSA PSS algorithms
214
String PS256 = "PS256";
215
String PS384 = "PS384";
216
String PS512 = "PS512";
217
218
// ECDSA algorithms
219
String ES256 = "ES256";
220
String ES384 = "ES384";
221
String ES512 = "ES512";
222
223
// EdDSA algorithms
224
String EdDSA = "EdDSA";
225
String Ed25519 = "Ed25519";
226
String Ed448 = "Ed448";
227
228
// HMAC algorithms
229
String HS256 = "HS256";
230
String HS384 = "HS384";
231
String HS512 = "HS512";
232
233
// AES Key Wrap algorithms
234
String A128KW = "A128KW";
235
String A192KW = "A192KW";
236
String A256KW = "A256KW";
237
238
// AES GCM Key Wrap algorithms
239
String A128GCMKW = "A128GCMKW";
240
String A192GCMKW = "A192GCMKW";
241
String A256GCMKW = "A256GCMKW";
242
243
// Direct encryption
244
String DIR = "dir";
245
246
// RSA OAEP algorithms
247
String RSA1_5 = "RSA1_5";
248
String RSA_OAEP = "RSA-OAEP";
249
String RSA_OAEP_256 = "RSA-OAEP-256";
250
251
// Content encryption algorithms
252
String A128CBC_HS256 = "A128CBC-HS256";
253
String A192CBC_HS384 = "A192CBC-HS384";
254
String A256CBC_HS512 = "A256CBC-HS512";
255
String A128GCM = "A128GCM";
256
String A192GCM = "A192GCM";
257
String A256GCM = "A256GCM";
258
}
259
```
260
261
### Asymmetric Signature Implementations
262
263
RSA and ECDSA signature creation and verification implementations.
264
265
```java { .api }
266
/**
267
* Asymmetric signature creation context
268
*/
269
public class AsymmetricSignatureSignerContext implements SignatureSignerContext {
270
/**
271
* Create asymmetric signature signer
272
* @param keyWrapper Key wrapper containing private key
273
*/
274
public AsymmetricSignatureSignerContext(KeyWrapper keyWrapper);
275
276
public byte[] sign(byte[] data) throws SignatureException;
277
public String getAlgorithm();
278
public String getKid();
279
}
280
281
/**
282
* Asymmetric signature verification context
283
*/
284
public class AsymmetricSignatureVerifierContext implements SignatureVerifierContext {
285
/**
286
* Create asymmetric signature verifier
287
* @param keyWrapper Key wrapper containing public key
288
*/
289
public AsymmetricSignatureVerifierContext(KeyWrapper keyWrapper);
290
291
public boolean verify(byte[] data, byte[] signature) throws SignatureException;
292
public String getAlgorithm();
293
public String getKid();
294
}
295
296
/**
297
* ECDSA signature creation context
298
*/
299
public class ECDSASignatureSignerContext implements SignatureSignerContext {
300
public ECDSASignatureSignerContext(KeyWrapper keyWrapper);
301
public byte[] sign(byte[] data) throws SignatureException;
302
public String getAlgorithm();
303
public String getKid();
304
}
305
306
/**
307
* ECDSA signature verification context
308
*/
309
public class ECDSASignatureVerifierContext implements SignatureVerifierContext {
310
public ECDSASignatureVerifierContext(KeyWrapper keyWrapper);
311
public boolean verify(byte[] data, byte[] signature) throws SignatureException;
312
public String getAlgorithm();
313
public String getKid();
314
}
315
```
316
317
### HMAC Signature Implementations
318
319
HMAC-based signature creation and verification for shared secret scenarios.
320
321
```java { .api }
322
/**
323
* HMAC signature creation context
324
*/
325
public class MacSignatureSignerContext implements SignatureSignerContext {
326
/**
327
* Create HMAC signature signer
328
* @param keyWrapper Key wrapper containing secret key
329
*/
330
public MacSignatureSignerContext(KeyWrapper keyWrapper);
331
332
public byte[] sign(byte[] data) throws SignatureException;
333
public String getAlgorithm();
334
public String getKid();
335
}
336
337
/**
338
* HMAC signature verification context
339
*/
340
public class MacSignatureVerifierContext implements SignatureVerifierContext {
341
/**
342
* Create HMAC signature verifier
343
* @param keyWrapper Key wrapper containing secret key
344
*/
345
public MacSignatureVerifierContext(KeyWrapper keyWrapper);
346
347
public boolean verify(byte[] data, byte[] signature) throws SignatureException;
348
public String getAlgorithm();
349
public String getKid();
350
}
351
```
352
353
### ECDSA Algorithm Support
354
355
Elliptic Curve Digital Signature Algorithm utilities and curve definitions.
356
357
```java { .api }
358
/**
359
* ECDSA algorithm utilities
360
*/
361
public class ECDSAAlgorithm {
362
/**
363
* Get the Java algorithm name for an ECDSA algorithm identifier
364
* @param algorithmId ECDSA algorithm ID (ES256, ES384, ES512)
365
* @return Java algorithm name
366
*/
367
public static String getJavaAlgorithm(String algorithmId);
368
369
/**
370
* Get the curve name for an ECDSA algorithm
371
* @param algorithmId ECDSA algorithm ID
372
* @return Curve name
373
*/
374
public static String getCurve(String algorithmId);
375
}
376
377
/**
378
* Elliptic curve definitions
379
*/
380
public enum ECCurve {
381
P256("secp256r1", "ES256"),
382
P384("secp384r1", "ES384"),
383
P521("secp521r1", "ES512");
384
385
private final String name;
386
private final String algorithm;
387
388
ECCurve(String name, String algorithm) {
389
this.name = name;
390
this.algorithm = algorithm;
391
}
392
393
public String getName();
394
public String getAlgorithm();
395
}
396
```
397
398
### Java Algorithm Mapping
399
400
Mapping between JOSE algorithm identifiers and Java cryptographic algorithm names.
401
402
```java { .api }
403
/**
404
* Java algorithm name mapping utilities
405
*/
406
public class JavaAlgorithm {
407
/**
408
* Get the Java algorithm name for a JOSE algorithm identifier
409
* @param joseAlgorithm JOSE algorithm identifier
410
* @return Java algorithm name
411
*/
412
public static String getJavaAlgorithm(String joseAlgorithm);
413
414
/**
415
* Get the key algorithm for a signature algorithm
416
* @param signatureAlgorithm Signature algorithm identifier
417
* @return Key algorithm name
418
*/
419
public static String getKeyAlgorithm(String signatureAlgorithm);
420
421
/**
422
* Check if algorithm is RSA-based
423
* @param algorithm Algorithm identifier
424
* @return true if RSA algorithm
425
*/
426
public static boolean isRSA(String algorithm);
427
428
/**
429
* Check if algorithm is ECDSA-based
430
* @param algorithm Algorithm identifier
431
* @return true if ECDSA algorithm
432
*/
433
public static boolean isECDSA(String algorithm);
434
435
/**
436
* Check if algorithm is HMAC-based
437
* @param algorithm Algorithm identifier
438
* @return true if HMAC algorithm
439
*/
440
public static boolean isHMAC(String algorithm);
441
}
442
```
443
444
## Exception Handling
445
446
```java { .api }
447
/**
448
* Exception thrown during cryptographic signature operations
449
*/
450
public class SignatureException extends Exception {
451
public SignatureException(String message);
452
public SignatureException(String message, Throwable cause);
453
}
454
455
/**
456
* Exception thrown during hash operations
457
*/
458
public class HashException extends Exception {
459
public HashException(String message);
460
public HashException(String message, Throwable cause);
461
}
462
```
463
464
## Usage Examples
465
466
```java
467
import org.keycloak.crypto.*;
468
import java.security.KeyPair;
469
import java.security.KeyPairGenerator;
470
471
// RSA signature creation and verification
472
KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
473
keyGen.initialize(2048);
474
KeyPair keyPair = keyGen.generateKeyPair();
475
476
KeyWrapper signingKey = new KeyWrapper();
477
signingKey.setKid("rsa-key-1");
478
signingKey.setAlgorithm(Algorithm.RS256);
479
signingKey.setType(KeyType.RSA);
480
signingKey.setUse(KeyUse.SIG);
481
signingKey.setStatus(KeyStatus.ACTIVE);
482
signingKey.setPrivateKey(keyPair.getPrivate());
483
signingKey.setPublicKey(keyPair.getPublic());
484
485
// Create signature
486
SignatureSignerContext signer = new AsymmetricSignatureSignerContext(signingKey);
487
byte[] data = "Hello, World!".getBytes();
488
byte[] signature = signer.sign(data);
489
490
// Verify signature
491
KeyWrapper verifyingKey = new KeyWrapper();
492
verifyingKey.setKid("rsa-key-1");
493
verifyingKey.setAlgorithm(Algorithm.RS256);
494
verifyingKey.setPublicKey(keyPair.getPublic());
495
496
SignatureVerifierContext verifier = new AsymmetricSignatureVerifierContext(verifyingKey);
497
boolean isValid = verifier.verify(data, signature);
498
499
// HMAC signature with shared secret
500
KeyWrapper hmacKey = new KeyWrapper();
501
hmacKey.setKid("hmac-key-1");
502
hmacKey.setAlgorithm(Algorithm.HS256);
503
hmacKey.setType(KeyType.OCT);
504
hmacKey.setSecretKey(secretKey);
505
506
MacSignatureSignerContext hmacSigner = new MacSignatureSignerContext(hmacKey);
507
byte[] hmacSignature = hmacSigner.sign(data);
508
509
MacSignatureVerifierContext hmacVerifier = new MacSignatureVerifierContext(hmacKey);
510
boolean hmacValid = hmacVerifier.verify(data, hmacSignature);
511
```