0
# Security & Cryptography
1

2
Security utilities including hash calculation, UUID generation, PKCE (Proof Key for Code Exchange) implementation, and certificate fingerprinting for OAuth and authentication workflows. These utilities provide cryptographically secure operations for microservices security requirements.
3

4
## Capabilities
5

6
### Hash Utilities
7

8
Comprehensive hashing and UUID generation utilities with support for MD5, PBKDF2 password hashing, and secure UUID generation.
9

10
```java { .api }
11
/**
12
 * Hash calculation utilities (MD5, PBKDF2, UUID generation)
13
 */
14
public class HashUtil {
15
    // UUID generation
16
    public static String generateUUID();
17
    
18
    // MD5 hashing
19
    public static String md5(String input);
20
    public static String md5Hex(String message);
21
    
22
    // Utility conversion
23
    public static String hex(byte[] array);
24
    
25
    // Password hashing with PBKDF2
26
    public static String generateStrongPasswordHash(String password) throws NoSuchAlgorithmException, InvalidKeySpecException;
27
    public static boolean validatePassword(char[] originalPassword, String storedPassword) throws NoSuchAlgorithmException, InvalidKeySpecException;
28
}
29
```
30

31
**Usage Examples:**
32

33
```java
34
import com.networknt.utility.HashUtil;
35

36
// UUID generation (Base64 URL-safe)
37
String uuid = HashUtil.generateUUID(); // "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"
38

39
// MD5 hashing
40
String hash = HashUtil.md5("hello world");
41
String hexHash = HashUtil.md5Hex("hello world"); // "5d41402abc4b2a76b9719d911017c592"
42

43
// Secure password hashing
44
String hashedPassword = HashUtil.generateStrongPasswordHash("mySecretPassword");
45
// Result: "1000:hex_salt:hex_hash" format using PBKDF2
46

47
// Password validation
48
boolean isValid = HashUtil.validatePassword(
49
    "mySecretPassword".toCharArray(), 
50
    hashedPassword
51
); // true
52

53
// Byte array to hex conversion
54
byte[] data = "hello".getBytes();
55
String hexString = HashUtil.hex(data); // "68656c6c6f"
56
```
57

58
### PKCE (Proof Key for Code Exchange) Utilities
59

60
OAuth 2.0 PKCE implementation for secure authorization code flows, commonly used in mobile and single-page applications.
61

62
```java { .api }
63
/**
64
 * PKCE (Proof Key for Code Exchange) implementation for OAuth
65
 */
66
public class CodeVerifierUtil {
67
    // Constants
68
    public static final String CODE_CHALLENGE_METHOD_S256 = "S256";
69
    public static final String CODE_CHALLENGE_METHOD_PLAIN = "plain";
70
    public static final int MIN_CODE_VERIFIER_LENGTH = 43;
71
    public static final int MAX_CODE_VERIFIER_LENGTH = 128;
72
    public static final int DEFAULT_CODE_VERIFIER_ENTROPY = 64;
73
    public static final int MIN_CODE_VERIFIER_ENTROPY = 32;
74
    public static final int MAX_CODE_VERIFIER_ENTROPY = 96;
75
    public static final Pattern VALID_CODE_CHALLENGE_PATTERN = Pattern.compile("^[0-9a-zA-Z\\-\\.~_]+$");
76
    
77
    // Code verifier generation
78
    public static String generateRandomCodeVerifier();
79
    public static String generateRandomCodeVerifier(SecureRandom entropySource, int entropyBytes);
80
    
81
    // Challenge derivation
82
    public static String deriveCodeVerifierChallenge(String codeVerifier);
83
    public static String getCodeVerifierChallengeMethod();
84
}
85
```
86

87
**Usage Examples:**
88

89
```java
90
import com.networknt.utility.CodeVerifierUtil;
91
import java.security.SecureRandom;
92

93
// Generate PKCE code verifier
94
String codeVerifier = CodeVerifierUtil.generateRandomCodeVerifier();
95
// Result: 43-128 character string, e.g., "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789aBcDeFgHiJ"
96

97
// Generate with custom entropy
98
SecureRandom random = new SecureRandom();
99
String customVerifier = CodeVerifierUtil.generateRandomCodeVerifier(random, 32);
100

101
// Derive code challenge for OAuth flow
102
String codeChallenge = CodeVerifierUtil.deriveCodeVerifierChallenge(codeVerifier);
103
// Result: Base64 URL-encoded SHA256 hash
104

105
// Get challenge method
106
String method = CodeVerifierUtil.getCodeVerifierChallengeMethod(); // "S256"
107

108
// Complete OAuth PKCE flow example
109
String verifier = CodeVerifierUtil.generateRandomCodeVerifier();
110
String challenge = CodeVerifierUtil.deriveCodeVerifierChallenge(verifier);
111

112
// Use in OAuth authorization URL
113
String authUrl = "https://auth.example.com/oauth/authorize?" +
114
    "client_id=myapp&" +
115
    "response_type=code&" +
116
    "redirect_uri=https://myapp.com/callback&" +
117
    "code_challenge=" + challenge + "&" +
118
    "code_challenge_method=" + CodeVerifierUtil.getCodeVerifierChallengeMethod();
119

120
// Later, exchange code with verifier
121
// POST to token endpoint with code_verifier=verifier
122
```
123

124
### Certificate Fingerprinting
125

126
Certificate fingerprint calculation for certificate validation and identification.
127

128
```java { .api }
129
/**
130
 * Certificate fingerprint calculation
131
 */
132
public class FingerPrintUtil {
133
    /**
134
     * Generates SHA-1 fingerprint of certificate
135
     * @param cert - X.509 certificate
136
     * @return SHA-1 fingerprint as hex string
137
     */
138
    public static String getCertFingerPrint(Certificate cert);
139
}
140
```
141

142
**Usage Examples:**
143

144
```java
145
import com.networknt.utility.FingerPrintUtil;
146
import java.security.cert.Certificate;
147
import java.security.cert.X509Certificate;
148

149
// Get certificate fingerprint
150
X509Certificate cert = // ... obtain certificate
151
String fingerprint = FingerPrintUtil.getCertFingerPrint(cert);
152
// Result: "A1:B2:C3:D4:E5:F6:07:08:09:0A:1B:2C:3D:4E:5F:60:71:82:93:A4"
153

154
// Use case: Certificate pinning validation
155
public boolean validateCertificatePin(Certificate cert, String expectedFingerprint) {
156
    String actualFingerprint = FingerPrintUtil.getCertFingerPrint(cert);
157
    return expectedFingerprint.equalsIgnoreCase(actualFingerprint);
158
}
159

160
// Use case: Certificate identification in logs
161
public void logCertificateInfo(Certificate cert) {
162
    String fingerprint = FingerPrintUtil.getCertFingerPrint(cert);
163
    logger.info("Certificate fingerprint: {}", fingerprint);
164
}
165
```
166

167
### Common Security Patterns
168

169
**API Authentication Token Generation:**
170
```java
171
// Generate secure API tokens
172
String apiToken = HashUtil.generateUUID(); // URL-safe, no special characters
173
// Store hashed version
174
String hashedToken = HashUtil.md5Hex(apiToken + "salt");
175
```
176

177
**OAuth 2.0 PKCE Flow:**
178
```java
179
// Authorization request
180
String codeVerifier = CodeVerifierUtil.generateRandomCodeVerifier();
181
String codeChallenge = CodeVerifierUtil.deriveCodeVerifierChallenge(codeVerifier);
182

183
// Store codeVerifier securely for token exchange
184
// Send codeChallenge in authorization URL
185

186
// Token exchange (later)
187
// Use stored codeVerifier in token request
188
```
189

190
**Password Security:**
191
```java
192
// User registration
193
String userPassword = "userEnteredPassword";
194
String hashedPassword = HashUtil.generateStrongPasswordHash(userPassword);
195
// Store hashedPassword in database
196

197
// User login
198
boolean isValidLogin = HashUtil.validatePassword(
199
    enteredPassword.toCharArray(),
200
    storedHashedPassword
201
);
202
```
203

204
**Certificate Validation:**
205
```java
206
// Validate certificate against known fingerprints
207
Set<String> trustedFingerprints = Set.of(
208
    "A1:B2:C3:D4:E5:F6:07:08:09:0A:1B:2C:3D:4E:5F:60:71:82:93:A4",
209
    "B2:C3:D4:E5:F6:07:08:09:0A:1B:2C:3D:4E:5F:60:71:82:93:A4:B5"
210
);
211

212
String certFingerprint = FingerPrintUtil.getCertFingerPrint(certificate);
213
boolean isTrusted = trustedFingerprints.contains(certFingerprint);
214
```