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.
Ensure all certificate files follow your security policy
Protect the regenerated certificate and ensure all certificate files you use conform to your organization's security policy.
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.
Copying certificates from a Window system to a Linux system
When copying certificates from a Windows system to a Linux system, line endings might be incorrect. Check that the certificate text is formatted correctly.
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:
-
Submit the CSR to a trusted certificate authority (CA) for signing, either internal or third-party.
-
Verify and convert the resulting certificate files to the .pem format.
-
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.
Danger: These instructions are examples
The following procedures are working examples. Before following them, you should be sure they conform to your organization's security policies. Modify them however you need to to remain compliant.
These examples use openssl
The following procedures use openssl to create and manage certificates. If you use another tool, adapt these instructions accordingly.
Creating Certificate Files¶
First, generate a new private key and CSR (certificate signing request).
To generate a private key and CSR:
- On the PCoIP Connection Manager server, open a command prompt.
-
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
-
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 isserver.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:
File | Explanation |
---|---|
private.key | Contains the certificate’s private key. |
certificate.pem | Contains a public certificate signed by a CA without the certificate chain. This is presented to PCoIP clients when they connect to the PCoIP Connection Manager during authentication and resource allocation. |
CAcertificate.pem | Contains the certificate chain, including any intermediate and root certificate. Self-signed certificates do not have any root or intermediate certificate. |
Important: Back up your certificate and private key
Back up the private key and certificate in a secure location according to your organization's security policy.
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:
-
On the PCoIP Connection Manager machine, open a command prompt.
-
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
-
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.
-
Restart PCoIP Connection Manager components:
service security_gateway restart service connection_manager restart
-
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. -
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:
- Log in to the server as an administrator.
-
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.
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
Ensure all certificate conform to your security policy
Protect the certificate and ensure all certificate files you use conform to your organization's security policy, including file ownership and permissions.
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).
Regenerate the self-signed certificate if you change your host name
If you use the default self-signed certificate and you change the system host name, you must regenerate the self-signed certificate.
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
andteradici_components
group members.
Installed files have these properties:
- Ownership:
root
- Group:
teradici_components
- Access: Readable only by
root
andteradici_components
group members.