Add server certificate

Add a server certificate to a FairCom Server

Abstract

The information in this section describes ways to create secure communications between a FairCom server and its clients.

FairCom products use TLS version 1.3 to encrypt communication between FairCom servers and clients. The Configure the server to use a certificate procedures describe how to configure TLS for FairCom services.

For TLS to work, you need two things created specifically for each host that runs FairCom servers:

If you want a FairCom server to require clients to use client certificates for authentication, you also need the CA certificate file to be added to the server. This is the same CA certificate that you use to create the client certificates.

Clients always need the CA certificate file to ensure it is talking to the correct server rather than a fraudulent server pretending to be the server.

Create a CA certificate

You can create a CA certificate differently depending on whether you want to run a FairCom server on the Internet or within an internal network. Most customers run FairCom servers on their internal network.

Internal network vs. Internet

If you are securing a FairCom server for use within your internal network, create a self-signed TLS certificate that is designed specifically for the hostname of the computer running the FairCom server.
If you are making a FairCom server available on the Internet, submit a certificate signing request (CSR) to a certificate authority (CA). You will receive a CA certificate and a private key designed specifically for the Internet domain name that hosts the FairCom server.

Important

A CA certificate does not certify the identity of a FairCom server. Instead it uses a network domain name or hostname to certify the identity of a computer on a network. Thus, you only need one CA certificate per computer unless a computer has multiple network adapters that connect to different networks, then you need a separate CA certificate for each network.

Tip

When you run multiple FairCom servers on the same computer, you use the same certificate file and private key file for all services provided by all FairCom servers running on that computer.

Configure the server to use a certificate

Essential information

Once you have the server certificate file and private key file, you need to configure a FairCom server to use these files. This is done by adding TLS entries in the services.json file.

A FairCom server provides multiple services that communicate with external computers. These are listed in the "listeners" section of the services.json file.

Example 1. services.json structure

{
  "listeners": [],
  "applications": [],
  "APIs": [],
  "integrationServices": [],
  "transformServices": []
}

The services that require TLS use the following protocols:

Add a server certificate and its private key to a listener

Navigate to and open the services.json file in a text editor.

Navigate to the desired listener.

Example 2. A listener in the services.json

{
	"serviceName": "https8443",
	"description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps",
	"port":        8443,
	"protocol":    "https",
	"enabled":     true,
	"tls":         
      {
		"certificateAuthoritiesFilename": "C:/Certificates/ca.crt",
		"certificateFilename":            "C:/Certificates/server.crt",
		"privateKeyFilename":             "C:/Certificates/server.key"
	}
}

Add the following "tls" object:
```
"tls":         
{
  "certificateFilename": "C:/Certificates/server.crt",
  "privateKeyFilename":  "C:/Certificates/server.key"
}
```
1. Update the "certificateFilename" property value with the full or relative path to the server certificate file.
2. Update the "privateKeyFilename" property value with the full or relative path to the private key file.
3. When the certificate and private key are combined into one file, update the "certificateFilename" property with the full or relative path to this file and omit the "privateKeyFilename" property.

Make the FairCom service require clients to use a client certificate for authentication

Navigate to and open the services.json file in a text editor.
Navigate to the desired listener.
Update the "certificateAuthoritiesFilename" property value with the CA certificate.
```
"tls":         
{
  "certificateAuthoritiesFilename": "C:/Certificates/ca.crt",
  "certificateFilename":            "C:/Certificates/server.crt",
  "privateKeyFilename":             "C:/Certificates/server.key"
}
```
Caution
When you specify a CA certificate on a FairCom server, it will only accept TLS connections from clients that have valid client certificates signed by the CA in the CA certificate. If you want to disable client certificate authentication, you must omit the "certificateAuthoritiesFilename" property.

Tips

To turn on a listener, set the "enabled" property to true.
To turn off a listener, set the "enabled" property to false.
To change the TCP/IP port of a listener, set the "port" property to a different port number.
To add a new listener, copy an existing listener and change the "serviceName" and "port" properties to unique values.
Include the "certificateAuthoritiesFilename" only when you require clients to use valid client certificates signed by the CA in the CA certificate.

CA certificate file