How to Create and Install Custom Certificates on Linux Agents

This article lays out how to replace Teradici's default certificates with your own custom certificates on Linux Agents.
Note the procedure in this article uses OpenSSL to create private keys, certificate signing requests, and certificates.
For detailed information about OpenSSL, refer to OpenSSL documentation.

Steps to replace Teradici's default certificates with custom certificates:

1. Install OpenSSL toolkit on your system if not yet.
2. Create internal root CA certificate.
3. Create a private key and certificate pair for the PCoIP Agent.
4. Install certificates and configure certificate mode for each agent.
5. Install the internal root CA in your PCoIP clients.

1.    Install OpenSSL

OpenSSL comes with Linux by default, which may not be the latest version though. To install or update it, use the following commands:

• CentOS/RHEL: sudo yum -y install openssl
• Ubuntu: sudo apt-get install openssl

2.    Create Internal Root CA Certificate

This section shows how to create a root CA private key, how to use this key to self-sign and generate an internal root CA certificate, and how to add X.509 v3 extensions to a certificate that restrict how the certificate can be used.

Creating a Root CA Private Key

To create a root CA private key in RSA format:

1. SSH to your Linux agent
2. Type openssl and press Enter to launch OpenSSL.
3. To create 3072-bit root RSA key named rootCA.key, use one of the following commands:
   • For an unsecured key, type:
     • genrsa -out rootCA.key 3072
   • For a password-protected key, add the -des3 argument:
     • genrsa -out rootCA.key 3072 -des3

Password-protected keys require the password to be entered each time they are used.

Caution: Store your private root key in a safe location. 
Anyone with access to your private root key can use it to generate certificates that your PCoIP clients will accept.

Self-signing and Creating Internal Root CA Certificate

Now that we have the private key, it will be used to generate a self-signed X.509 root CA certificate called rootCA.pem that is valid for 1095 days (1095 days is three years, ignoring leap days).

To create the root CA certificate:

1. Type the following command. This example creates a certificate that is valid for 3 years (1095 days). Change the -days parameter to customize the certificate lifetime:
   • req -x509 -new -nodes -key rootCA.key -days 1095 -out rootCA.pem
2. An interactive script will run, which prompts you to enter values for several fields. Follow the prompts to enter field values:

Note: Field values can be templatized.
If you will be creating a lot of certificates, consider using a configuration file that contains global field values. See http://www.openssl.org/docs for more information.

3. Creating Private Key and Certificate for PCoIP Agent

For each PCoIP Agent instance, you will create three items:

• A private key file
• A certificate signing request (CSR)
• A certificate

You will also need an X.509 v3 extension file, which is used as an input when generating the workstation certificate.

Note: There are two different private keys
The private key you create here is used by the PCoIP Agent to decrypt data. It is different from the internal root CA private key.

Creating an X.509 Version 3 Extension File

X.509 Version 3 extensions restrict how certificates can be used.

To create the X.509 v3 extension file:

1. Using a text editor, open a new file and paste the following text into it:
   • authorityKeyIdentifier=keyid,issuer
   • basicConstraints=CA:TRUE
   • keyUsage=digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
   • subjectAltName=email:test@mycompany.com
2. Save the file with an .ext extension (for example, v3.ext) in the current directory.

Note: More about X.509 v3 extensions
For more information about X.509 v3 certificate extensions, see https://www.openssl.org/docs/apps/x509v3_config.html.

Creating Private Key and Certificate

To create the PCoIP Agent's private key, certificate signing request, and certificate:

1. Launch openssl.
2. Create a 3072-bit private key in RSA format:
   • genrsa -out pcoip-key.pem 3072
   • This command creates a pcoip-key.pem file in the current directory.
3. Create a certificate signing request:
   • req -new -key pcoip-key.pem -out pcoip_req.csr
   • This command initiates an interactive script that prompts you to enter certificate metadata.
   • You may be prompted for a challenge password and company name.
   • The Common Name field must be the fully-qualified domain name (FQDN) of the desktop where the PCoIP agent is installed for example, mypcname.mydomain.local. If you want to use the same certificate on multiple machines in the same domain, use a wild card for all but the last two segments of the FQDN: *.mydomain.local.
   • When finished, this command creates a pcoip_req.pem file in the current directory.
4. Sign and create an X.509 v3 certificate. This example creates a certificate valid for one year (365 days). To customize the certificate lifetime, change the -days parameter:
   • x509 -req -outform PEM -in pcoip_req.csr -extfile v3.ext -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -sha256 -out pcoip-cert.pem -days 365
   • This command creates a pcoip-cert.pem file in the current directory.

Caution: Use Secure Hash Algorithms
The use of some older hash algorithms such as MD4, MD5, and SHA1 has been deprecated. Use SHA-384 or SHA-256 when creating your certificates. 

4. Install Certificates and Configure Certificate Mode

Custom Security Certificates

In order for a CA signed certificate to be loadable by PCoIP components, it must be stored in /etc/pcoip-agent/ssl-certs in three .pem files, owned by the pcoip user, and only readable by the owning user:

• Copy the file rootCA.pem created in step 2 to /etc/pcoip-agent/ssl-certs/pcoip-cacert.pem.
• Copy the file pcoip-cert.pem created in step 3 to /etc/pcoip-agent/ssl-certs/pcoip-cert.pem. 
• Copy the file pcoip-key.pem created in step 3 to /etc/pcoip-agent/ssl-certs/pcoip-key.pem.  

Configure the Graphics Agent for Linux to use custom certificates

The Graphics Agent for Linux can be configured to look for certificates locally or to generate its own by setting the pcoip.ssl_cert_type directive in pcoip-agent.conf.

For more detailed information, see Configuring the Agent.

Select a Security Key Length

When the Graphics Agent for Linux is attempting to find a certificate in storage, the required key length can be set via the pcoip.ssl_cert_min_key_length directive in pcoip-agent.conf.

If the system cannot find a local certificate with the specified key length, it will either self-generate a certificate (if pcoip.ssl_cert_type is 0), or refuse the connection (if pcoip.ssl_cert_type is 1). This setting has no effect if pcoip.ssl_cert_type is set to 2.

For more detailed information, see Configuring the Agent. 

5. Install Root CA Certificate on PCoIP Client 

The root CA certificate rootCA.pem created in step 2 needs to be installed on PCoIP clients for the authentication to work.

Please refer to the section in windows agent admin guide for detailed steps: http://www.teradici.com/web-help/pcoip_agent/graphics_agent/windows/current/security/installing-certs-on-clients/