0
# Configuration Encryption
1

2
Jasypt-based encryption and decryption support for sensitive configuration values. The encryption system provides configurable algorithms, providers, initialization vectors, and seamless integration with all configuration loading mechanisms.
3

4
## Capabilities
5

6
### Jasypt Cipher Executor
7

8
Primary encryption/decryption implementation using Jasypt library with full configurability for algorithms, providers, and security parameters.
9

10
```java { .api }
11
public class CasConfigurationJasyptCipherExecutor implements CipherExecutor<String, String> {
12
    /**
13
     * Constructor with algorithm and password.
14
     *
15
     * @param algorithm the encryption algorithm
16
     * @param password  the encryption password
17
     */
18
    public CasConfigurationJasyptCipherExecutor(String algorithm, String password);
19
    
20
    /**
21
     * Constructor using environment properties for configuration.
22
     *
23
     * @param environment the environment with Jasypt configuration properties
24
     */
25
    public CasConfigurationJasyptCipherExecutor(Environment environment);
26
    
27
    /**
28
     * Encrypt value with parameters.
29
     *
30
     * @param value      the value to encrypt
31
     * @param parameters optional parameters
32
     * @return encrypted value with prefix
33
     */
34
    @Override
35
    public String encode(String value, Object[] parameters);
36
    
37
    /**
38
     * Decrypt value with parameters.
39
     *
40
     * @param value      the encrypted value
41
     * @param parameters optional parameters
42
     * @return decrypted value
43
     */
44
    @Override
45
    public String decode(String value, Object[] parameters);
46
    
47
    /**
48
     * Get cipher executor name.
49
     *
50
     * @return "CAS Configuration Jasypt Encryption"
51
     */
52
    @Override
53
    public String getName();
54
}
55
```
56

57
### Encryption Methods
58

59
```java { .api }
60
public class CasConfigurationJasyptCipherExecutor {
61
    /**
62
     * Encrypt value with error handling.
63
     *
64
     * @param value the value to encrypt
65
     * @return encrypted value with prefix, or null on error
66
     */
67
    public String encryptValue(String value);
68
    
69
    /**
70
     * Encrypt value with custom error handler.
71
     *
72
     * @param value   the value to encrypt
73
     * @param handler error handling function
74
     * @return encrypted value or handler result
75
     */
76
    public String encryptValue(String value, Function<Exception, String> handler);
77
    
78
    /**
79
     * Decrypt value with error handling.
80
     *
81
     * @param value the encrypted value
82
     * @return decrypted value, or original value on error
83
     */
84
    public String decryptValue(String value);
85
}
86
```
87

88
### Configuration Methods
89

90
```java { .api }
91
public class CasConfigurationJasyptCipherExecutor {
92
    /**
93
     * Set encryption algorithm.
94
     *
95
     * @param alg the algorithm (e.g., "PBEWithMD5AndTripleDES")
96
     */
97
    public void setAlgorithm(String alg);
98
    
99
    /**
100
     * Set encryption password.
101
     *
102
     * @param psw the password
103
     */
104
    public void setPassword(String psw);
105
    
106
    /**
107
     * Set encryption provider name.
108
     *
109
     * @param pName the provider name (null for default, "BC" for BouncyCastle)
110
     */
111
    public void setProviderName(String pName);
112
    
113
    /**
114
     * Set key obtention iterations.
115
     *
116
     * @param iter the number of iterations as string
117
     */
118
    public void setKeyObtentionIterations(String iter);
119
    
120
    /**
121
     * Set initialization vector generator.
122
     *
123
     * @param iv the IV generator
124
     */
125
    public void setIvGenerator(IvGenerator iv);
126
}
127
```
128

129
### Static Utility Methods
130

131
```java { .api }
132
public class CasConfigurationJasyptCipherExecutor {
133
    /**
134
     * Check if value is encrypted (starts with prefix).
135
     *
136
     * @param value the value to check
137
     * @return true if encrypted
138
     */
139
    public static boolean isValueEncrypted(String value);
140
    
141
    /**
142
     * Extract encrypted value without prefix.
143
     *
144
     * @param value the prefixed encrypted value
145
     * @return encrypted value without prefix
146
     */
147
    public static String extractEncryptedValue(String value);
148
}
149
```
150

151
## Usage Examples
152

153
### Basic Encryption Setup
154

155
```java
156
import org.apereo.cas.configuration.support.CasConfigurationJasyptCipherExecutor;
157

158
// Create cipher executor with algorithm and password
159
CasConfigurationJasyptCipherExecutor cipherExecutor = 
160
    new CasConfigurationJasyptCipherExecutor("PBEWithMD5AndTripleDES", "mySecretPassword");
161

162
// Encrypt a sensitive value
163
String sensitiveValue = "database_password_123";
164
String encrypted = cipherExecutor.encryptValue(sensitiveValue);
165
System.out.println(encrypted); // {cas-cipher}ENCRYPTED_CONTENT
166

167
// Decrypt the value
168
String decrypted = cipherExecutor.decryptValue(encrypted);
169
System.out.println(decrypted); // database_password_123
170
```
171

172
### Environment-Based Configuration
173

174
```java
175
// Set environment properties for Jasypt configuration
176
System.setProperty("cas.standalone.configuration-security.alg", "PBEWITHHMACSHA256ANDAES_128");
177
System.setProperty("cas.standalone.configuration-security.psw", "myEncryptionPassword");
178
System.setProperty("cas.standalone.configuration-security.provider", "BC");
179
System.setProperty("cas.standalone.configuration-security.iterations", "1000");
180

181
// Create cipher executor from environment
182
CasConfigurationJasyptCipherExecutor cipherExecutor = 
183
    new CasConfigurationJasyptCipherExecutor(environment);
184

185
// Use for encryption/decryption
186
String encrypted = cipherExecutor.encryptValue("sensitive_data");
187
```
188

189
### Advanced Configuration
190

191
```java
192
import org.jasypt.iv.RandomIvGenerator;
193
import org.jasypt.iv.NoIvGenerator;
194

195
// Create cipher executor
196
CasConfigurationJasyptCipherExecutor cipherExecutor = 
197
    new CasConfigurationJasyptCipherExecutor("PBEWITHHMACSHA256ANDAES_128", "password");
198

199
// Configure advanced settings
200
cipherExecutor.setProviderName("BC");  // Use BouncyCastle provider
201
cipherExecutor.setKeyObtentionIterations("10000");
202
cipherExecutor.setIvGenerator(new RandomIvGenerator());  // Use random IV
203

204
// Encrypt with advanced configuration
205
String encrypted = cipherExecutor.encryptValue("highly_sensitive_data");
206
```
207

208
### Integration with Configuration Loading
209

210
```java
211
import org.apereo.cas.configuration.DefaultCasConfigurationPropertiesSourceLocator;
212

213
// Create cipher executor
214
CasConfigurationJasyptCipherExecutor cipherExecutor = 
215
    new CasConfigurationJasyptCipherExecutor(environment);
216

217
// Create property source locator with encryption support
218
DefaultCasConfigurationPropertiesSourceLocator locator = 
219
    new DefaultCasConfigurationPropertiesSourceLocator(cipherExecutor);
220

221
// All loaded properties will be automatically decrypted
222
Optional<PropertySource<?>> properties = locator.locate(environment, resourceLoader);
223
```
224

225
## Encryption Parameters
226

227
### Jasypt Configuration Parameters
228

229
```java { .api }
230
public enum JasyptEncryptionParameters {
231
    /**
232
     * Jasypt algorithm name to use.
233
     */
234
    ALGORITHM("cas.standalone.configuration-security.alg", "PBEWithMD5AndTripleDES"),
235
    
236
    /**
237
     * Jasypt provider name to use. None for Java, "BC" for BouncyCastle.
238
     */
239
    PROVIDER("cas.standalone.configuration-security.provider", null),
240
    
241
    /**
242
     * Jasypt number of iterations to use.
243
     */
244
    ITERATIONS("cas.standalone.configuration-security.iterations", null),
245
    
246
    /**
247
     * Jasypt password to use for encryption and decryption.
248
     */
249
    PASSWORD("cas.standalone.configuration-security.psw", null),
250
    
251
    /**
252
     * Use (or not) a Jasypt Initialization Vector.
253
     */
254
    INITIALIZATION_VECTOR("cas.standalone.configuration-security.initialization-vector", null);
255
    
256
    /**
257
     * Get the property name for this parameter.
258
     *
259
     * @return property name
260
     */
261
    String getPropertyName();
262
    
263
    /**
264
     * Get the default value for this parameter.
265
     *
266
     * @return default value
267
     */
268
    String getDefaultValue();
269
}
270
```
271

272
### Supported Algorithms
273

274
#### Standard Java Algorithms
275
- `PBEWithMD5AndTripleDES` (default)
276
- `PBEWithMD5AndDES`
277
- `PBEWithSHA1AndRC2_40`
278
- `PBEWithSHA1AndDESede`
279

280
#### BouncyCastle Algorithms (with provider "BC")
281
- `PBEWITHHMACSHA256ANDAES_128`
282
- `PBEWITHHMACSHA256ANDAES_256`
283
- `PBEWITHHMACSHA1ANDAES_128`
284
- `PBEWITHHMACSHA1ANDAES_256`
285

286
#### Initialization Vector Requirements
287

288
Algorithms matching pattern `PBEWITHHMACSHA\d+ANDAES_.*(?<!-BC)$` require initialization vectors and automatically use `RandomIvGenerator`.
289

290
## Configuration File Usage
291

292
### YAML Configuration with Encrypted Values
293

294
```yaml
295
# application.yml
296
database:
297
  url: "jdbc:mysql://localhost:3306/cas"
298
  username: "cas_user"
299
  password: "{cas-cipher}DroW8Pj4z6WkEbCJy4NqGxCqY8fhOKGOtDbWlHGUgOZ2vtK1Boo="
300

301
ldap:
302
  bindCredential: "{cas-cipher}Ak8fKzKp9Z4bWqRxYJ8Ts3+P8sXyO9C1NqO4DpL2MkGf3=="
303

304
# Non-encrypted values work normally
305
server:
306
  port: 8443
307
  ssl:
308
    enabled: true
309
```
310

311
### Properties Configuration with Encrypted Values
312

313
```properties
314
# application.properties
315
database.url=jdbc:mysql://localhost:3306/cas
316
database.username=cas_user
317
database.password={cas-cipher}DroW8Pj4z6WkEbCJy4NqGxCqY8fhOKGOtDbWlHGUgOZ2vtK1Boo=
318

319
ldap.bindCredential={cas-cipher}Ak8fKzKp9Z4bWqRxYJ8Ts3+P8sXyO9C1NqO4DpL2MkGf3==
320

321
# Non-encrypted values
322
server.port=8443
323
server.ssl.enabled=true
324
```
325

326
## Encryption Constants
327

328
```java { .api }
329
/**
330
 * Prefix inserted at the beginning of a value to indicate it's encrypted.
331
 */
332
String ENCRYPTED_VALUE_PREFIX = "{cas-cipher}";
333

334
/**
335
 * Pattern for algorithms that require an initialization vector.
336
 */
337
Pattern ALGS_THAT_REQUIRE_IV_PATTERN = Pattern.compile("PBEWITHHMACSHA\\d+ANDAES_.*(?<!-BC)$");
338
```
339

340
## Security Considerations
341

342
### Password Management
343
- Never hardcode encryption passwords in source code
344
- Use environment variables or external configuration for passwords
345
- Consider key rotation strategies for production environments
346

347
### Algorithm Selection
348
- Use stronger algorithms like `PBEWITHHMACSHA256ANDAES_128` for production
349
- BouncyCastle provider offers additional algorithm options
350
- Consider initialization vector requirements for enhanced security
351

352
### Property Protection
353
- Only encrypt truly sensitive values (passwords, tokens, keys)
354
- Encrypted values are Base64-encoded and can be lengthy
355
- Decryption errors will log warnings but preserve original values