0
# TLS and Certificate Management
1

2
Advanced TLS certificate and key management utilities that provide automatic certificate reloading, custom verification, and flexible trust store configuration for gRPC connections.
3

4
## Capabilities
5

6
### Advanced Trust Manager
7

8
The `AdvancedTlsX509TrustManager` provides enhanced trust management with certificate reloading and custom verification capabilities.
9

10
```java { .api }
11
/**
12
 * Advanced TLS trust manager with certificate reloading and custom verification.
13
 * Supports automatic certificate refresh from files and custom peer verification.
14
 */
15
public final class AdvancedTlsX509TrustManager extends X509ExtendedTrustManager {
16
  
17
  /**
18
   * Creates a new builder for configuring the trust manager
19
   * @return Builder instance for configuration
20
   */
21
  public static Builder newBuilder();
22

23
  /**
24
   * Uses the default trust certificates stored on user's local system
25
   * @throws CertificateException if certificate processing fails
26
   * @throws KeyStoreException if keystore operations fail  
27
   * @throws NoSuchAlgorithmException if trust manager algorithm unavailable
28
   */
29
  public void useSystemDefaultTrustCerts() throws CertificateException, KeyStoreException, NoSuchAlgorithmException;
30

31
  /**
32
   * Updates the current cached trust certificates
33
   * @param trustCerts the trust certificates to use
34
   * @throws IOException if certificate processing fails
35
   * @throws GeneralSecurityException if security operations fail
36
   */
37
  public void updateTrustCredentials(X509Certificate[] trustCerts) throws IOException, GeneralSecurityException;
38

39
  /**
40
   * Updates trust certificates from a local file path
41
   * @param trustCertFile the file containing trust certificates
42
   * @throws IOException if file operations fail
43
   * @throws GeneralSecurityException if certificate processing fails
44
   */
45
  public void updateTrustCredentials(File trustCertFile) throws IOException, GeneralSecurityException;
46

47
  /**
48
   * Schedules periodic reading of trust certificates from file
49
   * @param trustCertFile the file containing trust certificates
50
   * @param period the period between successive read-and-update executions
51
   * @param unit the time unit of the period parameter
52
   * @param executor the executor service used to read and update the credentials
53
   * @return a Closeable that caller should close when file refreshes are not needed
54
   * @throws IOException if file operations fail
55
   * @throws GeneralSecurityException if certificate processing fails
56
   */
57
  public Closeable updateTrustCredentials(File trustCertFile, long period, TimeUnit unit, ScheduledExecutorService executor) throws IOException, GeneralSecurityException;
58
}
59
```
60

61
**Builder Configuration:**
62

63
```java { .api }
64
public static final class Builder {
65
  /**
66
   * Sets verification mode for peer certificate authentication
67
   * @param verification the verification mode to use
68
   * @return Builder instance for method chaining
69
   */
70
  public Builder setVerification(Verification verification);
71

72
  /**
73
   * Sets custom peer verifier for additional certificate checks
74
   * @param verifier the custom peer verifier
75
   * @return Builder instance for method chaining  
76
   */
77
  public Builder setSslSocketAndEnginePeerVerifier(SslSocketAndEnginePeerVerifier verifier);
78

79
  /**
80
   * Builds the configured trust manager
81
   * @return configured AdvancedTlsX509TrustManager instance
82
   * @throws CertificateException if trust manager creation fails
83
   */
84
  public AdvancedTlsX509TrustManager build() throws CertificateException;
85
}
86
```
87

88
**Verification Modes:**
89

90
```java { .api }
91
public enum Verification {
92
  /** Performs both certificate and hostname verification (RECOMMENDED) */
93
  CERTIFICATE_AND_HOST_NAME_VERIFICATION,
94
  /** Performs only certificate verification (requires custom peer verification) */
95
  CERTIFICATE_ONLY_VERIFICATION,
96
  /** Skips all verification (DANGEROUS - requires custom implementation) */
97
  INSECURELY_SKIP_ALL_VERIFICATION
98
}
99
```
100

101
**Custom Peer Verification:**
102

103
```java { .api }
104
public interface SslSocketAndEnginePeerVerifier {
105
  /**
106
   * Verifies peer certificate chain for socket connections
107
   * @param peerCertChain the certificate chain from the peer
108
   * @param authType the key exchange algorithm used
109
   * @param socket the socket used for connection (may be null)
110
   * @throws CertificateException if verification fails
111
   */
112
  void verifyPeerCertificate(X509Certificate[] peerCertChain, String authType, Socket socket) throws CertificateException;
113

114
  /**
115
   * Verifies peer certificate chain for engine connections  
116
   * @param peerCertChain the certificate chain from the peer
117
   * @param authType the key exchange algorithm used
118
   * @param engine the SSL engine used for connection (may be null)
119
   * @throws CertificateException if verification fails
120
   */
121
  void verifyPeerCertificate(X509Certificate[] peerCertChain, String authType, SSLEngine engine) throws CertificateException;
122
}
123
```
124

125
**Usage Examples:**
126

127
```java
128
import io.grpc.util.AdvancedTlsX509TrustManager;
129
import java.security.cert.X509Certificate;
130
import java.io.File;
131
import java.util.concurrent.Executors;
132
import java.util.concurrent.TimeUnit;
133

134
// Basic trust manager with system defaults
135
AdvancedTlsX509TrustManager trustManager = AdvancedTlsX509TrustManager.newBuilder()
136
    .setVerification(AdvancedTlsX509TrustManager.Verification.CERTIFICATE_AND_HOST_NAME_VERIFICATION)
137
    .build();
138
trustManager.useSystemDefaultTrustCerts();
139

140
// Trust manager with custom certificates
141
X509Certificate[] customCerts = loadCustomCertificates();
142
trustManager.updateTrustCredentials(customCerts);
143

144
// Trust manager with automatic certificate reloading
145
File certFile = new File("/path/to/trust-certs.pem");
146
AdvancedTlsX509TrustManager.Closeable reloader = trustManager.updateTrustCredentials(
147
    certFile, 
148
    30, 
149
    TimeUnit.MINUTES, 
150
    Executors.newScheduledThreadPool(1)
151
);
152

153
// Remember to close the reloader when done
154
reloader.close();
155
```
156

157
### Advanced Key Manager
158

159
The `AdvancedTlsX509KeyManager` provides enhanced key management with identity credential reloading capabilities.
160

161
```java { .api }
162
/**
163
 * Advanced key manager with identity credential reloading capabilities.
164
 * Supports automatic credential refresh from files.
165
 * Uses default constructor for instantiation.
166
 */
167
public final class AdvancedTlsX509KeyManager extends X509ExtendedKeyManager {
168

169
  /**
170
   * Creates a new advanced key manager instance
171
   */
172
  public AdvancedTlsX509KeyManager();
173

174
  /**
175
   * Updates current cached private key and certificate chains
176
   * @param certs the certificate chain to use  
177
   * @param key the private key to use
178
   * @throws IOException if credential processing fails
179
   * @throws GeneralSecurityException if security operations fail
180
   */
181
  public void updateIdentityCredentials(X509Certificate[] certs, PrivateKey key) throws IOException, GeneralSecurityException;
182

183
  /**
184
   * Updates identity credentials from local files
185
   * @param certFile the file containing certificate chain
186
   * @param keyFile the file containing private key
187
   * @throws IOException if file operations fail
188
   * @throws GeneralSecurityException if credential processing fails
189
   */
190
  public void updateIdentityCredentials(File certFile, File keyFile) throws IOException, GeneralSecurityException;
191

192
  /**
193
   * Schedules periodic reading of identity credentials from files
194
   * @param certFile the file containing certificate chain
195
   * @param keyFile the file containing private key  
196
   * @param period the period between successive updates
197
   * @param unit the time unit of the period parameter
198
   * @param executor the executor service for scheduled updates
199
   * @return Closeable to stop the scheduled updates
200
   * @throws IOException if initial file read fails
201
   * @throws GeneralSecurityException if credential processing fails
202
   */
203
  public Closeable updateIdentityCredentials(File certFile, File keyFile, long period, TimeUnit unit, ScheduledExecutorService executor) throws IOException, GeneralSecurityException;
204
}
205
```
206

207
**Usage Examples:**
208

209
```java
210
import io.grpc.util.AdvancedTlsX509KeyManager;
211
import java.security.PrivateKey;
212
import java.security.cert.X509Certificate;
213
import java.io.File;
214

215
// Basic key manager with credentials
216
AdvancedTlsX509KeyManager keyManager = new AdvancedTlsX509KeyManager();
217
X509Certificate[] certChain = loadCertificateChain();
218
PrivateKey privateKey = loadPrivateKey();
219
keyManager.updateIdentityCredentials(certChain, privateKey);
220

221
// Key manager with automatic credential reloading
222
File certFile = new File("/path/to/server-cert.pem");
223
File keyFile = new File("/path/to/server-key.pem");
224
AdvancedTlsX509KeyManager.Closeable reloader = keyManager.updateIdentityCredentials(
225
    certFile, 
226
    keyFile,
227
    60, 
228
    TimeUnit.MINUTES, 
229
    Executors.newScheduledThreadPool(1)
230
);
231
```
232

233
### Closeable Interface
234

235
Specialized Closeable interface for resource management in TLS operations.
236

237
```java { .api }
238
/**
239
 * Custom Closeable interface that extends java.io.Closeable
240
 * Used by credential reloading methods to manage scheduled tasks
241
 */
242
public interface Closeable extends java.io.Closeable {
243
  /**
244
   * Closes the resource without throwing checked exceptions
245
   */
246
  @Override
247
  void close();
248
}
249
```
250

251
### Certificate Utilities
252

253
Utility methods for parsing certificates and private keys from PEM format.
254

255
```java { .api }
256
/**
257
 * Utility methods for certificate and private key parsing.
258
 * All methods are static and thread-safe.
259
 */
260
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8024")
261
public final class CertificateUtils {
262

263
  /**
264
   * Generates X509Certificate array from PEM formatted input stream
265
   * @param inputStream input stream containing PEM formatted certificates
266
   * @return array of X509Certificate instances
267
   * @throws IOException if stream reading fails
268
   * @throws GeneralSecurityException if certificate parsing fails
269
   */
270
  public static X509Certificate[] getX509Certificates(InputStream inputStream) throws IOException, GeneralSecurityException;
271

272
  /**
273
   * Generates PrivateKey from PKCS #8 formatted PEM input stream
274
   * @param inputStream input stream containing PKCS #8 formatted private key
275
   * @return PrivateKey instance
276
   * @throws IOException if stream reading fails  
277
   * @throws GeneralSecurityException if key parsing fails
278
   */
279
  public static PrivateKey getPrivateKey(InputStream inputStream) throws IOException, GeneralSecurityException;
280
}
281
```
282

283
**Usage Examples:**
284

285
```java
286
import io.grpc.util.CertificateUtils;
287
import java.io.FileInputStream;
288
import java.io.InputStream;
289
import java.security.PrivateKey;
290
import java.security.cert.X509Certificate;
291

292
// Parse certificates from PEM file
293
try (InputStream certStream = new FileInputStream("certificates.pem")) {
294
    X509Certificate[] certificates = CertificateUtils.getX509Certificates(certStream);
295
}
296

297
// Parse private key from PEM file  
298
try (InputStream keyStream = new FileInputStream("private-key.pem")) {
299
    PrivateKey privateKey = CertificateUtils.getPrivateKey(keyStream);
300
}
301
```
302

303
## Types
304

305
```java { .api }
306
/**
307
 * Non-throwing closeable interface for cleanup operations
308
 */
309
public interface Closeable extends java.io.Closeable {
310
  @Override
311
  void close();
312
}
313
```
314

315
## Security Considerations
316

317
- Always use `CERTIFICATE_AND_HOST_NAME_VERIFICATION` for production environments
318
- `CERTIFICATE_ONLY_VERIFICATION` requires additional peer verification to be secure
319
- `INSECURELY_SKIP_ALL_VERIFICATION` should never be used in production
320
- When using automatic reloading, ensure certificate files have appropriate file permissions
321
- Minimum refresh period is automatically enforced at 1 minute for security reasons
322
- Always close `Closeable` instances returned by scheduling methods to prevent resource leaks