Creating and Managing PCoIP Management Console Certificates¶

This section contains information on how to manage your PCoIP Management Console certificates, including custom certificate requirements, creation, upload, update, and general management of certificates.

The following requirements and procedures will help guide you with creating a self-signed certificate for use with Management Console in a secure environment.

Custom Certificate Requirements¶

The certificate loaded onto the PCoIP Management Console for use as the PCoIP Management Console web interface certificate and for endpoint management must meet the following requirements:

• It must be a X.509 certificate in PEM format.

• Three PEM files are needed to install the certificate into the PCoIP Management Console:

  • The first file contains only the PCoIP Management Console public certificate. This is generally referred to as the leaf or server certificate.

  • The second file contains only the PCoIP Management Console certificate’s private key. This is the private key that was generated when you made the certificate request.

  • The third file contains the PCoIP Management Console certificate’s issuing chain, this chain will contain the first certificate and the root certificate and in some cases an intermediate certificate will be required (intermediate CAs, if applicable, and root CA).

    Order of Issuing Chain

    The certificate must have an entire verifiable chain. Any certificate used to sign the leaf certificate must be present in the chain.

    Generally it will be the order of the certificates in the chain will be:

    1. Leaf/Server

    2. Intermediate

    3. Root Ca

• The certificate must be valid, meaning that the current time is after the 'not valid before' time and before the 'not valid after' time.

• Certificate RSA keys.

  • Management Console supports RSA keys or signing algorithm. (ECDSA is not currently supported)

  • Management Console also supports MD5 signatures.

  • The certificate’s RSA key must be 1024 bit or greater. The recommended length is 2048 bits.

  • If the PCoIP Management Console certificate contains an Enhanced Key Usage extension, it must include the Server Authentication usage. It is also acceptable for the certificate to not include an Enhanced Key Usage extension.

Creating and Preparing Your Own Custom Certificate for PCoIP Management Console¶

This section demonstrates how to create your own certificate using OpenSSL and your own CA server. The following steps use the PCoIP Management Console VM and a Microsoft CA server but it can be done from any VM with OpenSSL and a CA server of your choice.

Step 1 - Ensure your PCoIP Management Console does not have Any Custom Certificates Installed¶

To make sure you don't have custom certificates installed:

1. Log into the PCoIP Management Console web interface.

2. Go to SETTINGS > SECURITY > CERTIFICATES and ensure the default certificate is installed by confirming:

   • Security Certificate section Subject and Issued By are populated with localhost. (see #1)

   • Security Chain section is empty. (see #2)

   Custom Certificates

   The Security Certificate and Security Chain fields of custom certificates will be populated by data that does not include localhost and will not have empty values.

   

Step 2 - Connect and Enable SSH to Create Your Certificate Signing Request via the PCoIP Management Console virtual machine¶

You will need to enable SSH prior to creating your certificate. See Accessing the PCoIP Management Console Virtual Machine Console.

To create your Certificate Signing Request:

1. SSH into the PCoIP Management Console VM using your preferred SSH client. The example shown next uses PuTTY.

2. Run the OpenSSL command:
   openssl req -out CSR.csr -new -newkey rsa:3072 -nodes -keyout mccertprivateKey.pem

3. You will get the following response and be asked a series of questions, as shown next:

   

   Modify each entry with your own detailed information. Descriptions are shown next:

   • Country Name: Your country

   • State of Province Name: Your state or province

   • Locality Name: Your city

   • Organization Name: Your company

   • Organizational Unit Name: Your department

   • Common Name: Your PCoIP Management Console Name (for example, hostname of PCoIP Management Console such as se-pcoip-mc-200)

   • Email Address: you@yourcompany.com

   • A challenge password: Your password

   • An optional company name: Optional

4. Press Enter.

5. Two files will be generated in the admin folder: mccertprivateKey.pem and CSR.csr.

6. Using a file management tool of your choice, copy the two files off of your PCoIP Management Console to a desktop of your choice.

Step 3 - Submit Your Certificate Signing Request (CSR)¶

To submit your certificate signing request (CSR):

1. From your CA Server (this example is using a Microsoft CA server)

2. Select Request a Certificate.

3. Select Advanced Certificate Request.

4. From the VM/PC you saved your CSR.csr files, open the CSR.csr file in a text editor and copy the contents into the csr request field on your Certificate Authority (CA) server (https://mycertserver.mydomain.local/certsrv). The content will be Base 64 encoded.

   Using text editor to copy the Certificate Signing Request

   If CSR.csr does not open in your text editor, you can rename CSR.csr to CSR.csr.txt to open it in Notepad and copy the content.

5. For Certificate Template, select Web Server.

6. Do not add anything in the attributes box.

7. Click Submit.

   

Step 4 - Download and Prepare the Certificate¶

To download and prepare the certificate:

1. You can now download the created certificate from the CA server in Base 64 format. However, do not download the certificate chain as it is still in the wrong format. The certificate will show up as certnew.cer.

   

2. Rename certnew.cer to certnew.pem.

3. Get a copy of the CA certificate from the certificate server in Base64. The CA will return a certificate that will be used as part of the chain.

   1. From the CA server home page click the Download a CA certificate link.

      

   2. Select Base64 and then click the Download CA Certificate link.

      

   3. Save the file as CA.cer.

   4. Rename the file to CA.pem.

4. Create a new certificate called chain.pem by combining the contents of certnew.pem with CA.pem using a text editor. (Occasionally the CA certificate may contain intermediate certificates which may need to be added to the chain)

   To combine the certificates:

   1. Rename both certificate extensions to .txt.
   2. Using a text editor like Notepad, create a new file called chain.txt by combining the CA.txt content under the certnew.txt content.

   3. Rename chain.txt to chain.pem.

      Note: All certificates must be in PEM format

      All PCoIP Management Console certificates must be issued in PEM format.

5. Now, you will have three certificates:

   • certnew.pem: The certificate returned from the CA
   • mccertprivateKey.pem: The certificate from the OpenSSL command executed in Step 2 above.
   • chain.pem: The combination of certnew.pem and CA.pem

Uploading Your Own PCoIP Management Console Certificates¶

This section explains how to upload your own certificates to the PCoIP Management Console and to endpoints that require a PCoIP Management Console certificate before discovery. If you wish to avoid browser certificate warnings when you access the PCoIP Management Console’s web interface, you can also install the PCoIP Management Console certificate in your browser.

The PCoIP Management Console requires the following certificates:

• PCoIP Management Console server’s certificate (*.pem): Contains the public key. The PCoIP Management Console’s public key certificate fingerprint is also used for DHCP/DNS endpoint discovery. (e.g. certnew.pem in this topic's example)

• PCoIP Management Console server’s private certificate (*.pem): Contains the private key. (e.g. mccertprivateKey.pem in this topic's example)

• PCoIP Management Console chain certificate (*.pem): Contains the leaf/server certificate, any intermediate certificates, and the trusted root CA certificate used to issue PCoIP Management Console server certificates. (e.g. chain.pem in this topic's example)

Step 1 - Upload Custom Certificate to the PCoIP Management Console VM¶

To upload your certificates to the PCoIP Management Console VM:

1. From the PCoIP Management Console’s top menu, click SETTINGS.

2. Click SECURITY in the left pane and select the CERTIFICATES tab in the SECURITY pane to the right.

3. Click UPDATE.

4. Click SELECT CERTIFICATE, select the PCoIP Management Console’s public certificate file (eg. certnew.pem), and then click NEXT.

   

5. Click SELECT KEY, select the PCoIP Management Console’s private certificate file (eg. mccertprivateKey.pem), and then click NEXT.

   

6. Click SELECT CHAIN, select the PCoIP Management Console’s chain certificate file (eg. chain.pem), and then click NEXT.

   

7. Click Apply.

8. Read the warning message and then click APPLY.

9. When the update process completes, click LOGIN to log in to the PCoIP Management Console again.

   

Step 2 - Update Your DHCP/DNS Server with the PCoIP Management Console Server’s Public Certificate Fingerprint¶

If your DHCP or DNS server is configured to provision endpoints with the PCoIP Management Console’s public certificate fingerprint, this information must be updated next. You can update your server with your PCoIP Management Console certificate fingerprint as follows:

• DHCP server: Edit the EBM X.509 SHA-256 fingerprint option for the PCoIP Endpoint option class. For details, see Configuring DHCP Options.

• DNS server: Edit the EBM-SHA-256-fingerprint DNS text record. For details, see Adding a DNS TXT Record.

Step 3 - Upload PCoIP Management Console Certificate to Your Endpoints¶

If your endpoints are configured with a discovery method and security level that require them to have a PCoIP Management Console certificate in their trusted certificate store before they can connect to the PCoIP Management Console, you can either upload the PCoIP Management Console certificate for a group of endpoints using a PCoIP Management Console profile, or you can upload the PCoIP Management Console certificate locally using each endpoint’s AWI. Depending on your security requirements, you can upload either a PCoIP Management Console issuer certificate (that is, the root CA certificate (or intermediate certificate) that was used to issue a PCoIP Management Console server certificate) or you can upload the PCoIP Management Console server’s public key certificate.

To upload the PCoIP Management Console certificate for a group of endpoints using PCoIP Management Console:

1. Ensure that all ungrouped endpoints are moved from the ungrouped category into a group.

   Possible modifications due to your deployment

   Depending on your site configuration, this may require modifications to your DHCP options or DNS SRV records, or it may require disabling persistent auto-configuration or placing the endpoints into a segregated network with a new PCoIP Management Console.

2. Ensure that every group (or at least one parent group) is associated with a profile.

3. Update all existing profiles to push the new certificate to endpoints. For each profile:

   1. From the PCoIP Management Console’s top menu click PROFILE.

   2. Click the NEW PROFILE button.

   3. Enter a name and description for the profile in their respective fields.

   4. Click the + tab beside the SETTINGS OVERVIEW tab and then select the appropriate type of profile (e.g. TERA2: CLIENT [DUAL], TERA2 HOST [QUAD]) that applies to your endpoints and click ADD.

   5. In the SOFTWARE section, ensure the correct Firmware Version is selected for your endpoints.

   6. Click SECURITY in the left navigation pane, scroll down to Certificate Store, and select Set in Profile.

   7. Click Add New, browse to your PCoIP Management Console public key certificate, highlight it and click Open. (This certificate must have a .pem extension)

   8. Click Upload.

   9. Ensure the correct usage type is selected for any specialized certificates such as 802.1x and Syslog.

      Certificate Usage type Limitation

      Only one specialized usage type can be selected in one profile. Any subsequent certificate selected for the same usage type will cause the previous certificate to change usage type to No Usage.

      802.1x and Syslog options are disabled when you upload certificates without a private key

   10. Click SAVE at the top of the page.

   11. Apply the profile immediately or create a schedule to update your group(s) with the profile.

Installing the PCoIP Management Console Certificate in Your Browser¶

If you wish to avoid browser certificate warnings when you access the PCoIP Management Console’s web interface, you can install a PCoIP Management Console certificate in your browser. You can use either a PCoIP Management Console issuer certificate or the PCoIP Management Console server’s public key certificate. For more information, see How do I get the fix the unsecure browser warning when accessing the Management Console 2.x and 3.x web interface? (1406)

Reverting to the Default Self-signed PCoIP Management Console Certificate¶

To revert to the default PCoIP Management Console certificate:

1. From the PCoIP Management Console’s top menu, click SETTINGS.

2. Click SECURITY in the left pane.

3. Click REVERT SELF-SIGNED CERTIFICATE.

4. Read the warning message and then click APPLY.

   

5. When the update process completes, click LOGIN to log in to the PCoIP Management Console again.