SSL/TLS

This page explains how to configure SSL/TLS encryption between cluster nodes (both server and client nodes) and thin clients that connect to your cluster.

Considerations

To ensure a sufficient level of security, we recommend that each node (server or client) has its own unique certificate in the node’s keystore (including the private key). This certificate must be trusted by all other server nodes.

Refer to Security Guide: Configuring SSL/TLS/HTTPS, which contains detailed instructions and scripts for generating private key and certificates.

SSL/TLS for Nodes

To enable SSL/TLS for cluster nodes, configure an SSLContext factory in the node configuration. You can use the org.apache.ignite.ssl.SslContextFactory, which is the default factory that uses a configurable keystore to initialize the SSL context.

Below is an example of SslContextFactory configuration:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">

    <property name="sslContextFactory">
        <bean class="org.apache.ignite.ssl.SslContextFactory">
            <property name="keyStoreFilePath" value="keystore/node.jks"/>
            <property name="keyStorePassword" value="123456"/>
            <property name="trustStoreFilePath" value="keystore/trust.jks"/>
            <property name="trustStorePassword" value="123456"/>
            <property name="protocol" value="TLSv1.3"/>
        </bean>
    </property>

</bean>

IgniteConfiguration igniteCfg = new IgniteConfiguration();

SslContextFactory factory = new SslContextFactory();

factory.setKeyStoreFilePath("keystore/node.jks");
factory.setKeyStorePassword("123456".toCharArray());
factory.setTrustStoreFilePath("keystore/trust.jks");
factory.setTrustStorePassword("123456".toCharArray());
factory.setProtocol("TLSv1.3");

igniteCfg.setSslContextFactory(factory);

var cfg = new IgniteConfiguration
{
    SslContextFactory = new SslContextFactory
    {
        KeyStoreFilePath = "server.jks",
        KeyStorePassword = "123",
        TrustStoreFilePath = "trust.jks",
        TrustStorePassword = "345"
    }
};

Ignition.Start(cfg);

This API is not presently available for C++. You can use XML configuration.

The keystore must contain the node’s certificate, including its private key. The trust store must contain the trusted certificates for all other cluster nodes.

You can define other properties, such as key algorithm, key store type, or trust manager. See the description of the properties in the SslContextFactory Properties section.

After starting the node, you should see the following messages in the logs:

Security status [authentication=off, tls/ssl=on]

SSL/TLS for Thin Clients and JDBC/ODBC

GridGain uses the same SSL/TLS properties for all clients, including thin clients and JDBC/ODBC connections. The properties are configured within the client connector configuration. The client connector configuration is defined via the IgniteConfiguration.clientConnectorConfiguration property.

To enable SSL/TLS for client connections, set the sslEnabled property to true and provide an SslContextFactory in the client connector configuration. You can re-use the SSLContextFactory configured for nodes, or you can configure an SSLContext factory that will be used for client connections only.

Then, configure SSL on the client side in the same way. Refer to the specific client documentation for details.

Here is an example configuration that sets SslContextFactory for client connection:

<property name="clientConnectorConfiguration">
    <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
        <property name="sslEnabled" value="true"/>
        <property name="useIgniteSslContextFactory" value="false"/>
        <property name="sslContextFactory">
            <bean class="org.apache.ignite.ssl.SslContextFactory">
                <property name="keyStoreFilePath" value="/path/to/server.jks"/>
                <property name="keyStorePassword" value="123456"/>
                <property name="trustStoreFilePath" value="/path/to/trust.jks"/>
                <property name="trustStorePassword" value="123456"/>
            </bean>
        </property>
    </bean>
</property>

IgniteConfiguration igniteCfg = new IgniteConfiguration();

ClientConnectorConfiguration clientCfg = new ClientConnectorConfiguration();
clientCfg.setSslEnabled(true);
clientCfg.setUseIgniteSslContextFactory(false);
SslContextFactory sslContextFactory = new SslContextFactory();
sslContextFactory.setKeyStoreFilePath("/path/to/server.jks");
sslContextFactory.setKeyStorePassword("123456".toCharArray());

sslContextFactory.setTrustStoreFilePath("/path/to/trust.jks");
sslContextFactory.setTrustStorePassword("123456".toCharArray());

clientCfg.setSslContextFactory(sslContextFactory);

igniteCfg.setClientConnectorConfiguration(clientCfg);

var cfg = new IgniteClientConfiguration
{
    Endpoints = new[] {"127.0.0.1:10800"},
    SslStreamFactory = new SslStreamFactory
    {
        CertificatePath = ".../certs/client.pfx",
        CertificatePassword = "password",
    }
};
using (var client = Ignition.StartClient(cfg))
{
    //...
}

This API is not presently available for C++. You can use XML configuration.

If you want to re-use the SSLContext factory configured for nodes, you only need to set the sslEnabled property to true, and ClientConnectorConfiguration will look for the SSLContext configured in IgniteConfiguration:

<property name="clientConnectorConfiguration">
    <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
        <property name="sslEnabled" value="true"/>
    </bean>
</property>

ClientConnectorConfiguration clientConnectionCfg = new ClientConnectorConfiguration();
clientConnectionCfg.setSslEnabled(true);

This API is not presently available for C#/.NET. You can use XML configuration.

This API is not presently available for C++. You can use XML configuration.

Configuring Client SSL/TLS Authentication

In most cases, it is sufficient to only have SSL/TLS certificates on the server nodes. However, sometimes security policies require client certificates validation (also reffered to as "client SSL/TLS authentication", "mutual authentication", or "two-way SSL") to be enabled. This behavior can be configured for all types of GridGain clients.

Thick Clients SSL/TLS Authentication

By default, thick clients have certificate validation enabled.

To disable it, set SslContextFactory.needClientAuth=false on the server nodes.

Thin Clients SSL/TLS Authentication

By default, thin clients are not required to have client certificates.

To enable client certificate validation, set ClientConnectorConfiguration.sslClientAuth=true on the server nodes.

Management Tools SSL/TLS Authentication

By default, management scripts such as control.sh|bat, management.sh|bat, and snapshot-utility.sh|bat are not required to have client certificates.

To enable client certificate validation, set ConnectorConfiguration.sslClientAuth=true on the server nodes.

REST SSL/TLS Authentication

By default, REST does not require client certificate validation. This behavior is controlled by the Jetty configuration.

To enable client certificate validation, use the following Jetty SslContextFactory configuration on the server nodes:

    <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
        <Set name="keyStorePath">server.jks</Set>
        <Set name="keyStorePassword">123456</Set>
        <Set name="trustStorePath">trust.jks</Set>
        <Set name="trustStorePassword">123456</Set>
        <Set name="needClientAuth">true</Set>
    </New>

Disabling Certificate Validation Completely

In some cases, it is useful to disable certificate validation, for example when connecting to a server with a self-signed certificate. This can be achieved by using a disabled trust manager, which can be obtained by calling the SslContextFactory.getDisabledTrustManager() method.

<bean class="org.apache.ignite.configuration.IgniteConfiguration">

    <property name="sslContextFactory">
        <bean class="org.apache.ignite.ssl.SslContextFactory">
            <property name="keyStoreFilePath" value="keystore/node.jks"/>
            <property name="keyStorePassword" value="123456"/>
            <property name="trustManagers">
                <bean class="org.apache.ignite.ssl.SslContextFactory" factory-method="getDisabledTrustManager"/>
            </property>
        </bean>
    </property>

</bean>

IgniteConfiguration igniteCfg = new IgniteConfiguration();

SslContextFactory factory = new SslContextFactory();

factory.setKeyStoreFilePath("keystore/node.jks");
factory.setKeyStorePassword("123456".toCharArray());
factory.setTrustManagers(SslContextFactory.getDisabledTrustManager());

igniteCfg.setSslContextFactory(factory);

Note that there is a difference between using SslContextFactory.getDisabledTrustManager() and disabling client authentication. With SslContextFactory.getDisabledTrustManager(), all nodes are still required to have a certificate but its validity will not be checked. If client authentication is disabled, clients are not required to have certificates at all.

Upgrading Certificates

If your SSL certificates are about to expire or have been compromised, you can install new certificates without shutting down the whole cluster.

The following is a procedure for updating certificate.

Trusted Certificate

If the new certificate is trusted by all cluster nodes, you can import the new certificate (including the private key) to the key store of the corresponding node and remove the old certificate. Then, gracefully restart the node. Repeat this procedure for all certificates you want to update.

Untrusted Certificate

This approach is required if a new certificate is issued by the same certificate authority, but may or may not be trusted.

Repeat the following procedure for the nodes where the certificate is not trusted:

Import the new certificate to the trusted store of the node.
Gracefully restart the node.
Repeat these steps for all server nodes.

Certificate from a New Certificate Authority

If the certificate is issues from a different certificate authority (CA) than the previous one, rolling restart is not possible for the cluster, as the running cluster cannot have certificates from different authorities active at the same time.

To change the certificate in this case:

Deactivate the cluster.
Shut down the cluster nodes.
Update certificate on all nodes in the cluster.
Restart the nodes and reactivate the cluster.

SslContextFactory Properties

SslContextFactory supports the following properties:

Property Description Default

Property	Description	Default
`keyAlgorithm`	The key manager algorithm that will be used to create a key manager.	`SunX509`
`keyStoreFilePath`	The path to the key store file. This is a mandatory parameter since the SSL context can not be initialized without a key manager.	`N/A`
`keyStorePassword`	The key store password.	`N/A`
`keyStoreType`	The key store type.	`JKS`
`needClientAuth`	Whether the connecting clients are required to have a trusted SSL/TLS certificate.	`true`
`protocol`	The protocol for secure transport. Supported algorithms.	`TLS`
`trustStoreFilePath`	The path to the trust store file.	`N/A`
`trustStorePassword`	The trust store password.	`N/A`
`trustStoreType`	The trust store type.	`JKS`
`trustManagers`	A list of pre-configured trust managers.	`N/A`

keyAlgorithm

The key manager algorithm that will be used to create a key manager.

SunX509

keyStoreFilePath

The path to the key store file. This is a mandatory parameter since the SSL context can not be initialized without a key manager.

N/A

keyStorePassword

The key store password.

N/A

keyStoreType

The key store type.

JKS

needClientAuth

Whether the connecting clients are required to have a trusted SSL/TLS certificate.

true

protocol

The protocol for secure transport. Supported algorithms.

TLS

trustStoreFilePath

The path to the trust store file.

N/A

trustStorePassword

The trust store password.

N/A

trustStoreType

The trust store type.

JKS

trustManagers

A list of pre-configured trust managers.

N/A

© 2024 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Apr 25, 2024