0
# SSL/TLS Configuration
1

2
Comprehensive SSL/TLS support for gRPC Netty with utilities for creating properly configured SSL contexts, including ALPN negotiation and certificate management.
3

4
## Core Imports
5

6
```java
7
import io.grpc.netty.GrpcSslContexts;
8
import io.grpc.netty.NettySslContextChannelCredentials;
9
import io.grpc.netty.NettySslContextServerCredentials;
10
import io.grpc.netty.NettyChannelCredentials;
11
import io.grpc.ChannelCredentials;
12
import io.grpc.ServerCredentials;
13
import io.netty.handler.ssl.SslContext;
14
import io.netty.handler.ssl.SslContextBuilder;
15
import io.netty.handler.ssl.SslProvider;
16
import java.io.File;
17
import java.io.InputStream;
18
import java.security.PrivateKey;
19
import java.security.Provider;
20
import java.security.cert.X509Certificate;
21
```
22

23
## GrpcSslContexts
24

25
Utility class for configuring Netty SSL contexts with gRPC-specific settings.
26

27
### Client SSL Context
28

29
```java { .api }
30
public static SslContextBuilder forClient();
31
```
32

33
Creates an SSL context builder for gRPC clients with appropriate ALPN/NPN configuration.
34

35
**Returns:** `SslContextBuilder` configured for gRPC client use
36

37
### Server SSL Context
38

39
```java { .api }
40
public static SslContextBuilder forServer(File keyCertChainFile, File keyFile);
41
public static SslContextBuilder forServer(File keyCertChainFile, File keyFile, String keyPassword);
42
public static SslContextBuilder forServer(InputStream keyCertChain, InputStream key);
43
public static SslContextBuilder forServer(InputStream keyCertChain, InputStream key, String keyPassword);
44
public static SslContextBuilder forServer(PrivateKey key, X509Certificate... keyCertChain);
45
public static SslContextBuilder forServer(PrivateKey key, String keyPassword, X509Certificate... keyCertChain);
46
```
47

48
**Parameters:**
49
- `keyCertChainFile` - Certificate chain file in PEM format
50
- `keyFile` - Private key file in PEM format  
51
- `keyPassword` - Password for encrypted private keys
52
- `keyCertChain` - Certificate chain input stream
53
- `key` - Private key input stream or object
54
- `keyCertChain` - Certificate chain as X.509 certificates
55

56
**Returns:** `SslContextBuilder` configured for gRPC server use
57

58
### SSL Context Configuration
59

60
```java { .api }
61
public static SslContextBuilder configure(SslContextBuilder builder);
62
public static SslContextBuilder configure(SslContextBuilder builder, SslProvider provider);
63
public static SslContextBuilder configure(SslContextBuilder builder, Provider jdkProvider);
64
```
65

66
**Parameters:**
67
- `builder` - Existing `SslContextBuilder` to configure
68
- `provider` - Specific SSL provider (`OPENSSL`, `JDK`)
69
- `jdkProvider` - JDK security provider for SSL implementation
70

71
**Returns:** Configured `SslContextBuilder` with gRPC-specific settings
72

73
## Experimental SSL Credentials
74

75
### NettySslContextChannelCredentials
76

77
```java { .api }
78
public static ChannelCredentials create(SslContext sslContext);
79
```
80

81
**Parameters:**
82
- `sslContext` - Configured Netty `SslContext`
83

84
**Returns:** `ChannelCredentials` for use with channel builders
85

86
### NettySslContextServerCredentials  
87

88
```java { .api }
89
public static ServerCredentials create(SslContext sslContext);
90
```
91

92
**Parameters:**
93
- `sslContext` - Configured Netty `SslContext`
94

95
**Returns:** `ServerCredentials` for use with server builders
96

97
### NettyChannelCredentials
98

99
```java { .api }
100
public static ChannelCredentials create(io.grpc.ChannelCredentials channelCreds);
101
```
102

103
**Parameters:**
104
- `channelCreds` - Standard gRPC channel credentials
105

106
**Returns:** Netty-specific `ChannelCredentials` implementation
107

108
### NettyServerCredentials
109

110
```java { .api }
111
public static ServerCredentials create(io.grpc.ServerCredentials serverCreds);
112
```
113

114
**Parameters:**
115
- `serverCreds` - Standard gRPC server credentials
116

117
**Returns:** Netty-specific `ServerCredentials` implementation
118

119
## Usage Examples
120

121
### Basic Client TLS
122

123
```java
124
import io.grpc.netty.GrpcSslContexts;
125
import io.grpc.netty.NettyChannelBuilder;
126
import io.netty.handler.ssl.SslContext;
127

128
// Client with system default trust store
129
SslContext sslContext = GrpcSslContexts.forClient()
130
    .build();
131

132
ManagedChannel channel = NettyChannelBuilder.forAddress("api.example.com", 443)
133
    .sslContext(sslContext)
134
    .build();
135
```
136

137
### Client with Custom Trust Manager
138

139
```java
140
import javax.net.ssl.TrustManagerFactory;
141
import java.security.KeyStore;
142

143
// Load custom trust store
144
KeyStore trustStore = KeyStore.getInstance("JKS");
145
trustStore.load(new FileInputStream("truststore.jks"), "password".toCharArray());
146

147
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance("SunX509");
148
trustManagerFactory.init(trustStore);
149

150
SslContext sslContext = GrpcSslContexts.forClient()
151
    .trustManager(trustManagerFactory)
152
    .build();
153

154
ManagedChannel channel = NettyChannelBuilder.forAddress("api.example.com", 443)
155
    .sslContext(sslContext)
156
    .build();
157
```
158

159
### Client with Certificate Files
160

161
```java
162
import java.io.File;
163

164
SslContext sslContext = GrpcSslContexts.forClient()
165
    .trustManager(new File("ca-cert.pem"))
166
    .keyManager(new File("client-cert.pem"), new File("client-key.pem"))
167
    .build();
168

169
ManagedChannel channel = NettyChannelBuilder.forAddress("api.example.com", 443)
170
    .sslContext(sslContext)
171
    .build();
172
```
173

174
### Basic Server TLS
175

176
```java
177
import io.grpc.netty.GrpcSslContexts;
178
import io.grpc.netty.NettyServerBuilder;
179
import java.io.File;
180

181
SslContext sslContext = GrpcSslContexts.forServer(
182
    new File("server-cert.pem"),
183
    new File("server-key.pem")
184
).build();
185

186
Server server = NettyServerBuilder.forPort(9090)
187
    .sslContext(sslContext)
188
    .addService(new GreeterImpl())
189
    .build();
190
```
191

192
### Server with Password-Protected Key
193

194
```java
195
SslContext sslContext = GrpcSslContexts.forServer(
196
    new File("server-cert.pem"),
197
    new File("server-key.pem"),
198
    "keyPassword"
199
).build();
200

201
Server server = NettyServerBuilder.forPort(9090)
202
    .sslContext(sslContext)
203
    .addService(new GreeterImpl())
204
    .build();
205
```
206

207
### Server with Client Certificate Authentication
208

209
```java
210
SslContext sslContext = GrpcSslContexts.forServer(
211
    new File("server-cert.pem"),
212
    new File("server-key.pem")
213
)
214
.trustManager(new File("client-ca.pem"))
215
.clientAuth(ClientAuth.REQUIRE)
216
.build();
217

218
Server server = NettyServerBuilder.forPort(9090)
219
    .sslContext(sslContext)
220
    .addService(new GreeterImpl())
221
    .build();
222
```
223

224
### Using Experimental Credentials API
225

226
```java
227
import io.grpc.netty.NettySslContextChannelCredentials;
228
import io.grpc.netty.NettySslContextServerCredentials;
229

230
// Client credentials
231
SslContext clientSslContext = GrpcSslContexts.forClient().build();
232
ChannelCredentials channelCreds = NettySslContextChannelCredentials.create(clientSslContext);
233

234
ManagedChannel channel = Grpc.newChannelBuilder("api.example.com:443", channelCreds)
235
    .build();
236

237
// Server credentials  
238
SslContext serverSslContext = GrpcSslContexts.forServer(
239
    new File("server-cert.pem"),
240
    new File("server-key.pem")
241
).build();
242

243
ServerCredentials serverCreds = NettySslContextServerCredentials.create(serverSslContext);
244

245
Server server = Grpc.newServerBuilderForPort(9090, serverCreds)
246
    .addService(new GreeterImpl())
247
    .build();
248
```
249

250
### Advanced SSL Configuration
251

252
```java
253
import io.netty.handler.ssl.SslProvider;
254
import io.netty.handler.ssl.SupportedCipherSuiteFilter;
255

256
SslContext sslContext = GrpcSslContexts.forClient()
257
    .sslProvider(SslProvider.OPENSSL) // Use OpenSSL for performance
258
    .ciphers(Http2SecurityUtil.CIPHERS, SupportedCipherSuiteFilter.INSTANCE)
259
    .protocols("TLSv1.2", "TLSv1.3")
260
    .build();
261
```
262

263
## OpenSSL vs JDK SSL
264

265
### Using OpenSSL (Recommended for Production)
266

267
```java
268
import io.netty.handler.ssl.OpenSsl;
269
import io.netty.handler.ssl.SslProvider;
270

271
if (OpenSsl.isAvailable()) {
272
    SslContext sslContext = GrpcSslContexts.forClient()
273
        .sslProvider(SslProvider.OPENSSL)
274
        .build();
275
} else {
276
    // Fallback to JDK
277
    SslContext sslContext = GrpcSslContexts.forClient()
278
        .sslProvider(SslProvider.JDK)
279
        .build();
280
}
281
```
282

283
### Benefits of OpenSSL
284
- Better performance
285
- More cipher suites supported
286
- Better memory usage
287
- Hardware acceleration support
288

289
## TLS Session Resumption
290

291
```java
292
import io.netty.handler.ssl.SslSessionCacheSize;
293
import io.netty.handler.ssl.SslSessionTimeout;
294

295
SslContext sslContext = GrpcSslContexts.forServer(
296
    new File("server-cert.pem"),
297
    new File("server-key.pem")
298
)
299
.sessionCacheSize(1000)
300
.sessionTimeout(300) // 5 minutes
301
.build();
302
```
303

304
## ALPN Configuration
305

306
gRPC requires ALPN (Application Layer Protocol Negotiation) for HTTP/2. The `GrpcSslContexts` utility automatically configures ALPN with the correct protocol identifiers:
307

308
- `h2` - HTTP/2 over TLS
309
- `http/1.1` - HTTP/1.1 fallback
310

311
## Common SSL Errors and Solutions
312

313
### ALPN Not Available
314
```
315
javax.net.ssl.SSLException: ALPN is not supported
316
```
317
**Solution:** Use OpenSSL provider or ensure JDK 8u251+ with ALPN support
318

319
### Certificate Verification Failed
320
```
321
javax.net.ssl.SSLHandshakeException: General SSLEngine problem
322
```
323
**Solution:** Verify certificate chain and trust store configuration
324

325
### Protocol Version Mismatch
326
```
327
javax.net.ssl.SSLHandshakeException: No appropriate protocol
328
```
329
**Solution:** Ensure both client and server support compatible TLS versions
330

331
## Security Best Practices
332

333
1. **Use Strong Cipher Suites**: Let gRPC configure appropriate ciphers
334
2. **Certificate Validation**: Always validate server certificates in production
335
3. **TLS 1.2+**: Use TLS 1.2 or 1.3, avoid older versions
336
4. **Regular Certificate Rotation**: Implement certificate renewal processes
337
5. **Mutual TLS**: Use client certificates for additional security when needed