0
# SSL/TLS Configuration
1

2
Comprehensive SSL/TLS support with Netty SSL contexts, optimized for gRPC with proper ALPN negotiation, certificate management, and security configuration. This module provides utilities for creating SSL contexts and credential objects for both client and server use.
3

4
## Capabilities
5

6
### GrpcSslContexts Utility
7

8
Factory methods for creating SSL context builders optimized for gRPC usage.
9

10
```java { .api }
11
/**
12
 * Create an SSL context builder for gRPC clients
13
 * @return SslContextBuilder configured for client use
14
 */
15
public static SslContextBuilder forClient();
16

17
/**
18
 * Create an SSL context builder for gRPC servers
19
 * @param keyCertChainFile Certificate chain file
20
 * @param keyFile Private key file
21
 * @return SslContextBuilder configured for server use
22
 */
23
public static SslContextBuilder forServer(File keyCertChainFile, File keyFile);
24

25
/**
26
 * Create an SSL context builder for gRPC servers with key password
27
 * @param keyCertChainFile Certificate chain file
28
 * @param keyFile Private key file
29
 * @param keyPassword Password for the private key
30
 * @return SslContextBuilder configured for server use
31
 */
32
public static SslContextBuilder forServer(File keyCertChainFile, File keyFile, String keyPassword);
33

34
/**
35
 * Create an SSL context builder for gRPC servers from streams
36
 * @param keyCertChain Certificate chain input stream
37
 * @param key Private key input stream
38
 * @return SslContextBuilder configured for server use
39
 */
40
public static SslContextBuilder forServer(InputStream keyCertChain, InputStream key);
41

42
/**
43
 * Create an SSL context builder for gRPC servers from streams with password
44
 * @param keyCertChain Certificate chain input stream
45
 * @param key Private key input stream
46
 * @param keyPassword Password for the private key
47
 * @return SslContextBuilder configured for server use
48
 */
49
public static SslContextBuilder forServer(InputStream keyCertChain, InputStream key, String keyPassword);
50
```
51

52
**Usage Examples:**
53

54
```java
55
import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
56
import io.grpc.netty.shaded.io.netty.handler.ssl.SslContext;
57
import java.io.File;
58

59
// Client SSL context
60
SslContext clientSslContext = GrpcSslContexts.forClient()
61
    .trustManager(new File("ca.crt"))
62
    .build();
63

64
// Server SSL context
65
SslContext serverSslContext = GrpcSslContexts.forServer(
66
        new File("server.crt"),
67
        new File("server.key")
68
    )
69
    .build();
70

71
// Server with password-protected key
72
SslContext secureServerContext = GrpcSslContexts.forServer(
73
        new File("server.crt"),
74
        new File("server.key"),
75
        "keyPassword"
76
    )
77
    .build();
78
```
79

80
### SSL Context Configuration
81

82
Configure SSL context builders with gRPC-specific optimizations.
83

84
```java { .api }
85
/**
86
 * Configure an SSL context builder for gRPC usage
87
 * @param builder The SslContextBuilder to configure
88
 * @return Configured SslContextBuilder
89
 */
90
public static SslContextBuilder configure(SslContextBuilder builder);
91

92
/**
93
 * Configure an SSL context builder with specific SSL provider
94
 * @param builder The SslContextBuilder to configure
95
 * @param provider The SSL provider to use
96
 * @return Configured SslContextBuilder
97
 */
98
@ExperimentalApi
99
public static SslContextBuilder configure(SslContextBuilder builder, SslProvider provider);
100

101
/**
102
 * Configure an SSL context builder with JDK provider
103
 * @param builder The SslContextBuilder to configure
104
 * @param jdkProvider The JDK security provider
105
 * @return Configured SslContextBuilder
106
 */
107
public static SslContextBuilder configure(SslContextBuilder builder, Provider jdkProvider);
108
```
109

110
**Usage Example:**
111

112
```java
113
import io.grpc.netty.shaded.io.netty.handler.ssl.SslProvider;
114
import io.grpc.netty.shaded.io.netty.handler.ssl.SslContextBuilder;
115

116
// Configure with OpenSSL provider
117
SslContext sslContext = GrpcSslContexts.configure(
118
        SslContextBuilder.forClient(),
119
        SslProvider.OPENSSL
120
    )
121
    .trustManager(new File("ca.crt"))
122
    .build();
123
```
124

125
### Channel Credentials
126

127
Create channel credentials from Netty SSL contexts for client connections.
128

129
```java { .api }
130
/**
131
 * Create channel credentials from an SSL context
132
 * @param sslContext The Netty SSL context
133
 * @return ChannelCredentials for use with channel builders
134
 */
135
public static ChannelCredentials create(SslContext sslContext);
136
```
137

138
**Usage Example:**
139

140
```java
141
import io.grpc.netty.shaded.io.grpc.netty.NettySslContextChannelCredentials;
142
import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
143
import io.grpc.ChannelCredentials;
144

145
SslContext sslContext = GrpcSslContexts.forClient()
146
    .trustManager(new File("ca.crt"))
147
    .build();
148

149
ChannelCredentials credentials = NettySslContextChannelCredentials.create(sslContext);
150

151
ManagedChannel channel = NettyChannelBuilder
152
    .forAddress("secure-service.example.com", 443)
153
    .build();
154
```
155

156
### Server Credentials
157

158
Create server credentials from Netty SSL contexts for server configuration.
159

160
```java { .api }
161
/**
162
 * Create server credentials from an SSL context
163
 * @param sslContext The Netty SSL context
164
 * @return ServerCredentials for use with server builders
165
 */
166
public static ServerCredentials create(SslContext sslContext);
167
```
168

169
**Usage Example:**
170

171
```java
172
import io.grpc.netty.shaded.io.grpc.netty.NettySslContextServerCredentials;
173
import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
174
import io.grpc.ServerCredentials;
175

176
SslContext sslContext = GrpcSslContexts.forServer(
177
        new File("server.crt"),
178
        new File("server.key")
179
    )
180
    .build();
181

182
ServerCredentials credentials = NettySslContextServerCredentials.create(sslContext);
183

184
Server server = NettyServerBuilder
185
    .forPort(9090, credentials)
186
    .addService(new MyServiceImpl())
187
    .build();
188
```
189

190
### Insecure HTTP/1.1 Upgrade Credentials
191

192
Create credentials for insecure HTTP/1.1 to HTTP/2 upgrade scenarios.
193

194
```java { .api }
195
/**
196
 * Create insecure credentials for HTTP/1.1 upgrade
197
 * @return ChannelCredentials for HTTP/1.1 to HTTP/2 upgrade
198
 */
199
public static ChannelCredentials create();
200
```
201

202
**Usage Example:**
203

204
```java
205
import io.grpc.netty.shaded.io.grpc.netty.InsecureFromHttp1ChannelCredentials;
206

207
ChannelCredentials upgradeCredentials = InsecureFromHttp1ChannelCredentials.create();
208

209
ManagedChannel channel = NettyChannelBuilder
210
    .forAddress("localhost", 8080, upgradeCredentials)
211
    .build();
212
```
213

214
## Advanced SSL Configuration Examples
215

216
### Mutual TLS (mTLS) Client
217

218
```java
219
import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
220
import io.grpc.netty.shaded.io.grpc.netty.NettySslContextChannelCredentials;
221
import io.grpc.netty.shaded.io.netty.handler.ssl.SslContext;
222

223
// Create client SSL context with client certificate
224
SslContext clientSslContext = GrpcSslContexts.forClient()
225
    .keyManager(new File("client.crt"), new File("client.key"))
226
    .trustManager(new File("ca.crt"))
227
    .build();
228

229
ChannelCredentials credentials = NettySslContextChannelCredentials.create(clientSslContext);
230

231
ManagedChannel channel = NettyChannelBuilder
232
    .forAddress("secure-service.example.com", 443, credentials)
233
    .build();
234
```
235

236
### Custom Trust Manager
237

238
```java
239
import javax.net.ssl.TrustManagerFactory;
240
import java.security.KeyStore;
241

242
// Load custom trust store
243
KeyStore trustStore = KeyStore.getInstance("JKS");
244
trustStore.load(new FileInputStream("truststore.jks"), "password".toCharArray());
245

246
TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
247
tmf.init(trustStore);
248

249
SslContext sslContext = GrpcSslContexts.forClient()
250
    .trustManager(tmf)
251
    .build();
252
```
253

254
### OpenSSL with ALPN
255

256
```java
257
import io.grpc.netty.shaded.io.netty.handler.ssl.SslProvider;
258
import io.grpc.netty.shaded.io.netty.handler.ssl.ApplicationProtocolConfig;
259

260
SslContext sslContext = GrpcSslContexts.configure(
261
        SslContextBuilder.forClient(),
262
        SslProvider.OPENSSL
263
    )
264
    .trustManager(new File("ca.crt"))
265
    .applicationProtocolConfig(ApplicationProtocolConfig.ALPN)
266
    .build();
267
```
268

269
## Protocol Negotiation Types
270

271
The `NegotiationType` enum defines different approaches to protocol negotiation:
272

273
```java { .api }
274
public enum NegotiationType {
275
    /**
276
     * TLS ALPN/NPN negotiation for SSL connections.
277
     * Assumes an SSL connection and uses ALPN or NPN to negotiate HTTP/2.
278
     */
279
    TLS,
280

281
    /**
282
     * HTTP UPGRADE from HTTP/1.1 to HTTP/2.
283
     * Uses HTTP/1.1 upgrade mechanism to transition to HTTP/2 over plaintext.
284
     */
285
    PLAINTEXT_UPGRADE,
286

287
    /**
288
     * Direct HTTP/2 plaintext connection.
289
     * Assumes the remote endpoint supports HTTP/2 directly without negotiation.
290
     */
291
    PLAINTEXT
292
}
293
```
294

295
**Usage Example:**
296

297
```java
298
import io.grpc.netty.shaded.io.grpc.netty.NegotiationType;
299

300
NettyChannelBuilder builder = NettyChannelBuilder
301
    .forAddress("localhost", 9090)
302
    .negotiationType(NegotiationType.PLAINTEXT_UPGRADE);
303
```
304

305
## Error Handling
306

307
Common SSL/TLS related exceptions:
308

309
- `SSLException` - General SSL configuration or handshake errors
310
- `CertificateException` - Certificate validation or parsing errors  
311
- `NoSuchAlgorithmException` - Unsupported cryptographic algorithms
312
- `KeyStoreException` - Key store loading or access errors
313

314
Always handle these exceptions appropriately in production code:
315

316
```java
317
try {
318
    SslContext sslContext = GrpcSslContexts.forClient()
319
        .trustManager(new File("ca.crt"))
320
        .build();
321
} catch (SSLException e) {
322
    logger.error("Failed to create SSL context", e);
323
    // Handle SSL configuration error
324
}
325
```