0
# Codec Utilities
1

2
Encoding and decoding utilities for Base64, Hexadecimal, and UTF-8 conversions commonly used in cryptographic operations.
3

4
## Capabilities
5

6
### Base64 Codec
7

8
Base64 encoding and decoding utilities for binary data representation.
9

10
```java { .api }
11
/**
12
 * Base64 encoding and decoding utilities (deprecated - use java.util.Base64)
13
 */
14
@Deprecated
15
class Base64 {
16
    /**
17
     * Encode bytes to Base64 format
18
     * @param bytes the bytes to encode
19
     * @return the Base64 encoded bytes
20
     */
21
    static byte[] encode(byte[] bytes);
22
    
23
    /**
24
     * Decode Base64 bytes to original format
25
     * @param bytes the Base64 encoded bytes to decode
26
     * @return the decoded bytes
27
     */
28
    static byte[] decode(byte[] bytes);
29
    
30
    /**
31
     * Check if the byte array is Base64 encoded
32
     * @param bytes the bytes to check
33
     * @return true if Base64 encoded, false otherwise
34
     */
35
    static boolean isBase64(byte[] bytes);
36
}
37
```
38

39
**Usage Example:**
40

41
```java
42
import org.springframework.security.crypto.codec.Base64;
43

44
// Encode bytes to Base64
45
byte[] data = "Hello World".getBytes();
46
byte[] encoded = Base64.encode(data);
47

48
// Decode Base64 back to original
49
byte[] decoded = Base64.decode(encoded);
50

51
// Validation
52
boolean isValid = Base64.isBase64(encoded);
53
```
54

55
### Hex Codec
56

57
Hexadecimal encoding and decoding utilities for binary data representation.
58

59
```java { .api }
60
/**
61
 * Hexadecimal encoding and decoding utilities
62
 */
63
class Hex {  
64
    /**
65
     * Encode bytes to hexadecimal character array
66
     * @param bytes the bytes to encode
67
     * @return the hex encoded character array
68
     */
69
    static char[] encode(byte[] bytes);
70
    
71
    /**
72
     * Decode hexadecimal string to bytes
73
     * @param s the hex string to decode
74
     * @return the decoded bytes
75
     */
76
    static byte[] decode(CharSequence s);
77
}
78
```
79

80
**Usage Example:**
81

82
```java
83
import org.springframework.security.crypto.codec.Hex;
84

85
// Encode bytes to hex
86
byte[] data = "Hello World".getBytes();
87
char[] hexChars = Hex.encode(data);
88
String hexString = new String(hexChars);
89

90
// Decode hex back to original
91
byte[] decoded = Hex.decode(hexString);
92

93
// Example output: "Hello World" -> "48656c6c6f20576f726c64"
94
System.out.println(hexString); // "48656c6c6f20576f726c64"
95
```
96

97
### UTF-8 Codec
98

99
UTF-8 encoding and decoding utilities for string/byte conversions.
100

101
```java { .api }
102
/**
103
 * UTF-8 encoding and decoding utilities
104
 */
105
class Utf8 {
106
    /**
107
     * Encode string to UTF-8 bytes
108
     * @param string the string to encode
109
     * @return the UTF-8 encoded bytes
110
     */
111
    static byte[] encode(CharSequence string);
112
    
113
    /**
114
     * Decode UTF-8 bytes to string
115
     * @param bytes the UTF-8 bytes to decode
116
     * @return the decoded string
117
     */
118
    static String decode(byte[] bytes);
119
}
120
```
121

122
**Usage Example:**
123

124
```java
125
import org.springframework.security.crypto.codec.Utf8;
126

127
// Encode string to UTF-8 bytes
128
String text = "Hello 世界";
129
byte[] utf8Bytes = Utf8.encode(text);
130

131
// Decode UTF-8 bytes back to string
132
String decoded = Utf8.decode(utf8Bytes);
133

134
// Useful for consistent encoding in cryptographic operations
135
String password = "pássword123";
136
byte[] passwordBytes = Utf8.encode(password); // for key derivation
137
```
138

139
### Encoding Utils
140

141
General encoding utilities for common operations.
142

143
```java { .api }
144
/**
145
 * Static helper for encoding data (for internal use only)
146
 */
147
class EncodingUtils {
148
    /**
149
     * Concatenate multiple byte arrays
150
     * @param arrays the byte arrays to concatenate
151
     * @return the concatenated byte array
152
     */
153
    static byte[] concatenate(byte[]... arrays);
154
    
155
    /**
156
     * Extract a sub array of bytes out of the byte array
157
     * @param array the byte array to extract from
158
     * @param beginIndex the beginning index of the sub array, inclusive
159
     * @param endIndex the ending index of the sub array, exclusive
160
     * @return the sub array
161
     */
162
    static byte[] subArray(byte[] array, int beginIndex, int endIndex);
163
}
164
```
165

166
## Common Usage Patterns
167

168
### Cryptographic Key Preparation
169

170
```java
171
import org.springframework.security.crypto.codec.*;
172

173
// Prepare password for key derivation
174
String password = "mySecretPassword";
175
byte[] passwordBytes = Utf8.encode(password);
176

177
// Prepare hex-encoded salt
178
String saltHex = "deadbeefcafebabe";
179
byte[] salt = Hex.decode(saltHex);
180

181
// Encode result for storage
182
byte[] derivedKey = performKeyDerivation(passwordBytes, salt);
183
byte[] encodedKey = Base64.encode(derivedKey);
184
String keyForStorage = new String(encodedKey);
185
```
186

187
### Data Encoding for Transmission
188

189
```java
190
// Encrypt data and encode for safe transmission
191
byte[] plaintext = Utf8.encode("Sensitive Information");
192
byte[] encrypted = encryptor.encrypt(plaintext);
193

194
// Safe for JSON/XML/URL transmission
195
byte[] base64Encrypted = Base64.encode(encrypted);
196
String safeEncrypted = new String(base64Encrypted);
197

198
// Or hex encoding for debugging/logging (less efficient)
199
char[] hexChars = Hex.encode(encrypted);
200
String hexEncrypted = new String(hexChars);
201
```
202

203
### Validation and Parsing
204

205
```java
206
// Validate input format before processing
207
String userInput = "48656c6c6f20576f726c64";
208
if (isValidHex(userInput)) {
209
    byte[] data = Hex.decode(userInput);
210
    // process data
211
}
212

213
// Validate Base64 before decoding
214
String base64Input = "SGVsbG8gV29ybGQ=";
215
byte[] base64Bytes = base64Input.getBytes();
216
if (Base64.isBase64(base64Bytes)) {
217
    byte[] data = Base64.decode(base64Bytes);
218
    // process data
219
}
220
```
221

222
### Security Utilities
223

224
Security-focused utilities for constant-time operations to prevent timing attacks.
225

226
```java { .api }
227
/**
228
 * Utility for constant time comparison to prevent against timing attacks
229
 */
230
class PasswordEncoderUtils {
231
    /**
232
     * Constant time comparison to prevent against timing attacks
233
     * @param expected the expected string
234
     * @param actual the actual string to compare
235
     * @return true if strings are equal, false otherwise
236
     */
237
    static boolean equals(String expected, String actual);
238
}
239
```
240

241
**Usage Example:**
242

243
```java
244
import org.springframework.security.crypto.password.PasswordEncoderUtils;
245

246
// Secure comparison that prevents timing attacks
247
String expected = "secretPassword";
248
String actual = getUserInput();
249
boolean matches = PasswordEncoderUtils.equals(expected, actual);
250
```
251

252
## Security Considerations
253

254
- **Constant Time Operations**: Use `PasswordEncoderUtils.equals()` for secure string comparisons to prevent timing attacks
255
- **Character Encoding**: Always use UTF-8 encoding for consistent string-to-byte conversion
256
- **Input Validation**: Validate encoded input before decoding to prevent exceptions
257
- **Memory Management**: Be aware that encoding operations create new byte arrays
258
- **Case Sensitivity**: Hex decoding is case-insensitive, but be consistent in encoding