Configure SSL/TLS Encryption in Windows and Linux

TLS delivers network security with a lower performance overhead than NCache Data Encryption. It is essential for NCache activities that require data sharing between servers and clients, different servers, caches, and bridges. You can use TLS selectively to secure specific data transfers based on your needs. Read more about how it works, here. Understanding these considerations will ensure your deployment of NCache TLS encryption goes smoothly.

Note

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

How to Configure TLS Encryption

NCache has two primary locations on both server and client machines from where it can retrieve the authentication certificate: the Personal store and the Trusted Root (TR) store. Certificates placed in the Personal store are accessible by all users on the local machine, while those in the user store are only accessible by the specific user, and NCache can only access it if it is running with that particular user. There are four specific stores from which NCache can retrieve the authentication certificate:

  • Trusted Root: Local Machine
  • Trusted Root: Current User
  • Personal: Local Machine
  • Personal: Current User
Note

Place the authentication certificate at machine level to avoid any access restrictions.

Note

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

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

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: Login to your machine.
Step-2: Create (you can create a self-signed certificate as detailed here) 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 your certificate to the appropriate machine as detailed here.
Step-4: Press Win + R, type mmc, and press Enter.


Step-5: 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.


Step-6: 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.


Step-7: 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.


Step-8: 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.


Step-9: 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.


Step-10: Make sure that the NCache Service is running under the same user that was used to import the certificate.
Step-11: Use the following PowerShell Cmdlet to enable TLS security. To learn more about the properties used here, refer to the certificate elements discussed below. When executing the Enable NCacheTLS command, make sure to specify the respective certificate name and thumbprint for the client and server that were saved in Steps 8 and 9.

Enable-NCacheTLS -Node "20.200.20.39,20.200.20.40" -ServerCertificateCN "MyCert" -ServerCertificateThumbprint "1234567890ABCDEF" -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 Packages 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>
    <use-mutual-tls-for-client-to-server>false</use-mutual-tls-for-client-to-server>
    <protocol-version>protocol-version</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: 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.

Considerations for Certificate Placement

When the Java client is running on a Windows machine, an important consideration arises with regard to certificate management. Specifically, Java does not natively support the use of local machine certificates; rather, it retrieves certificates from the current user. This means that if the client is configured for mutual TLS, both the client's certificate and the associated issuer's certificate must be present in the current user's certificate store. In the scenario where mutual TLS is disabled, the requirement changes. In this case, only the certificate issued by the Certificate Authority (CA) needs to be present in the current user's certificate store.

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.

Important

For Windows, if you have a bundled 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.

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