CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-grpc--grpc-netty

Netty-based HTTP/2 transport implementation for gRPC Java providing high-performance network communication

—

Pending
Overview
Eval results
Files

ssl-tls.mddocs/

SSL/TLS Configuration

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

Core Imports

import io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.NettySslContextChannelCredentials;
import io.grpc.netty.NettySslContextServerCredentials;
import io.grpc.netty.NettyChannelCredentials;
import io.grpc.ChannelCredentials;
import io.grpc.ServerCredentials;
import io.netty.handler.ssl.SslContext;
import io.netty.handler.ssl.SslContextBuilder;
import io.netty.handler.ssl.SslProvider;
import java.io.File;
import java.io.InputStream;
import java.security.PrivateKey;
import java.security.Provider;
import java.security.cert.X509Certificate;

GrpcSslContexts

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

Client SSL Context

public static SslContextBuilder forClient();

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

Returns: SslContextBuilder configured for gRPC client use

Server SSL Context

public static SslContextBuilder forServer(File keyCertChainFile, File keyFile);
public static SslContextBuilder forServer(File keyCertChainFile, File keyFile, String keyPassword);
public static SslContextBuilder forServer(InputStream keyCertChain, InputStream key);
public static SslContextBuilder forServer(InputStream keyCertChain, InputStream key, String keyPassword);
public static SslContextBuilder forServer(PrivateKey key, X509Certificate... keyCertChain);
public static SslContextBuilder forServer(PrivateKey key, String keyPassword, X509Certificate... keyCertChain);

Parameters:

  • keyCertChainFile - Certificate chain file in PEM format
  • keyFile - Private key file in PEM format
  • keyPassword - Password for encrypted private keys
  • keyCertChain - Certificate chain input stream
  • key - Private key input stream or object
  • keyCertChain - Certificate chain as X.509 certificates

Returns: SslContextBuilder configured for gRPC server use

SSL Context Configuration

public static SslContextBuilder configure(SslContextBuilder builder);
public static SslContextBuilder configure(SslContextBuilder builder, SslProvider provider);
public static SslContextBuilder configure(SslContextBuilder builder, Provider jdkProvider);

Parameters:

  • builder - Existing SslContextBuilder to configure
  • provider - Specific SSL provider (OPENSSL, JDK)
  • jdkProvider - JDK security provider for SSL implementation

Returns: Configured SslContextBuilder with gRPC-specific settings

Experimental SSL Credentials

NettySslContextChannelCredentials

public static ChannelCredentials create(SslContext sslContext);

Parameters:

  • sslContext - Configured Netty SslContext

Returns: ChannelCredentials for use with channel builders

NettySslContextServerCredentials

public static ServerCredentials create(SslContext sslContext);

Parameters:

  • sslContext - Configured Netty SslContext

Returns: ServerCredentials for use with server builders

NettyChannelCredentials

public static ChannelCredentials create(io.grpc.ChannelCredentials channelCreds);

Parameters:

  • channelCreds - Standard gRPC channel credentials

Returns: Netty-specific ChannelCredentials implementation

NettyServerCredentials

public static ServerCredentials create(io.grpc.ServerCredentials serverCreds);

Parameters:

  • serverCreds - Standard gRPC server credentials

Returns: Netty-specific ServerCredentials implementation

Usage Examples

Basic Client TLS

import io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.NettyChannelBuilder;
import io.netty.handler.ssl.SslContext;

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

ManagedChannel channel = NettyChannelBuilder.forAddress("api.example.com", 443)
    .sslContext(sslContext)
    .build();

Client with Custom Trust Manager

import javax.net.ssl.TrustManagerFactory;
import java.security.KeyStore;

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

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

SslContext sslContext = GrpcSslContexts.forClient()
    .trustManager(trustManagerFactory)
    .build();

ManagedChannel channel = NettyChannelBuilder.forAddress("api.example.com", 443)
    .sslContext(sslContext)
    .build();

Client with Certificate Files

import java.io.File;

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

ManagedChannel channel = NettyChannelBuilder.forAddress("api.example.com", 443)
    .sslContext(sslContext)
    .build();

Basic Server TLS

import io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.NettyServerBuilder;
import java.io.File;

SslContext sslContext = GrpcSslContexts.forServer(
    new File("server-cert.pem"),
    new File("server-key.pem")
).build();

Server server = NettyServerBuilder.forPort(9090)
    .sslContext(sslContext)
    .addService(new GreeterImpl())
    .build();

Server with Password-Protected Key

SslContext sslContext = GrpcSslContexts.forServer(
    new File("server-cert.pem"),
    new File("server-key.pem"),
    "keyPassword"
).build();

Server server = NettyServerBuilder.forPort(9090)
    .sslContext(sslContext)
    .addService(new GreeterImpl())
    .build();

Server with Client Certificate Authentication

SslContext sslContext = GrpcSslContexts.forServer(
    new File("server-cert.pem"),
    new File("server-key.pem")
)
.trustManager(new File("client-ca.pem"))
.clientAuth(ClientAuth.REQUIRE)
.build();

Server server = NettyServerBuilder.forPort(9090)
    .sslContext(sslContext)
    .addService(new GreeterImpl())
    .build();

Using Experimental Credentials API

import io.grpc.netty.NettySslContextChannelCredentials;
import io.grpc.netty.NettySslContextServerCredentials;

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

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

// Server credentials  
SslContext serverSslContext = GrpcSslContexts.forServer(
    new File("server-cert.pem"),
    new File("server-key.pem")
).build();

ServerCredentials serverCreds = NettySslContextServerCredentials.create(serverSslContext);

Server server = Grpc.newServerBuilderForPort(9090, serverCreds)
    .addService(new GreeterImpl())
    .build();

Advanced SSL Configuration

import io.netty.handler.ssl.SslProvider;
import io.netty.handler.ssl.SupportedCipherSuiteFilter;

SslContext sslContext = GrpcSslContexts.forClient()
    .sslProvider(SslProvider.OPENSSL) // Use OpenSSL for performance
    .ciphers(Http2SecurityUtil.CIPHERS, SupportedCipherSuiteFilter.INSTANCE)
    .protocols("TLSv1.2", "TLSv1.3")
    .build();

OpenSSL vs JDK SSL

Using OpenSSL (Recommended for Production)

import io.netty.handler.ssl.OpenSsl;
import io.netty.handler.ssl.SslProvider;

if (OpenSsl.isAvailable()) {
    SslContext sslContext = GrpcSslContexts.forClient()
        .sslProvider(SslProvider.OPENSSL)
        .build();
} else {
    // Fallback to JDK
    SslContext sslContext = GrpcSslContexts.forClient()
        .sslProvider(SslProvider.JDK)
        .build();
}

Benefits of OpenSSL

  • Better performance
  • More cipher suites supported
  • Better memory usage
  • Hardware acceleration support

TLS Session Resumption

import io.netty.handler.ssl.SslSessionCacheSize;
import io.netty.handler.ssl.SslSessionTimeout;

SslContext sslContext = GrpcSslContexts.forServer(
    new File("server-cert.pem"),
    new File("server-key.pem")
)
.sessionCacheSize(1000)
.sessionTimeout(300) // 5 minutes
.build();

ALPN Configuration

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

  • h2 - HTTP/2 over TLS
  • http/1.1 - HTTP/1.1 fallback

Common SSL Errors and Solutions

ALPN Not Available

javax.net.ssl.SSLException: ALPN is not supported

Solution: Use OpenSSL provider or ensure JDK 8u251+ with ALPN support

Certificate Verification Failed

javax.net.ssl.SSLHandshakeException: General SSLEngine problem

Solution: Verify certificate chain and trust store configuration

Protocol Version Mismatch

javax.net.ssl.SSLHandshakeException: No appropriate protocol

Solution: Ensure both client and server support compatible TLS versions

Security Best Practices

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

Install with Tessl CLI

npx tessl i tessl/maven-io-grpc--grpc-netty

docs

client-transport.md

index.md

protocol-negotiation.md

server-transport.md

socket-support.md

ssl-tls.md

tile.json