Search

vSEC:CMS Client-Server Communication

Anthony - Versasec Support
Anthony - Versasec Support
  • Updated

Introduction

vSEC:CMS client-server architecture uses HTTP(S) as the underlying communication protocol. There are 2 protocol frameworks that can be used:

  • SOAP
  • gRPC

These protocols are supported when using vSEC:CMS User, vSEC:CMS Admin or Agent and vSEC:CMS Remote Security Device Management (RSDM).

Important
Starting March 2024, we will discontinue support for SOAP client interface. For optimal performance and compatibility, it is recommended to select force gRPC in the protocol dropdown list.
Recommendation
It is recommended to configure all of the above mentioned Windows services to Startup type of Automatic (Delayed Start). This ensures that the services will come back up after a system reboot.
Note
Historically, the vSEC:CMS User application was referred to as vSEC:CMS User Self-Service (USS). Similarly, the vSEC:CMS Admin and Agent applications were referred to as vSEC:CMS Operator Console (OC).

This article will describe how these protocols can be used when configuring your client-server architecture for vSEC:CMS.

Using gRPC

gRPC can be configured when using USS, OC and RSDM. You configure this when setting up these connections if they are to be used in your environment. In this article we will describe how this can be setup for the USS.

Note
The same configuration steps should be used if setting up OC and RSDM.

Configure Server-Side

From Options - Connections click the Add button and select User Self-Service and click Ok. Enable the Enable gRPC checkbox. Depending on your environment settings enter a hostname and port to listen on. You can also setup support for SSL/TLS if you wish to use HTTPS for secure communication between the client and server. The SSL/TLS certificate should be a local machine web server certificate available on the vSEC:CMS server. You can verify that such a certificate is available using MMC on the server to view what certificates are available in the local machine certificate store.

Note
When it is required to renew the certificate you can perform the renewal using MMC or other tools of choice. vSEC:CMS is not responsible for managing the lifecycle of the SSL/TLS certificates used for this.

Make sure that the vSEC:CMS - User Self-Service service is running after you configure this in Windows services.

Tip
Open a command prompt and run query below to ensure that the correct certificate is bound to the correct port. You can check the hash value returned which corresponds with the thumbprint value in the certificate:
>netsh http show sslcert
Important
If you use Microsoft CA you would need to use Microsoft Enhanced RSA and AES Cryptographic Provider as in below example. You should ensure that only this checkbox is selected in the template that will be used when issuing and renewing the SSL/TLS certificate used for the secure connection.

Important
If you are also configuring OC and/or RSDM (from Options - Connections) you need to use a different port for each service to what you configure for USS, i.e. a unique port number needs to be used for each service you use for gRPC. This is not the case if you are using SOAP where the same port can be used.
Important
When issuing a web server certificate for the vSEC:CMS server it is important that the Common Name (CN) of the certificate is unique for that server, otherwise you run the risk that the wrong certificate will be chosen. This is because of a limitation in OpenSSL which is used when searching for certificates in the local computer store. vSEC:CMS will use the subject of the certificate (CN) to establish the SSL connection to. Therefore it is also important that the subject of the certificate is resolvable from a DNS perspective from the client side.
Additionally, if SSL/TLS is used, the subject CN is case sensitive. For example, if the certificate subject CN for the SSL/TLS is Myserver.cms.com then you need to enter Myserver.cms.com and not myserver.com.com when configuring the connection URL below.
Note
It is possible to configure support for SOAP in parallel to using gRPC (simply enable it above and follow instructions below for SOAP). This will give you more flexibility in how your clients can be configured. For example, you can configure your clients to use gRPC and if for whatever reason gRPC service was not available the clients can fall back to use SOAP. If you plan to use such a configuration refer to the Installing the vSEC:CMS MSI Client article for details on how to enable this during client installations.

Configure Client-Side

On a client machine it will be necessary to install the vSEC:CMS User (USS) application. Use the vSEC:CMS Client MSI to install this component. It is recommended to install the USS silently as it is possible to pass in the URL link to the backend vSEC:CMS server that the USS needs to communicate with. This will remove the requirement to manually configure the USS to communicate with the backend in this case.

Open a command Window as administrator and change to the location where the MSI installer is located. Run the command similar to below

Command
msiexec /i "vSEC_CMS Client 64bit.msi" /quiet ADDLOCAL=USS USSGRPC="https://2016-server:8445" USSPCL=4

Where USSGRPC points to the backend gPRC service where vSEC:CMS is installed and USSPCL=4 configures the USS client to use gRPC.

Important
For optimal security you should configure the connection from clients to use SSL/TLS. In this case it is important that the full certificate chain (root and intermediate certificates) are available and trusted on the client host.
Note
The client host will automatically reboot when running above command so make sure you have saved any material you may be working on when performing this task.
Note
If you are installing OC please refer to the article here if you are setting up the Admin application or here if you are installing the Agent application.

Enable Logging

If you’re having trouble with the service, for example the service not starting, you can enable logging to help diagnose the problem. Follow the instructions below to get started. If the issue persists, you may need to open a support ticket.

  1. On the server where vSEC:CMS is installed open File Explorer and navigate to the root of the installation folder (typically here: C:\Program Files\Versasec\vSEC_CMS S-Series). 
  2. Stop the vSEC:CMS - Operator Console Service if it is running from the Windows services console.
  3. Open Notepad as administrator and open the file CmsServiceDll.cfg.

  4. Look for the section <!-- BEGIN USS Server logging --> and for the tag <logging_enabled> set the value to true.

    <!-- BEGIN USS Server logging -->
 <!--logging_enabled: true,false-->
 <logging_enabled>true</logging_enabled>
  5. Save the change and start the vSEC:CMS - Operator Console Service from the Windows services console.
  6. In the log folder in the root of the installation folder you should see log files in the folder now.
  7. Once the issue has been resolved you should disable the logging. Open the CmsServiceDll.cfg again and change the <logging_enabled> to false.

To enable logging for OC and RSDM you should perform similar steps to above but search for the tags <!-- BEGIN ADM Server logging --> and <!-- BEGIN RSDM Server logging --> respectively and edit the <logging_enabled> tag in these sections to set them to true.

Using SOAP

As already mentioned above support for SOAP has been discontinued from March, 2024. You can still use SOAP but any issues encountered when using SOAP will not be supported. For historical reason we will keep this section here for information purposes only.

SOAP can be configured when using USS, RSDM and OC. You configure this when setting up these connections if they are to be used in your environment. In this article we will describe how this can be setup for the USS.

Note
The same configuration steps should be used if setting up RSDM and/or OC.

Configure Server-Side

From Options - Connections click the Add button and select User Self-Service and click Ok. Enable the Enable SOAP checkbox. Depending on your environment settings enter a hostname and port to listen on. You can also setup support for SSL/TLS if you wish to use HTTPS for secure communication between the client and server.

The SSL/TLS certificate should be a local machine web server certificate available on the vSEC:CMS server. You can verify that such a certificate is available using MMC on the server to view what certificates are available in the local machine certificate store.

Note
When it is required to renew the certificate you can perform the renewal using MMC or other tools of choice. vSEC:CMS is not responsible for managing the lifecycle of the SSL/TLS certificates used for this.

Make sure that the vSEC:CMS - User Self-Service service is running after you configure this in Windows services.

Tip
Open a command prompt and run query below to ensure that the correct certificate is bound to the correct port. You can check the hash value returned which corresponds with the thumbprint value in the certificate:
>netsh http show sslcert
Note
It is possible to configure support for gRPC in parallel to using SOAP (simply enable it above and follow instructions above for gRPC). This will give you more flexibility in how your clients can be configured. For example, you can configure your clients to use SOAP and if for whatever reason SOAP service is not available the clients can fall back to use gRPC. If you plan to use such a configuration refer to the Installing the vSEC:CMS MSI Client article for details on how to enable this during client installations.

Configure Client-Side

On a client machine it will be necessary to install the vSEC:CMS User Self-Service (USS) application. Use the vSEC:CMS Client MSI to install this component. It is recommended to install the USS silently as it is possible to pass in the URL link to the backend vSEC:CMS server that the USS needs to communicate with. This will remove the requirement to manually configure the USS to communicate with the backend in this case.

Open a command Window as administrator and change to the location where the MSI installer is located. Run the command similar to below

Command
msiexec /i "vSEC_CMS Client 64bit.msi" /quiet ADDLOCAL=USS USSSOAP="https://2016-server:8443/uss" USSPCL=3

Where USSSOAP points to the backend SOAP service where vSEC:CMS is installed and USSPCL=3 configures the USS client to use SOAP. Important to append /uss to the end of the server hostname/IP. 

Note
The client host will automatically reboot when running above command so make sure you have saved any material you may be working on when performing this task.

Troubleshooting gRPC Connection Issues

Once you have completed the above configurations you may still get connection issues when testing from clients. You may see a generic error message like below when testing the connection for the clients:

This can occur for a few reasons. If you encounter this error please check the following:

  1. Make sure the port that gRPC is listening on is open. You can use a PowerShell command to verify that the port is open by running below, where <server-ip> is the IP of the server that vSEC:CMS is running on and <grpc-port> is the port it is listening on. You should get a response that the test succeeded ok if everything is ok (TcpTestSucceeded : True). 
    Test-NetConnection -ComputerName <server-ip> -Port <grpc-port>
  2. On the client make sure that you have the sub and root CA certificates installed in the local user store that the client is running on. Also, important to not have old expired sub or root CA certificates installed on the clients as these can be selected during the handshake resulting in failure to setup the connection. Therefore, you should only have valid sub and root certificates in the user store and any old/expired sub and root certificates should be removed.
  3. Make sure the name entered in the connection URL settings for the server name match exactly (case-sensitive) what is in the CN for the certificate subject field. For example, if the CN is set to my-vSEC-CMS.mylab.com then the connection URL name should be exactly like what is set in the CN, https://vSEC-CMS.mylab.com:8444 
  4. The URL entered on the client-side connection configuration SHOULD NOT contain a trailing / character. For example, if the back-end server is vSEC-CMS.mylab.com with port 8444 then the correct way to configure the connection URL is https://vSEC-CMS.mylab.com:8444 and not https://vSEC-CMS.mylab.com:8444/. 
  5. Make sure that the certificate template used to issue the certificate on the vSEC:CMS server was issued as either Microsoft Enhanced RSA and AES Cryptographic Provider or Microsoft Enhanced Cryptographic Provider v1.0 provider. It can be that for some reason the certificate gets issued into a different provider store and this can cause the loading of the certificate to fail. To ensure that the certificate is installed into the correct provider store, issue the certificate as a .pfx. Then remove any certificates from the computer store of the vSEC:CMS server that had been issued before for vSEC:CMS server. Open a command prompt on the server and run below command to import the certificate into the correct provider store: 
    certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importPFX <my-server.pfx>
    Or
    certutil.exe -csp "Microsoft Enhanced Cryptographic Provider v1.0" -importPFX <my-server.pfx>