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.

Note

The following TLS configuration will only work for 5.3 SP2 and above.

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.

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.

To configure TLS Encryption, please see below.

Windows
Linux

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 MMC, in the File menu, click Add/Remove Snap-in. 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, should there be 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 CertificateName and CertificateThumbprint that you saved in Steps 8 and 9.

Enable-NCacheTLS -Node "20.200.20.39,20.200.20.40" -CertificateName "Example" -CertificateThumbprint "596846ab6bdd9edb03cdfbdfa1aa7b0b05e744a6" -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:

<tls-info>
    <certificate-name>certificate-name</certificate-name>
    <certificate-thumbprint>your-thumbprint</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>
</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.

The steps below should be followed in order to install the TLS certificate on a Linux machine. Keep in mind that the following steps are performed using Ubuntu and may vary if you use Fedora, Red Hat, etc.

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.
You can do this by running the following command to create a self-signed certificate using OpenSSL:

openssl req -new -x509 -days 365 -keyout ncachetest-private-key.pem -out ncachetest-certificate.crt

This will create two files: ncachetest-private-key.pem (private key) and ncachetest-certificate.crt (certificate).

Important

We do not recommend using self-generated certificates in your production environments. Although, you can use them in your testing environments.

Step-3: To use TLS in NCache, you need a .pfx file. If you already have a .crt and .pem file, here is how you can create the pfx file:

openssl pkcs12 -export -out ncachetest-certificate.pfx -inkey ncachetest-private-key.pem -in ncachetest-certificate.crt

Step-4: Get the Thumbprint/Fingerprint and Certificate Name by running the following command and remove any colons (':') or extra spaces in the certificate thumbprint, should there be any. Save both the certificate name and thumbprint as they will be required in the proceeding steps.

openssl x509 -noout -in ncachetest-certificate.crt -fingerprint -subject | sed 's/://g'

Step-5: Additionally, if UseMutualTLSForClientToServer or UseMutualTLSForServerToServer has been enabled, the certificate must also be installed on the server machines. To do so, proceed with the following:

Create a directory to store the certificates that need to be applied system-wide. For example:

sudo mkdir -p /usr/local/share/ca-certificates/

Copy the certificates to this newly created directory.

sudo cp ncachetest-certificate.crt /usr/local/share/ca-certificates/

Update the System's Certificate Store through the following command:

sudo update-ca-certificates

Step-6: Now, to use the certificate with NCache, you must run the following command as ncache user. Since, the install-pfxcertificate command simply deploys the given certificate to personal store of current user.

/opt/ncache/bin/tools/install-pfxcertificate -filepath "/home/ncache/ncachetest-certificate.pfx" -password "YourPassword"

Step-7: Use the following Command Line 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 certificatename and certificatethumbprint that you saved in Step 4.

enable-ncachetls -node "20.200.20.39,20.200.20.40" -certificatename "certificate-name" -certificatethumbprint "596846ab6bdd9edb03cdfbdfa1aa7b0b05e744a6" -clientservercommunication -usemutualtlsforclienttoserver true -pfxpath /home/ncache/ncachetest-certificate.pfx -pfxpassword YourPassword

The above command is installed with NCache and is unavailable otherwise. If your client machine does not have NCache installed, and you want to run this command, you will need to manually enable TLS using the tls.ncconf file available via the NCache NuGet Packages and Maven Packages.
However, if you are using the Java application from this machine, it will be necessary to add the pfx-path and pfx-password. These parameters help set PFX file path and PFX file password in TLS configuration file. For .NET Clients, pfx path is automatically set without manual intervention, but for Java Clients, you can also provide the pfx path and pfx password in the above command. The configuration is as follows:

<tls-info>
    <certificate-name>certificate-name</certificate-name>
    <certificate-thumbprint>your-thumbprint</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>

    <!-- Following two parameters are required if you're running Java application from this machine. -->
    <pfx-path>/home/ncache/ncachetest-certificate.pfx</pfx-path>
    <pfx-password>YourPassword</pfx-password>
</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-8: 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 Authority (CA) certificate 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.

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.

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.

Windows
Linux

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 Test-Stress will be TLS.

test-stress -cachename demoCache

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.

Certificate Elements

To employ any one of the configurations mentioned, TLS certificates can be granted by Certificate Authorities (CA's) or self-signed by users, ensuring encrypted data transport. These certificates will usually contain the following information:

Windows
Linux

Parameters	Data Types	Description	Default Value
`-CertificateName*`	`<String>`	The CertificateName parameter specifies the name of the TLS certificate to be used for encryption. It provides the unique name associated with the desired TLS certificate for secure communication.	-
`-CertificateThumbprint*`	`<String>`	Specifies the unique thumbprint of the TLS certificate to ensure its authenticity and integrity. It provides the fingerprint value associated with the desired TLS certificate for secure communication.	-
`-ClientServerCommunication`	`<SwitchParameter>`	Enables TLS encryption for communication between client and server nodes.	False
`-ServerToServerCommunication`	`<SwitchParameter>`	Enables TLS encryption for communication between server nodes within a cluster.	False
`-BridgeCommunication`	`<SwitchParameter>`	Enables TLS encryption solely for communication between NCache bridge and geographically separate caches. If the user wants to extend this security to encompass communication between the bridge nodes as well, they should use the `ServerToServerCommunication` flag. If `BridgeCommunication` is true, make sure to enable `ClientServerCommunication`. Currently, NCache requires you to use the same certificate on both bridge nodes.	False
`-UseMutualTLSForClientToServer`	`<String>`	Enforces the requirement for a valid client TLS certificate. When enabled, client nodes connecting to the server must present a valid TLS certificate for authentication and for that certificate's Certificate Authority to exist in the server's Trusted Root.	False
`-UseMutualTLSForServerToServer`	`<String>`	Enforces the requirement for a valid server TLS certificate during communication. When enabled, the server nodes connecting to the first server must present a valid TLS certificate for authentication. Additionally, all servers need to have each other's Certificate Authorities to exist in their Trusted Roots.	True
`-Node`	`<String>`	Specifies one or more IP addresses of cache servers, cache clients, or bridge nodes where TLS settings will be applied. Provide a comma-separated list of IP addresses to enable TLS settings on the desired nodes. Please ensure that client nodes with NCache installed are included; for NCache clients without installation, use manual configuration.	-
`-Credentials`	`<pscredential>`	Specifies the user credentials required to authorize access for the specified operation. These credentials should belong to a user who has appropriate permissions at the node.	-

Parameters	Data Types	Description	Default Value
`-certificatename*`	`<String>`	The CertificateName parameter specifies the name of the TLS certificate to be used for encryption. It provides the unique name associated with the desired TLS certificate for secure communication.	-
`-certificatethumbprint*`	`<String>`	Specifies the unique thumbprint of the TLS certificate to ensure its authenticity and integrity. It provides the fingerprint value associated with the desired TLS certificate for secure communication.	-
`-clientservercommunication`	`<SwitchParameter>`	Enables TLS encryption for communication between client and server nodes.	False
`-servertoservercommunication`	`<SwitchParameter>`	Enables TLS encryption for communication between server nodes within a cluster.	False
`-bridgecommunication`	`<SwitchParameter>`	Enables TLS encryption solely for communication between NCache bridge and geographically separate caches. If the user wants to extend this security to encompass communication between the bridge nodes as well, they should use the `server-to-server-communication` flag. If `bridgecommunication` is true, make sure to enable `client-server-communication`. Currently, NCache requires you to use the same certificate on both bridge nodes.	False
`-usemutualtlsforclienttoserver`	`<String>`	Enforces the requirement for a valid client TLS certificate. When enabled, client nodes connecting to the server must present a valid TLS certificate for authentication and for that certificate's Certificate Authority to exist in the server's Trusted Root.	False
`-usemutualtlsforservertoserver`	`<String>`	Enforces the requirement for a valid server TLS certificate during communication. When enabled, the server nodes connecting to the first server must present a valid TLS certificate for authentication. Additionally, all servers need to have each other's Certificate Authorities to exist in their Trusted Roots.	True
`-node`	`<String>`	Specifies one or more IP addresses of cache servers, cache clients, or bridge nodes where TLS settings will be applied. Provide a comma-separated list of IP addresses to enable TLS settings on the desired nodes. Please ensure that client nodes with NCache installed are included; for NCache clients without installation, use manual configuration.	-
`-pfxpath`	`<String>`	Specifies the path to the PFX certificate file to be used by NCache Java clients on Linux machines for mutual client-server TLS authentication. This parameter is not required for Windows-based clients or cache servers.	-
`-pfxpassword`	`<String>`	Specifies the password associated with the PFX certificate file. This parameter is relevant only for NCache Java clients running on Linux machines and is used in conjunction with the PFXPath parameter. It is not applicable to Windows-based clients or cache servers.	-
`-userid`	`<String>`	Specifies the user ID required to authorize access for the specified operation. These credentials should belong to a user who has appropriate permissions at the node.	-
`-password`	`<String>`	Specifies the password required to authorize access for the specified operation. These credentials should belong to a user who has appropriate permissions at the node.	-

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

Configure SSL/TLS Encryption in Windows and Linux

Note

Note

How to Configure TLS Encryption

Note

Important

Important

Important

Important

Note

Considerations for Certificate Placement

Note

Important

Verify Successful Client Connectivity Through TLS

Note

Certificate Elements

Troubleshooting

See Also

Contact Us