TLS/SSL
This page describes the TLS/SSL security features of Hazelcast .NET client, for connections between members and between clients and members, and mutual authentication. These security features require Hazelcast IMDG Enterprise edition.
One of the offers of Hazelcast is the TLS/SSL protocol which you can use to establish an encrypted communication across your cluster with key stores and trust stores.
- A Java
keyStore
is a file that includes a private key and a public certificate. - A Java
trustStore
is a file that includes a list of certificates trusted by your application which is named as "certificate authority".
You should set keyStore
and trustStore
before starting the members. See the next section on setting keyStore
and trustStore
on the server side.
TLS/SSL for Hazelcast Members
Hazelcast allows you to encrypt socket level communication between Hazelcast members and between Hazelcast clients and members, for end to end encryption. To use it, see the TLS/SSL for Hazelcast Members section.
TLS/SSL for Hazelcast .NET Clients
TLS/SSL for the Hazelcast .NET client can be configured using the SslOptions
class. Let's first give an example of a sample configuration and then go over the configuration options one by one:
var hazelcastOptions = new HazelcastOptionsBuilder().Build();
var sslOptions = hazelcastOptions.Networking.Ssl;
sslOptions.Enabled = true;
sslOptions.ValidateCertificateChain = true;
sslOptions.ValidateCertificateName = false;
sslOptions.CheckCertificateRevocation = false;
sslOptions.CertificateName = "CN or SAN of server certificate";
sslOptions.CertificatePath = "client pfx file path";
sslOptions.CertificatePassword = "client pfx password";
sslOptions.SslProtocol = SslProtocols.Tls12;
Of course these can also be configured via command-line options or environment variables, or via the Hazelcast configuration file. See the configuration page for details.
Enabling TLS/SSL
TLS/SSL for the Hazelcast .NET client can be enabled/disabled using the Enabled
option. When this option is set to true
, TLS/SSL will be configured with respect to the other SslOptions
options. Setting this option to false
will result in discarding other SslOptions
properties.
Default value is false
(disabled).
Certificate Chain validation
Remote SSL certificate chain validation can be enabled/disabled using the SslOptions.ValidateCertificateChain
option. It is enabled by default. If you need to bypass certificate validation for some reason, you can disable it by setting the value to false
.
Validation is done by .NET and delegated to OS, and you need to make sure your server certificate is trusted by your OS. Please refer to this blog for information on how to configure your OS to trust your server certificates.
Certificate Name Validation
Server certificate CN or SAN field can be validated against a value you set into configuration. This option is disabled by default. You can enable it by setting SslOptions.ValidateCertificateName
to true
and providing a name with SslOptions.CertificateName
.
TLS/SSL Protocol
You can configure the TLS/SSL protocol using the SslOptions.Protocol
option. Valid options are values of the System.Security.Authentication.SslProtocols
enum. Depending on your .NET version, below values are valid:
- None : Allows the operating system to choose the best protocol to use.
- Ssl2 : SSL 2.0 Protocol. RFC 6176 prohibits the usage of SSL 2.0.
- Ssl3 : SSL 3.0 Protocol. RFC 7568 prohibits the usage of SSL 3.0.
- Tls : TLS 1.0 Protocol described in RFC 2246. deprecated.
- Tls11 : TLS 1.1 Protocol described in RFC 4346. deprecated.
- Tls12 : TLS 1.2 Protocol described in RFC 5246. recommended.
Mutual Authentication
As explained above, Hazelcast members have key stores used to identify themselves (to other members) and Hazelcast clients have trust stores used to define which members they can trust.
Using mutual authentication, the clients also have their key stores and members have their trust stores so that the members can know which clients they can trust.
To enable mutual authentication, firstly, you need to set the following property on the server side in the hazelcast.xml
file:
<network>
<ssl enabled="true">
<properties>
<property name="javax.net.ssl.mutualAuthentication">REQUIRED</property>
</properties>
</ssl>
</network>
You can see the details of setting mutual authentication on the server side in the Mutual Authentication section of the Hazelcast IMDG Reference Manual.
On the client side, you have to provide the client certificate and its password if there is one. Here is how you do it:
sslOptions.CertificatePath = "client pfx file path";
sslOptions.CertificatePassword = "client pfx password";
The provided certificate file should be a PFX file that has private and public keys. The file path should be set with SslOptions.CertificatePath
.
If you choose to set a password to it, you need to provide it to the configuration using the SslOptions.CertificatePassword
option.