Virtual Appliance SSL Certificates

You will need SAN entries for:

• FQDN of the Virtual Appliance.
• Wildcard of FQDN (*HOMEURL).

You will need SAN entries for:

• FQDN of the Virtual Appliance.
• Each of the following internal microservices:
  • gw.HOMEURL.
  • traefik.HOMEURL.
  • portainer.HOMEURL.
  • cdn.HOMEURL.
  • app.HOMEURL.
  • agent-api.HOMEURL.
  • printer-admin-api.HOMEURL.
• If using Advanced Features:
  • Control Panel Application (CPA) — cpa-api.HOMEURL.
  • Control Panel Application (CPA) — cpp-ui.HOMEURL.
  • Off-Network Print — ofn.HOMEURL.
  • Off-Network Print — ofn-gw.HOMEURL.
• If using the Enterprise Data Warehouse:
  • edw.HOMEURL.
• If using CAC/PIV:
  • pivcac.HOMEURL.

Corresponding ssl.crt file:

Corresponding ssl.key file:

This method covers converting a PKCS12 PFX certificate to Base64 encoded PEM files.

1. Download the Virtual Appliance-CertUtil application.
2. Unzip the archive file into its own folder.
3. Copy your PFX file into the new folder. To simplify this process, rename the PFX file to ssl.pfx.
4. Open up Command Prompt or PowerShell terminal.
5. Use the change directory (cd) command to change the directory to where the archive contents have been dumped.

6. In the terminal window run the following command.

   Copy Code

   Command Prompt

   va-certutil.exe pfx2pem -i

   Copy Code

   PowerShell

   /va-certutil.exe pfx2pem -i

7. Enter the input filename of the PKCS12 bundle (PFX) to convert. The default selection is the text inside the brackets. To accept the default suggestion, press the Enter key.

8. Enter the password of the PKCS12 bundle when prompted and press the Enter key to continue. The terminal does not display the password characters.

   

9. Enter the output filename of the private key — press Enter to accept the default value, ssl.key.
10. Enter the output filename of the certificate — press Enter to accept the default value, ssl.cert.
11. Enter the output filename of the certificate chain — press Enter to accept the default value, ssl-chain.crt.

Move the Files

When the process completes, you will see the new files:

• ssl.key,
• ssl.crt,
• ssl-chain.crt.

1. Rename ssl-chain.crt to ssl.crt.
2. Place this file and the corresponding private key file (ssl.key) in the following shared drive location(\\IP-of-Virtual Appliance\appliance-storage\certs).

It may take the Virtual Appliance up to 10 minutes to recognize the new certificates. You may reboot the Virtual Appliance to speed this up.

This method creates the ssl.csr and ssl.key files needed for a Certificate Authority to publish the ssl.crt file.

1. Download the Virtual Appliance-CertUtil application.
2. Unzip the archive file into its own folder.
3. Open up Command Prompt or PowerShell terminal.
4. Use the change directory (cd) command to change the directory to the location where you saved the extracted files.

5. In the terminal window, run the following command.

   Copy Code

   Command Prompt

   va-certutil.exe createcsr -i

   Copy Code

   PowerShell

   /va-certutil.exe createcsr -i

6. With the interactive CSR tool open, generate a private key. Create the private key in the unencrypted PKCS8 format required for the Virtual Appliance.

   1. In the menu, the default selection is the text bracket on the left-hand side. For example, [Y]Press the Enter key to accept the value.

   2. When entering information regarding Organization Unit (OU), locality, etc., enter one string per line. Enter a blank line to finish.

      

7. To generate a new private key, press Enter to accept the [Y] (Yes) value.
   1. Enter the length (bits) of the private key. (2048 is the recommended minimum.)
   2. Enter the output filename of the private key. (This must be ssl.key)
   3. Enter the signature algorithm to use. (SHA256-RSA, SHA38-RSA, SHA512-RSA, ECDSA-SHA256,ECDSA-SHA384, ECDSA-SHA512)
   4. Enter the common name (CN) of the subject. (*.va.YOUR_URL)
   5. Enter the organizational unit (OU) of the subject.
   6. Enter the organization (O) of the subject.
   7. Enter the city or locality (L) of the subject.
   8. Enter the state or province (ST) of the subject.
   9. Enter the country (C) of the subject.
   10. Enter the DNS name of the subjectAlternativeName.
   11. Enter the IP Address of the subjectAlternativeName, if necessary. (You can leave it blank.)
   12. Enter the email address of the subjectAlternativeName.
   13. Enter the output filename of the CSR. (This must be ssl.csr)

Submit the Certificate

When the process completes, you'll see the following new files:

• ssl.key.
• ssl.csr.

Submit the ssl.csr file to your CA to publish back the required certificate. Ensure the private key is not exposed online or to unauthorized personnel.

Once the CA provides the certificate"

1. Rename the file to ssl.crt.
2. Place this file and the ssl.key file in the following Virtual Appliance shared drive location(\\IP-of-Virtual Appliance\appliance-storage\certs).
3. See Format the Certificate & Key. If you need to compile your full chain certificate, reference Create a Full Chain Certificate.

It may take the Virtual Appliance up to 10 minutes to recognize the new certificates. You may reboot the Virtual Appliance to speed this up.

This method is for creating a full-chain certificate using the ssl.crt and ssl.key files created in Method 2.

1. Download the Virtual Appliance-CertUtil application.
2. Unzip the archive file into its own folder.
3. Put your certificate file into the same folder. If your crt file is not already named ssl.crt, rename it during file placement.
4. Open up Command Prompt or PowerShell terminal.
5. Use the change directory (cd) command to change the directory to the location where you saved the extracted files.

6. In the terminal window, run the following command.

   Copy Code

   Command Prompt

   va-certutil.exe buildcrtchain -i

   Copy Code

   PowerShell

   /va-certutil.exe buildcrtchain -i

7. With the interactive utility open, complete the following. The default values are the text inside the brackets. To accept the default suggestion, press the Enter key.

   

   1. Enter the filename of the endpoint certificate.
   2. Enter the input filename of the root CA certificate.
8. Enter the input filename of the intermediate CA certificate. Enter one string per line. Enter a blank line to finish.
9. Enter the output filename of the endpoint cerficate chain. Press Enter to accept the default value ssl-chain.crt.

Move the Files

When the process completes, you will see the new file, ssl-chain.crt, in the folder.

1. Rename ssl-chain.crt to ssl.crt.
2. Place this file and the corresponding private key file (ssl.key) in the following Virtual Appliance shared drive location(\\IP-of-Virtual Appliance\appliance-storage\certs).

It may take the Virtual Appliance up to 10 minutes to recognize the new certificates. You may reboot the Virtual Appliance to speed this up.

Some organizations have a PKI team that generate SSL certificates and private keys without requiring a Certificate Signing Request (CSR). If you use that method, ensure the PKI team understands the requirements above and verifies the certificate details. If the PKI team generates a certificate in PKCS12 format (.pfx) it needs to be converted to PEM format.

The following OpenSSL commands convert PKCS12 to PEM format. Mac / Linux devices include OpenSSL by default, but Windows devices require installing Windows Subsystem Linux (WSL). If your Windows device does not support WSL, these packages are available. The Win64 or Win32 Light version works.

openssl pkcs12 -in va_cert.pfx -out ssl.crt -clcerts -nokeys
openssl pkcs12 -in va_cert.pfx -out ssl.key -nocerts -nodes

If the PKCS12 bundle was saved with a password, each of the preceding commands will prompt for that password.

Once you convert the PKCS12 certificate, continue to the Verify the SSL Certificate step below.

1. Create the SSL Certificate Signing Request (CSR)

Generate a CSR using OpenSSL. Mac / Linux devices include OpenSSL by default, but Windows devices require installing Windows Subsystem Linux (WSL). If your Windows device does not support WSL, these packages are available. The Win64 or Win32 Light version works.

2. Create the OpenSSL Configuration File

Create a file called ssl.cnf with the following content, overriding countryName, stateOrPrivinceName, locatlityName, organizationName, commonName, DNS.1 and DNS.2 as required.

Override Specifics:

• stateOrProvinceName should be spelled out in full (i.e., Utah).
• localityName should not include punctuation.
• commonName should be the Virtual Appliance FQDN. For example, va.plawsfed.lab.
• DNS.1 should be theVirtual Appliance FQDN.
• DNS.2 should be the wildcard underneath the Virtual Appliance FQDN. For example *.va.plawsfed.lab.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[req]
default_bits = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
prompt = no

[req_distinguished_name]
countryName = US
stateOrProvinceName = Utah
localityName = Saint George
organizationName = PrinterLogic
commonName = printerlogic.mycompany.com

[req_ext]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = printerlogic.mycompany.com
DNS.2 = *.printerlogic.mycompany.com

3. Generate the Private Key and CSR

Using Command Prompt or Terminal, run the following commands. For Windows devices, include the path to openssl.exe in the PATH environment variable, OR type the fully qualified path to openssl.exe.

This command reads the ssl.cnf configuration file and generates a new 2048-bit RSA private key (stored in ssl.key) and the CSR (stored in ssl.csr). To generate a new private key and the CSR:

openssl req -out ssl.csr -newkey rsa:2048 -nodes -keyout ssl.key -config ssl.cnf

To validate the parameters of the CSR, run the following command.

openssl req -text -noout -verify -in ssl.csr

Sample output:

4. Submit the CSR to a Certification Authority for Signature

The next step is submitting the ssl.csr file to a Certification Authority (CA). If your organization includes a PKI team or has an existing process for certificate signing, use that method. If submitting the CSR directly to a Windows Certificate Authority, determine which certificate template you need. A Windows CA defines a WebServer certificate template by default, but often, this is duplicated and customized.

1. Upload the CSR to the CA and run the following in an elevated command prompt. In the command, C:\certs\va.plawsfed.lab is the example folder location.

   Copy Code

   certreq -attrib "CertificateTemplate:WebServer" -submit C:\certs\va.plawsfed.lab\ssl.csr

   Include the certificate name in the command if using a custom WebServer certificate template.

   Copy Code

   certreq -attrib "CertificateTemplate:PLAWSFEDWebServer" -submit C:\certs\va.plawsfed.lab\ssl.csr

2. Select the online certification authority handling the request, then select OK.

   

3. Save the generated certificate to a file called ssl.crt, then select OK.

   

4. Verify the resulting ssl.crt file matches the private key generated earlier.

   Copy Code

   openssl rsa -modulus -noout -in ssl.key | openssl md5
   openssl x509 -modulus -noout -in ssl.crt | openssl md5

5. Both MD5 hashes should be identical.

   

1. Open the ssl.crt file and select the Certification Path tab.

   

2. Working from the bottom of the certificate chain to the top, select each certificate above the Virtual Appliance certificate and perform the following steps.

   1. Select the View Certificate button.

      

   2. Select the Details tab then select Copy to File.

      

   3. On the Export File Format section of the wizard, select Base-64 encoded X.509 (.CER), then select Next.

      

   4. Enter the path/filename to store the certificate then select Save Make sure to give this file an appropriate name, so that you can reference it properly later.
   5. Select Finish.

Append All Certificates

Once all certificates in the chain have been exported to file, return to the command prompt and append all CA certificates to ssl.crt. Follow these guidelines to create a properly formatted ssl.crt file:

• The order of the certificates in the ssl.crt file is crucial. The file should start with the endpoint certificate (the Virtual Appliance certificate), then working up the certificate chain, any intermediate certificates, followed lastly by the root certificate.
• Each certificate in the file should begin with the certificate header on a line by itself. -----BEGIN CERTIFICATE-----
• Have a base-64 encoded X.509 certificate payload.
• End with the certificate footer on a line by itself. -----END CERTIFICATE-----

Strip Informational Text

Strip any other informational text. For example, if the Virtual Appliance certificate chain looks like this:

• Root CA (saved as root.cer)
  • Intermediate CA 1 (saved as int1.cer)
    • Intermediate CA 2 (saved as int2.cer)
      • Virtual Appliance Certificate

Do the following:

1. Use the following commands to properly build the certificate chain into the ssl.crt file:

   Copy Code

   Windows Commands

   type int2.cer >> ssl.crt
   type int1.cer >> ssl.crt
   type root.cer >> ssl.crt

   Copy Code

   Mac/Linux Commands

   cat int2.cer | tee -a ssl.crt
   cat int1.cer | tee -a ssl.crt
   cat root.cer | tee -a ssl.crt

2. Open the ssl.crt file in a text editor and validate that all certificates are present and follow the guidelines above. See the examples below.

This is an example of a properly formatted Virtual Appliance certificate:

This is an example of an INVALID Virtual Appliance certificate (the END CERTIFICATE footer and BEGIN CERTIFICATE header appear together on the same line):

To correct this, simply add a new line between the -----END CERTIFICATE----- footer and the -----BEGIN CERTIFICATE----- header (there are always 5 dashes or hyphens before and after the words).