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 1,024-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.

Certificate files must be readable by the teradici_components group.

If you are ready to replace your default self-signed certificates with your own signed certificates, proceed to Signed Services 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 < > ~ ! @ # $ % ^ * / \ ( ) ? . , &	Teradici 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 teradiciplatform.teradici.com then the CSR must have the common name teradiciplatform.teradici.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:

Installing Certificate Files¶

To install the newly-created certificate files, copy them into the configured certificate folder of the PCoIP Connection Manager machine and restart the services.

We will copy three files: the signed certificate without the chain (certificate.pem), the signed certificate with the chain (CAcertificate.pem), and the key file (private.key).

To install new certificate files:

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

2. Rename the existing certificate files, preserving them as backups:

   mv /opt/Teradici/certs/CMCertificate.pem /opt/Teradici/certs/CMCertificate.pem.backup
   mv /opt/Teradici/certs/CMCertificateCA.pem /opt/Teradici/certs/CMCertificateCA.pem.backup
   mv /opt/Teradici/certs/CMCertificateKey.pem /opt/Teradici/certs/CMCertificateKey.pem.backup
   

3. Copy the new certificate files. These commands assume you've created these files using the instructions above; if you haven't, the source filenames shown here may be different.

   cp ~/certs/certificate.pem /opt/Teradici/certs/CMCertificate.pem
   cp ~/certs/CAcertificate.pem /opt/Teradici/certs/CMCertificateCA.pem
   cp ~/certs/private.key /opt/Teradici/certs/CMCertificateKey.pem
   

   The resulting files are renamed to CMCertificate.pem, CMCertificateCA.pem, and CMCertifcateKey.pem. Note that the .key file is renamed to .pem by this copy operation.

4. Restart PCoIP Connection Manager components:

   service security_gateway restart
   service connection_manager restart
   

5. Once both services are back up, check the PCoIP Connection Manager log file to ensure the PCoIP Connection Manager web service started:

   less /var/log/Teradici/ConnectionManager/catalina.out
   

   Look for these lines in the output:

   INFO: Initializing ProtocolHandler ["http-apr-443"]
   INFO: Starting ProtocolHandler ["http-apr-443"]
   

   Also verify that there are no lines beginning with SEVERE:, as they may indicate that the certificate failed to load.

6. Check the most recent PCoIP Security Gateway log file to ensure the PCoIP Security Gateway service started. To do this, we'll go into the log directory, list all the files, and then use less to view the most recent:

   cd /var/log/Teradici/SecurityGateway/
   ls –l
   less <the_most_recent_filename>
   

Protecting Certificate Files¶

Once your certificate files have been created and installed, follow these guidelines to protect them.

To maintain client communications security:

• Ensure only root and the teradici_components group can read private keys.
• Ensure all certificate files are read-only.

To protect certificate files:

1. Log in to the server as an administrator.

2. Open a command prompt and issue these commands:

   chown root:teradici_components /opt/Teradici/certs/CMCertificateKey.pem
   chmod 440 /opt/Teradici/certs/CMCertificateKey.pem
   chmod -w /opt/Teradici/certs/CMCertificate.pem
   chmod -w /opt/Teradici/certs/CMCertificateCA.pem
   

Configuring Certificate Location and File Names¶

By default, certificate files are created in /opt/Teradici/certs during installation. This location and file names do not normally need to be changed.

If your organization's security policy requires it, you can change the location or file name of certificate files. The PCoIP Connection Manager and the PCoIP Security Gateway certificate files may be located in different directories.

Once you have installed the the certificates automatically you can run restart_components.sh to restart the system and complete the update.

Customizing PCoIP Connection Manager Certificate Information¶

The PCoIP Connection Manager's certificate configuration is in the Tomcat server config file, located in /opt/Teradici/thirdparty/tomcat/conf/server.xml. Set the certificate file paths with the following attributes of the <Connector> element in server.xml:

• SSLCertificateFile
• SSLCertificateKeyFile
• SSLCACertificateFile

Customizing PCoIP Security Gateway Certificate Information¶

The PCoIP Security Gateway's certificate configuration is in its own configuration file, located in /etc/SecurityGateway.conf. Set the certificate file paths with the following attributes:

• SSLLinuxExtCA
• SSLLinuxExtCert
• SSLLinuxExtPriv
• TCPControlLinuxExtCA
• TCPControLinuxExtCert
• TCPControlLinuxExtPriv

Self-Signed Certificates for Testing¶

A self-signed certificate can be used for testing and evaluation, and is provided by a default installation.

When using the self-signed certificate, PCoIP clients will connect but will indicate that the connection is insecure. Note that this warning appears because the certificate is not trusted; the connection may actually be secure, if the system is secured by other means (for example, if the entire system is deployed on a secured network).

For production systems, Teradici highly recommends replacing the self-signed certificate files with your own certificates, signed by a trusted Certificate Authority (CA).

About the Default Certificate Files¶

By default, both the PCoIP Connection Manager and PCoIP Security Gateway use the same key/certificate pair located in /opt/Teradici/certs.

• CMCertificate.pem contains the leaf certificate that the server presents to the client during the TLS handshake. This certificate contains the public key that the client uses to encrypt the symmetric key. Both the server and the client use this symmetric key for encryption and decryption in subsequent communications.

  This certificate secures the following ports:

  • TCP port 443 for the PCoIP Connection Manager.

  • TCP port 4172 for the PCoIP Security Gateway.

  This certificate is presented as follows:

  • The PCoIP Connection Manager presents this certificate file to PCoIP clients.

  • The PCoIP Security Gateway presents this certificate file to PCoIP clients and to the PCoIP Connection Manager.

• CMCertificateCA.pem contains the full chain of certificate files that the server presents to the client during the TLS handshake. For the client to establish trust of the leaf certificate, one or both of the following must be true:

  • At least one of the certificate files in the chain must be in the client's trust store.

  • The certificate of the certificate authority (CA) used to sign the last certificate in the chain must be in the client's trust store.

Regenerating the Self-Signed Certificate¶

If you need to regenerate the self-signed certificate, use the make_certs.sh utility script. Include the --install option to generate and install the certificates automatically:

sudo ~/opt/Teradici/Management/bin/make_certs.sh --install

If you use the --install option, files will be installed in the /opt/Teradici/certs directory and overwrite any existing files with the same names. If the /opt/Teradici/certs directory does not exist, the script will create it with the following properties:

• Ownership: root
• Group: teradici_components
• Access: Readable and browsable only by root and teradici_components group members.

Installed files have these properties:

• Ownership: root
• Group: teradici_components
• Access: Readable only by root and teradici_components group members.

Once you have installed the the certificates automatically you can run restart_components.sh to restart the system and complete the update.