Configure SSL/TLS Encryption in Windows and Linux

You should configure SSL/TLS encryption when you want to protect communication between NCache servers and clients, especially in production or distributed setups where data security matters. The process starts by creating or obtaining a TLS certificate and placing it in the correct certificate store. After that, you simply note the certificate name and thumbprint, enable TLS using the provided command or configuration file, make sure all servers and clients use the same settings, and then restart the NCache services to apply the changes securely.

Note

Make sure the cache and client processes are stopped before proceeding with the following.

Considerations for Certificate Placement

The following are the considerations for certificate placement for both Windows and Linux:

If you have a test certificate (that contains the root and intermediate certificates), then you need to add the certificate in both, the Personal and the Trusted Root of the local machine. If you have a separate Trusted Root and Personal certificate, then you need to add them individually i.e., the Personal certificate to the Personal store and the CA root certificate to the Trusted Root store. The client requires a client certificate, while the server needs only a server certificate. The server does not require a client certificate, but the client's issuer must be in the Trusted Root. Similarly, the client must have the server's issuer in its Trusted Root.

Note

NCache will utilize the certificates stored in the certificate stores automatically. When started under the correct user account, the NCache Service will automatically identify and use the relevant certificates from the appropriate certificate stores.

Note

You don’t need to install client certificate on Bridge and Server nodes if you don’t want to run client from them.

Note

From 5.3 SP5 onwards, clients and servers can have different certificates.

How to Configure TLS Encryption

Server's Selection of Certificate

When the server starts, it begins reading the certificate with its thumbprint stored in the registry. It systematically checks the certificate in the four aforementioned stores: Trusted Root (TR) of both Local Machine and Current User, followed by Personal of both Local Machine and Current User. The server selects the first certificate it finds in this order. Subsequently, the server reads this chosen certificate through its thumbprint and shares it with the client, facilitating secure communication.

Client's Selection of Certificate

This process ensures that the server obtains the appropriate certificate for authentication from the available stores during startup. Similarly, the client follows the same process to select and share its certificate with the server for authentication.

Mutual TLS Authentication

In the case of mutual TLS, the client must also share its certificate with the server. For the server to accept the client’s certificate, it must trust the client’s certificate issuer, which is stored in the server's Trusted Root Certificate Authority store.

To configure TLS Encryption, please see below.

The steps below should be followed in order to install the TLS certificate on a Windows machine.

Step 1 - Machine Login: Login to your machine.
Step 2 - Create a Self-signed Certificate: Create (you can create a self-signed certificate as detailed in Microsoft WCF certificate documentation) or obtain a TLS certificate that includes an exportable private key.

Important
  • Your certificate must be authorized by a Certificate Authority (CA). To reflect this as part of your configurations, please ensure that the Basic Constraints section specifies Subject Type=CA in the Certificate Details. Similarly, you can achieve this through the -TextExtension attribute with the value @("2.5.29.19={text}CA=true") when generating a certificate using the following command: New-SelfSignedCertificate.
  • We do not recommend using self-generated certificates in your production environments. Although, you can use them in your testing environments.

Step 3 - Import Certificate: Import your certificate to the appropriate machine as detailed in Microsoft certificate installation guide.

Step 4 - Open Microsoft Management Console: Press Win + R, type mmc, and press Enter.

Microsoft Management Console (MMC) window showing the Add/Remove Snap-ins dialog

Step 5 - Select Certificate: In Microsoft Management Console (MMC), in the File menu, click Add or Remove Snap-ins. Select Certificates from the list of available snap-ins and click the Add button.

select Certificate from list of available Snap-ins

Step 6 - Choose Account: Choose the account type from the My user account, Service account, and Computer account. You can choose a My user account or local machine based on where you place your certificate.

Choose the account type from the My user account, Service account, and Computer account

Step 7 - Locate the Certificate: In the left pane of MMC, expand Certificates and navigate Current User > Personal > Certificates to locate the TLS certificate that lists Client Authentication as an Intended Purpose and double-click. To learn about the certificate placement, refer to Considerations for Certificate Placement.

Locate the TLS certificate that lists Client Authentication as an Intended Purpose

Step 8 - Get the Thumbprint: In the Certificate Dialog Box, click the Details tab and locate Thumbprint. Click on it and copy the hexadecimal characters from the box. Remove any colons (':') or extra spaces in the certificate thumbprint, if there are any. Save the thumbprint as it will be required in the proceeding steps.

Getting Thumbprint

Step 9 - Copy the Certificate Name: Similarly, copy Certificate Name (CN) by clicking on the Subject property and copying only what comes after CN = in this case "Example". Save the certificate name as it will be required in the proceeding steps.

Copy and save certificate name present after CN

Step 10 - Verify that the Service is Running: Make sure that the NCache Service is running under the same user that was used to import the certificate.
Step 11 - Enable TLS Security: Use the following PowerShell Cmdlet to enable TLS security. When executing the Enable NCacheTLS command, make sure to specify the certificate name and thumbprint for the server that were saved in Steps 8 and 9. Similarly, you can add the client certificate by following the above-mentioned steps.

Enable-NCacheTLS -Node "20.200.20.39,20.200.20.40" -ServerCertificateCN "Example" -ServerCertificateThumbprint "596846ab6bdd9edb03cdfbdfa1aa7b0b05e744a6" -ClientCertificateCN "MyClientCert" -ClientCertificateThumbprint "1234567890EFGHIJKL" -ServerToServerCommunication -ClientServerCommunication -UseMutualTLSForClientToServer True
  • The above command will only work if you have NCache installed on your client machine. If otherwise, then you must manually enable TLS using the tls.ncconf file available via the NCache NuGet Package in Windows, as follows:
Note

If the ProtocolVersion parameter is not provided in the above command, the default protocol used is TLS 1.2.

<tls-info>
 <server-certificate-cn>certificate-name</server-certificate-cn> 
 <server-certificate-thumbprint>your-thumbprint</server-certificate-thumbprint>
 <client-certificate-cn>certificate-name</client-certificate-cn>
 <client-certificate-thumbprint>your-thumbprint</client-certificate-thumbprint>
 <enable>false</enable>
 <enable-client-server-tls>false</enable-client-server-tls>
 <enable-bridge-tls>false</enable-bridge-tls>
    <enable-server-to-server-tls>false</enable-server-to-server-tls>
 <use-mutual-tls-for-client-to-server>false</use-mutual-tls-for-client-to-server>
 <use-mutual-tls-for-server-to-server>false</use-mutual-tls-for-server-to-server>
    <protocol-version>tls12</protocol-version>
</tls-info>
Important

Make sure that the configuration values are consistent on all server and client nodes to ensure connectivity and homogeneity of the cluster.

Step 12 - Restart the Services & Processes: Once the desired properties are set, restart the cache, client processes, and NCache Service. Make sure that the NCache Service is running under the same user that was used to import the certificate.

Note

Once the certificates have been enabled, make sure that:

  • The NCache Service is running under the same user that was used to import the certificate.
  • All client applications run on 64-bit machines.

Verify Successful Client Connectivity Through TLS

In order to verify successful client connectivity through TLS, you can run the Test Stress cmdlet using the PowerShell. The following example runs Test Stress on the cache named demoCache.

Test-Stress -CacheName demoCache

You can also verify this using the Microsoft Network Monitor. In case TLS is enabled, the Protocol Name of the process PowerShell on running this command will be TLS.

Note

UseMutualTLSForClientToServer, EnableBridgeTLS, EnableClientServerTLS, EnableServerToServerTLS, and UseMutualTLSServerToServer will not work if Enable hasn't been set as true in your tls.ncconf, regardless of whether they have individually been enabled.

Troubleshooting

Client connectivity through TLS can fail due to the following reasons:

  • If the registry entries are missing, the connectivity might fail. Make sure that all the entries are made in the registry.
  • If the NCache Service has different user credentials than the user that was used to import the certificate, it will be invalid if the thumbprint value provided to the CertificateThumbprint property is incorrect.
  • If the Trusted Root of the client does not have the CA of the server.
  • If UseMutualTLSForClientToServer or UseMutualTLSForServerToServer are true and the Trusted Root of the server does not have the CA of the client or the other server.
  • If the values of the properties are not the same in the client and server machine, you receive an error saying "Decryption Operation Failed".

See Also

Configure Security for Cache
Configure Encryption for Cache