Edit

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.

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.

Caution

Ensure that your version of the JVM addresses the following issue that can cause deadlocks in SSL connections. If your JVM is affected but can’t be updated, then set the TcpDiscoverySpi.soLinger parameter to a non-negative value.

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);

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

Ignite 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.

Disabling Certificate Validation

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);

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.

First of all, make sure the new certificates are trusted by all cluster nodes. This step may not be necessary if your trusted stores contain the root certificate and the new certificates are signed by the same CA.
Repeat the following procedure for the nodes where the certificate is not trusted:
1. Import the new certificate to the trusted store of the node.
2. Gracefully restart the node.
3. Repeat these steps for all server nodes.
Now all nodes trust the new certificates.
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.

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`
`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

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 The Apache Software Foundation.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.