0
# Key Generation
1

2
Secure random key generation utilities for creating cryptographic keys and salts using various algorithms and encoding schemes.
3

4
## Capabilities
5

6
### BytesKeyGenerator Interface
7

8
Generator for unique byte array-based keys.
9

10
```java { .api }
11
/**
12
 * A generator for unique byte array-based keys
13
 */
14
interface BytesKeyGenerator {
15
    /**
16
     * Get the key length in bytes
17
     * @return the key length
18
     */
19
    int getKeyLength();
20
    
21
    /**
22
     * Generate a new key
23
     * @return the generated key bytes
24
     */
25
    byte[] generateKey();
26
}
27
```
28

29
### StringKeyGenerator Interface
30

31
Generator for unique string keys.
32

33
```java { .api }
34
/**
35
 * A generator for unique string keys
36
 */
37
interface StringKeyGenerator {
38
    /**
39
     * Generate a new key string
40
     * @return the generated key string
41
     */
42
    String generateKey();
43
}
44
```
45

46
### KeyGenerators Factory
47

48
Factory for commonly used key generator implementations.
49

50
```java { .api }
51
/**
52
 * Factory for commonly used key generators
53
 */
54
class KeyGenerators {
55
    /**
56
     * Creates a secure random bytes key generator with default length (8 bytes)
57
     * @return the bytes key generator
58
     */
59
    static BytesKeyGenerator secureRandom();
60
    
61
    /**
62
     * Creates a secure random bytes key generator with custom length
63
     * @param keyLength the key length in bytes
64
     * @return the bytes key generator
65
     */
66
    static BytesKeyGenerator secureRandom(int keyLength);
67
    
68
    /**
69
     * Creates a shared key generator that always returns the same key
70
     * @param keyLength the key length in bytes
71
     * @return the shared key generator
72
     */
73
    static BytesKeyGenerator shared(int keyLength);
74
    
75
    /**
76
     * Creates a hex-encoded string key generator
77
     * @return the string key generator
78
     */
79
    static StringKeyGenerator string();
80
}
81
```
82

83
**Usage Example:**
84

85
```java
86
import org.springframework.security.crypto.keygen.KeyGenerators;
87
import org.springframework.security.crypto.keygen.BytesKeyGenerator;
88
import org.springframework.security.crypto.keygen.StringKeyGenerator;
89

90
// Generate secure random bytes
91
BytesKeyGenerator bytesGenerator = KeyGenerators.secureRandom();
92
byte[] key = bytesGenerator.generateKey(); // 8 bytes by default
93

94
// Generate secure random bytes with custom length
95
BytesKeyGenerator customBytesGenerator = KeyGenerators.secureRandom(16);
96
byte[] customKey = customBytesGenerator.generateKey(); // 16 bytes
97

98
// Generate hex-encoded string keys
99
StringKeyGenerator stringGenerator = KeyGenerators.string();
100
String stringKey = stringGenerator.generateKey(); // hex-encoded string
101

102
// Shared key generator (for testing or specific use cases)
103
BytesKeyGenerator sharedGenerator = KeyGenerators.shared(12);
104
byte[] sharedKey1 = sharedGenerator.generateKey();
105
byte[] sharedKey2 = sharedGenerator.generateKey(); // same as sharedKey1
106
```
107

108
### Secure Random Bytes Key Generator
109

110
SecureRandom-based key generator for generating cryptographically secure random bytes.
111

112
```java { .api }
113
/**
114
 * A BytesKeyGenerator that uses SecureRandom to generate keys
115
 */
116
class SecureRandomBytesKeyGenerator implements BytesKeyGenerator {
117
    /**
118
     * Creates a secure random bytes key generator with default length (8 bytes)
119
     */
120
    SecureRandomBytesKeyGenerator();
121
    
122
    /**
123
     * Creates a secure random bytes key generator with custom length  
124
     * @param keyLength the key length in bytes
125
     */
126
    SecureRandomBytesKeyGenerator(int keyLength);
127
    
128
    /**
129
     * Creates a secure random bytes key generator with custom SecureRandom
130
     * @param keyLength the key length in bytes
131
     * @param random the SecureRandom instance to use
132
     */
133
    SecureRandomBytesKeyGenerator(int keyLength, SecureRandom random);
134
}
135
```
136

137
### Shared Key Generator
138

139
Key generator that always returns the same key value.
140

141
```java { .api }
142
/**
143
 * A BytesKeyGenerator that always returns the same key
144
 */
145
class SharedKeyGenerator implements BytesKeyGenerator {
146
    /**
147
     * Creates a shared key generator
148
     * @param keyLength the key length in bytes
149
     */
150
    SharedKeyGenerator(int keyLength);
151
    
152
    /**
153
     * Creates a shared key generator with custom SecureRandom for initial key generation
154
     * @param keyLength the key length in bytes
155
     * @param random the SecureRandom instance to use for generating the shared key
156
     */
157
    SharedKeyGenerator(int keyLength, SecureRandom random);
158
}
159
```
160

161
### Base64 String Key Generator
162

163
String key generator that produces Base64-encoded keys.
164

165
```java { .api }
166
/**
167
 * A StringKeyGenerator that generates Base64-encoded string keys
168
 */
169
class Base64StringKeyGenerator implements StringKeyGenerator {
170
    /**
171
     * Creates a Base64 string key generator with default length (8 bytes before encoding)
172
     */
173
    Base64StringKeyGenerator();
174
    
175
    /**
176
     * Creates a Base64 string key generator with custom byte length
177
     * @param keyLength the key length in bytes before Base64 encoding
178
     */
179
    Base64StringKeyGenerator(int keyLength);
180
    
181
    /**
182
     * Creates a Base64 string key generator with custom BytesKeyGenerator
183
     * @param keyGenerator the underlying bytes key generator
184
     */
185
    Base64StringKeyGenerator(BytesKeyGenerator keyGenerator);
186
}
187
```
188

189
### Hex Encoding String Key Generator
190

191
String key generator that produces hexadecimal-encoded keys.
192

193
```java { .api }
194
/**
195
 * A StringKeyGenerator that generates hex-encoded string keys
196
 */
197
class HexEncodingStringKeyGenerator implements StringKeyGenerator {
198
    /**
199
     * Creates a hex encoding string key generator with default length (8 bytes before encoding)
200
     */
201
    HexEncodingStringKeyGenerator();
202
    
203
    /**
204
     * Creates a hex encoding string key generator with custom byte length
205
     * @param keyLength the key length in bytes before hex encoding
206
     */
207
    HexEncodingStringKeyGenerator(int keyLength);
208
    
209
    /**
210
     * Creates a hex encoding string key generator with custom BytesKeyGenerator
211
     * @param keyGenerator the underlying bytes key generator
212
     */
213
    HexEncodingStringKeyGenerator(BytesKeyGenerator keyGenerator);
214
}
215
```
216

217
**Advanced Usage Examples:**
218

219
```java
220
import org.springframework.security.crypto.keygen.*;
221
import java.security.SecureRandom;
222

223
// Custom SecureRandom with specific algorithm
224
SecureRandom customRandom = SecureRandom.getInstance("SHA1PRNG");
225
SecureRandomBytesKeyGenerator customGenerator = 
226
    new SecureRandomBytesKeyGenerator(32, customRandom);
227
byte[] secureKey = customGenerator.generateKey();
228

229
// Base64 string keys for URLs or tokens
230
Base64StringKeyGenerator base64Generator = new Base64StringKeyGenerator(24);
231
String base64Key = base64Generator.generateKey();
232

233
// Hex string keys for display or logging
234
HexEncodingStringKeyGenerator hexGenerator = new HexEncodingStringKeyGenerator(16);
235
String hexKey = hexGenerator.generateKey();
236

237
// Combining generators
238
BytesKeyGenerator bytesGen = KeyGenerators.secureRandom(20);
239
HexEncodingStringKeyGenerator combinedGen = new HexEncodingStringKeyGenerator(bytesGen);
240
String combinedKey = combinedGen.generateKey();
241

242
// Shared keys for testing scenarios
243
SharedKeyGenerator testGenerator = new SharedKeyGenerator(16);
244
byte[] testKey1 = testGenerator.generateKey();
245
byte[] testKey2 = testGenerator.generateKey();
246
// testKey1 and testKey2 are identical
247
```
248

249
## Security Considerations
250

251
When using key generators, consider the following:
252

253
- **Key Length**: Use appropriate key lengths for your security requirements (minimum 128 bits for AES)
254
- **SecureRandom**: The default SecureRandom implementation is cryptographically secure
255
- **Shared Keys**: Only use `SharedKeyGenerator` for testing or specific architectural requirements
256
- **Key Storage**: Generated keys should be stored securely and never logged or exposed
257
- **Key Rotation**: Implement proper key rotation policies for long-lived applications