Creating, Installing, and Managing Certificates¶

In order to establish secure TLS connections with clients, certificates must be configured for the PCoIP Connection Manager and the PCoIP Security Gateway. If the required certificate files are not present or they are improperly configured, clients will not be able to connect and users will not be able to establish PCoIP sessions.

Only certificates with RSA private keys having at least 2,048-bit length are supported. RSA private keys having at least 3,072-bit length are recommended. Certificates with DSA private keys are not supported. Certificates that include an MD5-based digital signature algorithm are not supported.

Both the PCoIP Connection Manager and PCoIP Security Gateway support wildcard certificates which can be used on multiple PCoIP Connection Manager and PCoIP Security Gateway servers.

If you are ready to replace your default self-signed certificates with your own signed certificates, proceed to Signed Certificates for Production.

Default Certificate¶

The PCoIP Connection Manager and PCoIP Security Gateway installation script generates a self-signed certificate during installation to facilitate testing. This should be replaced with your own certificate, signed by a trusted Certificate Authority (CA), when deploying a production system.

By default, both the PCoIP Connection Manager and the PCoIP Security Gateway use the same private key and signed certificate; if your security policy requires it, each service can use its own key/certificate pair instead. If two sets of certificates are required, follow these procedures twice to generate two key/certificate pairs and configure the PCoIP Security Gateway appropriately.

Signed Certificates for Production¶

Production systems should use your own certificates, signed by a trusted certificate authority (CA). The following sections describe the process of creating, signing, and installing certificates.

At a high level, the process is:

1. Generate a new private key and certificate signing request.

2. Submit the CSR to a trusted certificate authority (CA) for signing, either internal or third-party.

3. Verify and convert the resulting certificate files to the .pem format.

4. Install the certificates on the PCoIP Connection Manager and Security Gateway machine, restart both services, and inspect their log files to verify that the certificates are working and that all services have started.

5. Protect the certificate files and access.

Creating Certificate Files¶

First, generate a new private key and CSR (certificate signing request).

To generate a private key and CSR:

1. On the PCoIP Connection Manager server, open a command prompt.

2. Create a temporary directory to store the certificate and move into it.

   This example uses ~/certs, which creates a certs directory under your home directory, but you can create it anywhere you like:

   mkdir ~/certs
   cd ~/certs
   

3. Generate a private key file and CSR according to your organization's security policy.

   This example creates an RSA 3072-bit private key and a CSR requesting a sha384 hash algorithm. The private key file is private.key and the CSR file is server.csr.

   openssl req -new -newkey rsa:3072 -sha384 -nodes -keyout private.key -out server.csr
   

   When running this command, you will be prompted for information to be displayed in the certificate.

   Distinguished Name Field	Description	Example
   Country Name	The two-letter ISO abbreviation for your country	CA for Canada
   State or Province Name	The unabbreviated name of the state or province where your organization is legally located.	British Columbia
   Locality Name	The city where your organization is legally located.	Burnaby
   Organization Name	The full legal name of your organization. Cannot use < > ~ ! @ # $ % ^ * / \ ( ) ? . , &	EasyShop Corporation
   Organization Unit Name	Department of your organization. Cannot use < > ~ ! @ # $ % ^ * / \ ( ) ? . , &	Global Support Services
   Common Name	The fully qualified domain name (FQDN) of your server. This must be an exact match or, in the case of a wild card, an asterisk (*) before the domain.	If your PCoIP Connection Manager address is easyshop.easybuzz.com then the CSR must have the common name easyshop.easybuzz.com. If you plan on having a wildcard certificate for use on multiple PCoIP Connection Manager servers, then prefix the domain with an asterisk (*). In this example: *.teradici.com.
   Email Address	Leave blank
   A challenge password	Leave blank
   An optional company name	Leave blank

You should now have two files in your ~/certs folder; private.key and server.csr.

You can verify the details of the CSR request using the following command:

openssl req -noout -text -in ~/certs/server.csr

Obtaining the Signed Public Key Certificate¶

Next, use your CSR request to obtain a public signed certificate. Submit server.csr to a trusted CA following your organization's security policy. Follow the CA's instructions to obtain the public signed certificate.

If your CA offers the public signed certificate both with and without the certificate chain, download both. If they do not offer a certificate file including the certificate chain, refer to your CA's documentation on how to build it.

When you have received the signed files, copy them into your working directory (~/certs).

Verifying and Converting Certificate File Format¶

Before installing your certificate, you must verify that it's in the correct format and convert it to .

These instructions assume the following:

• You have copied the files received from the CA to ~/certs.

• The public certificate signed by the CA without the certificate chain is named certificate.crt.

• The public certificate signed by the CA with the certificate chain (intermediary and root certificates) is named CAcertificate.crt.

To verify the certificate file format:

Verify the certificate.crt file:

openssl x509 -in certificate.crt -text -noout

• If you don't see any errors, change the file extension from .crt to .pem:

  mv certificate.crt certificate.pem
  

• If you DO see errors, open the certificate file in a text editor and verify the following:

  • There are no extra characters at the end of lines
  • The file starts with -----BEGIN CERTIFICATE-----
  • The file ends with -----END CERTIFICATE-----

  If the file doesn't begin and end with the required lines, it's in the wrong format. Convert it to PEM:

  openssl x509 -inform der -in certificate.crt -out certificate.pem
  

  Verify the newly renamed file:

  openssl x509 -in certificate.pem -text -noout
  

Repeat these steps for CAcertificate.crt (the certificate that includes the certificate chain).

When you are done, you should have two .pem files and one private key file in the ~/certs directory: