Skip to content

Creating And Installing Custom Certificates

This section describes how to replace Teradici's default certificates with your own custom certificates.

Note: These procedures use OpenSSL

The procedures in this section use OpenSSL to create private keys, certificate signing requests, and certificates. To use OpenSSL, install Visual C++ 2008 Restributables and Win32 OpenSSL Light v1.0.2g+.

For detailed information about OpenSSL, refer to OpenSSL documentation.

To replace Teradici's default certificates with custom certificates:

  1. Install required OpenSSL components on your system.

  2. Create the internal root CA certificate.

  3. Create a private key and certificate pair for the PCoIP Agent.

  4. Configure the certificate mode for each desktop.

  5. Install the internal root CA in your PCoIP clients.

Installing OpenSSL Requirements

Install the following components on your Windows machine:

  • Visual C++ 2008 Redistributables

  • Win32 OpenSSL v1.0.2g Light (or later).

    When prompted during OpenSSL installation, copy the OpenSSL DLLs to the OpenSSL binaries directory; for example, C:\OpenSSL-Win32\bin.

Note: Examples use the default installation directory

The following examples assume the default OpenSSL installation directory: C:\OpenSSL-Win32.

Creating the 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. Open a command prompt and navigate to the OpenSSL binaries directory (c:\OpenSSL-Win32\bin).

  2. Type openssl and press Enter to launch OpenSSL.

    Note: OpenSSL may need help finding the .cfg file

    If you see the following error, you will need to set the OPENSSL_CONF variable before proceeding.

    WARNING: can’t open config file: /usr/local/ssl/openssl.cnf
    
  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 -des3 3072
      

    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.

Setting the OPENSSL_CONF variable

If OpenSSL is unable to find its configuration file, you may need to set the OPENSSL_CONF variable.

To set the OPENSSL_CONF variable:

  1. Exit OpenSSL.

  2. Type the following command:

    set OPENSSL_CONF=C:\OpenSSL-Win32\bin\openssl.cfg
    
  3. Type ssl and press Enter to continue with the step you were performing when you saw the error.

Self-signing and Creating the Internal Root CA Certificate

Now that we have our private key, we will use it 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
    

    An interactive script will run, which prompts you to enter values for several fields.

  2. Follow the prompts to enter field values:

    Field Notes
    Country Name Optional. Use one of the ISO 3166-1 alpha-2 country codes.
    State or Province Name Optional
    Locality name Optional
    Organization Name Optional
    Common name Required. Enter a name for your root CA (for example, certificates.mycompany.com)
    Email address Optional. Enter an administrative alias email if you use this field.

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.

Creating a Private Key and Certificate for the 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).

  3. Store the file in the C:\OpenSSL-Win32\bin 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 the Private Key and Certificate

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

  1. Launch openssl from the C:\OpenSSL-Win32\bin directory.

  2. Create a 3072-bit private key in RSA format:

    genrsa -out pcoipprivate.pem 3072
    

    This command creates a pcoipprivate.pem file in the current directory.

  3. Create a certificate signing request:

    req -new -key pcoipprivate.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.csr 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 pcoipcert.pem -days 365
    

    This command creates a poipcert.pem file in the current directory.

    Caution: Use Secure Hash Algorithms

    Windows Certificate Manager has deprecated the use some older hash algorithms such as MD4, MD5, and SHA1. Use SHA-384 or SHA-256 when creating your certificates.

  5. Create a PKCS#12 file to import into a Windows certificate store. Replace <password> with your password:

    pkcs12 -export -in pcoipcert.pem -inkey pcoipprivate.pem -name PCoIP -out pcoipagent.p12 -password pass:<password>
    

    This command creates a pcoipagent.p12 file in the current directory.

    Note: The -name parameter must be 'PCoIP'

    You must specify PCoIP as the -name parameter value. This value sets the certificate's friendly name.

  6. Place the pcoipagent.p12 and rootCA.pem files where administrative users of the PCoIP Agent can access them, such as on network storage or on a USB key.