CtrlK
BlogDocsLog inGet started
Tessl Logo

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

A shaded version of the Netty transport for gRPC-Java that includes relocated Netty dependencies to avoid version conflicts

—

Pending
Overview
Eval results
Files

ssl-tls.mddocs/

SSL/TLS Configuration

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.

Capabilities

GrpcSslContexts Utility

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

/**
 * Create an SSL context builder for gRPC clients
 * @return SslContextBuilder configured for client use
 */
public static SslContextBuilder forClient();

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

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

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

/**
 * Create an SSL context builder for gRPC servers from streams with password
 * @param keyCertChain Certificate chain input stream
 * @param key Private key input stream
 * @param keyPassword Password for the private key
 * @return SslContextBuilder configured for server use
 */
public static SslContextBuilder forServer(InputStream keyCertChain, InputStream key, String keyPassword);

Usage Examples:

import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.shaded.io.netty.handler.ssl.SslContext;
import java.io.File;

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

// Server SSL context
SslContext serverSslContext = GrpcSslContexts.forServer(
        new File("server.crt"),
        new File("server.key")
    )
    .build();

// Server with password-protected key
SslContext secureServerContext = GrpcSslContexts.forServer(
        new File("server.crt"),
        new File("server.key"),
        "keyPassword"
    )
    .build();

SSL Context Configuration

Configure SSL context builders with gRPC-specific optimizations.

/**
 * Configure an SSL context builder for gRPC usage
 * @param builder The SslContextBuilder to configure
 * @return Configured SslContextBuilder
 */
public static SslContextBuilder configure(SslContextBuilder builder);

/**
 * Configure an SSL context builder with specific SSL provider
 * @param builder The SslContextBuilder to configure
 * @param provider The SSL provider to use
 * @return Configured SslContextBuilder
 */
@ExperimentalApi
public static SslContextBuilder configure(SslContextBuilder builder, SslProvider provider);

/**
 * Configure an SSL context builder with JDK provider
 * @param builder The SslContextBuilder to configure
 * @param jdkProvider The JDK security provider
 * @return Configured SslContextBuilder
 */
public static SslContextBuilder configure(SslContextBuilder builder, Provider jdkProvider);

Usage Example:

import io.grpc.netty.shaded.io.netty.handler.ssl.SslProvider;
import io.grpc.netty.shaded.io.netty.handler.ssl.SslContextBuilder;

// Configure with OpenSSL provider
SslContext sslContext = GrpcSslContexts.configure(
        SslContextBuilder.forClient(),
        SslProvider.OPENSSL
    )
    .trustManager(new File("ca.crt"))
    .build();

Channel Credentials

Create channel credentials from Netty SSL contexts for client connections.

/**
 * Create channel credentials from an SSL context
 * @param sslContext The Netty SSL context
 * @return ChannelCredentials for use with channel builders
 */
public static ChannelCredentials create(SslContext sslContext);

Usage Example:

import io.grpc.netty.shaded.io.grpc.netty.NettySslContextChannelCredentials;
import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
import io.grpc.ChannelCredentials;

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

ChannelCredentials credentials = NettySslContextChannelCredentials.create(sslContext);

ManagedChannel channel = NettyChannelBuilder
    .forAddress("secure-service.example.com", 443)
    .build();

Server Credentials

Create server credentials from Netty SSL contexts for server configuration.

/**
 * Create server credentials from an SSL context
 * @param sslContext The Netty SSL context
 * @return ServerCredentials for use with server builders
 */
public static ServerCredentials create(SslContext sslContext);

Usage Example:

import io.grpc.netty.shaded.io.grpc.netty.NettySslContextServerCredentials;
import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
import io.grpc.ServerCredentials;

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

ServerCredentials credentials = NettySslContextServerCredentials.create(sslContext);

Server server = NettyServerBuilder
    .forPort(9090, credentials)
    .addService(new MyServiceImpl())
    .build();

Insecure HTTP/1.1 Upgrade Credentials

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

/**
 * Create insecure credentials for HTTP/1.1 upgrade
 * @return ChannelCredentials for HTTP/1.1 to HTTP/2 upgrade
 */
public static ChannelCredentials create();

Usage Example:

import io.grpc.netty.shaded.io.grpc.netty.InsecureFromHttp1ChannelCredentials;

ChannelCredentials upgradeCredentials = InsecureFromHttp1ChannelCredentials.create();

ManagedChannel channel = NettyChannelBuilder
    .forAddress("localhost", 8080, upgradeCredentials)
    .build();

Advanced SSL Configuration Examples

Mutual TLS (mTLS) Client

import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.shaded.io.grpc.netty.NettySslContextChannelCredentials;
import io.grpc.netty.shaded.io.netty.handler.ssl.SslContext;

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

ChannelCredentials credentials = NettySslContextChannelCredentials.create(clientSslContext);

ManagedChannel channel = NettyChannelBuilder
    .forAddress("secure-service.example.com", 443, credentials)
    .build();

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 tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(trustStore);

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

OpenSSL with ALPN

import io.grpc.netty.shaded.io.netty.handler.ssl.SslProvider;
import io.grpc.netty.shaded.io.netty.handler.ssl.ApplicationProtocolConfig;

SslContext sslContext = GrpcSslContexts.configure(
        SslContextBuilder.forClient(),
        SslProvider.OPENSSL
    )
    .trustManager(new File("ca.crt"))
    .applicationProtocolConfig(ApplicationProtocolConfig.ALPN)
    .build();

Protocol Negotiation Types

The NegotiationType enum defines different approaches to protocol negotiation:

public enum NegotiationType {
    /**
     * TLS ALPN/NPN negotiation for SSL connections.
     * Assumes an SSL connection and uses ALPN or NPN to negotiate HTTP/2.
     */
    TLS,

    /**
     * HTTP UPGRADE from HTTP/1.1 to HTTP/2.
     * Uses HTTP/1.1 upgrade mechanism to transition to HTTP/2 over plaintext.
     */
    PLAINTEXT_UPGRADE,

    /**
     * Direct HTTP/2 plaintext connection.
     * Assumes the remote endpoint supports HTTP/2 directly without negotiation.
     */
    PLAINTEXT
}

Usage Example:

import io.grpc.netty.shaded.io.grpc.netty.NegotiationType;

NettyChannelBuilder builder = NettyChannelBuilder
    .forAddress("localhost", 9090)
    .negotiationType(NegotiationType.PLAINTEXT_UPGRADE);

Error Handling

Common SSL/TLS related exceptions:

  • SSLException - General SSL configuration or handshake errors
  • CertificateException - Certificate validation or parsing errors
  • NoSuchAlgorithmException - Unsupported cryptographic algorithms
  • KeyStoreException - Key store loading or access errors

Always handle these exceptions appropriately in production code:

try {
    SslContext sslContext = GrpcSslContexts.forClient()
        .trustManager(new File("ca.crt"))
        .build();
} catch (SSLException e) {
    logger.error("Failed to create SSL context", e);
    // Handle SSL configuration error
}

Install with Tessl CLI

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

docs

channel-building.md

index.md

server-building.md

ssl-tls.md

transport-providers.md

tile.json