VisibleThread uses Apache OpenSSL to provide SSL security of all traffic to the server.

 A self signed certificate is installed on the server by default. When using Internet Explorer to access VisibleThread, users will receive a warning because the certificate installed on VisibleThread is a self signed certificate.

It is possible to purchase a certificate and install it on the VisibleThread appliance. 

The details for how to obtain and install a certificate differ depending on who is the signing authority for the certificate. Your company may already use a particular signing authority to generate certificates, or may have the ability to generate their own certificates.

Please Note: If you would like to use Microsoft IIS for SSL follow this link for a guide to setup a reverse proxy for Mircosoft IIS using you're own SSL certs.

https://support.visiblethread.com/hc/en-us/articles/360021938671-How-to-use-Microsoft-IIS-as-a-reverse-proxy-for-VT-Writer

In general the following steps would be followed:

1. Generate a Certificate Signing Request

A Certificate Signing Request must be created to make an application for a new certificate. To create a CSR follow these steps:

1. Log on to the VisibleThread virtual appliance console

2. To generate a pair of private key and public Certificate Signing Request (CSR) for a web server, e.g. "myserver.com", use the following command :

   openssl req -nodes -newkey rsa:2048 -keyout myserver.com.key -out myserver.com.csr   

   Where 'myserver.com' is your domain or server name.

   This creates two files. The file myserver.com.key contains a private key; do not disclose this file to anyone. Carefully protect the private key.

   In particular, be sure to backup the private key, as there is no means to recover it should it be lost. The private key is used as input in the command to generate a Certificate Signing Request (CSR).

3. You will now be asked to enter details to be entered into your CSR:

   1. Country Name: Use the two-letter code without punctuation for country, for example: US or CA.

   2. State or Province: Spell out the state completely; do not abbreviate the state or province name, for example: California
   3. Locality or City: The Locality field is the city or town name, for example: Berkeley. Do not abbreviate. For example: Saint Louis, not St. Louis
   4. Company: If your company or department has an &, @, or any other symbol using the shift key in its name, you must spell out the symbol or omit it to enroll. Example: XY & Z Corporation would be XYZ Corporation or XY and Z Corportation.
   5. Organizational Unit: This field is optional; but can be used to help identify certificates registered to an organization. The Organizational Unit (OU) field is the name of the department or organization unit making the request. To skip the OU field, press Enter on your keyboard.
   6. Common Name (Important!): The Common Name is the name of your web server i.e. Host + Domain Name. It looks like “www.company.com” or “company.com”. For wildcard certificate the syntax should look like *.company.com. Certificates can only be used on Web servers using the Common Name specified during enrollment. For example, a certificate for the domain “domain.com” will receive a warning if accessing a site named “secure.domain.com”, because “secure.domain.com” is different from “domain.com”.

4.  Do not enter a challenge password when generating a CSR.

5. Your CSR will now have been created.
6. A public/private key pair has now been created. The private key (myserver.com.key) is stored locally on the server machine and is used for decryption. The public portion, in the form of a Certificate Signing Request (myserver.com.csr), will be for certificate enrollment
7. We recommend that you backup your private key file to a safe location.

 

2. Apply for a certificate for your sever

Apply to your Certificate Authority (CA) for a certificate for your server.

Note: You must request an Apache format certificate from your CA

You will need the CSR generated in the steps above during this process. The exact steps required to obtain a certificate differ for each authority. You can use secure ftp (SFTP) to copy the CSR from the VisibleThread appliance (see https://support.visiblethread.com/hc/en-us/articles/214225546 for details).

When the Certificate Authority process your request they will issues a certificate to you e.g. myserver.com.crt

3. Install the certificate on the VisibleThread appliance

The exact steps required to install the certificate will vary depending on the certificate issuing authority, however a loose guideline is listed below.

1. Save the certificate and any other files provided with the certificate (e.g. key chain files) in the "/home/visiblethread/cert" directory on the VisibleThread virtual appliance (Ubuntu)or /opt/visiblethread/cert (RedHat). You can use secure FTP (SFTP) to upload any files to the VisibleThread Virtual Appliance (see http://support.visiblethread.com/entries/23470636-Accessing-the-VisibleThread-Virtual-Appliance-using-Secure-FTP for details).

2. Modify the "/etc/apache2/sites-enabled/000-default.conf" (Ubuntu) or "/etc/httpd/conf.d/visiblethread.conf" (RedHat) file to refer to the public key file, certificate file and other files provided with the certificate.

   # On Ubuntu Deployment
   sudo pico /etc/apache2/sites-enabled/000-default.conf
   # On RedHat Deployment
   sudo vi /etc/httpd/conf.d/visiblethread.conf

   You will need to enter the password for the visiblethread user
3.  The relevant section to change is listed below.

   # On Ubuntu Deployment
   SSLCertificateFile      /home/visiblethread/cert/myserver.com.crt 
   SSLCertificateKeyFile   /home/visiblethread/cert/myserver.com.key
   
   # If a chain/intermediate key is needed add the following below SSLCertificateKeyFile:
   SSLCertificateChainFile /home/visiblethread/cert/myserverchain.com.crt
   
   # On RedHat Deployment
   SSLCertificateFile      /opt/visiblethread/cert/myserver.com.crt 
   SSLCertificateKeyFile   /opt/visiblethread/cert/myserver.com.key
   
   # If a chain/intermediate key is needed add the following below SSLCertificateKeyFile:
   SSLCertificateChainFile /home/visiblethread/cert/myserverchain.com.crt

4. Save the changes to the file by typing 'Ctrl-o' and exit the editor by typing 'Ctrl-x'

5. Restart the VisibleThread application by running

   1. Ubuntu - sudo /home/visiblethread/VisibleThreadTools/vt-services.sh restart
   2. Red Hat - sudo /opt/visiblethread/VisibleThreadTools/vt-services.sh restart
6. Restart your Apache webserver.
   

   sudo service apache2 restart

4. Verify Installation Success

Open your web browser and navigate to your website (e.g. https://myserver.com). Hit Ctrl-F5 to force the browser to fully reload the website. You should be able to verify the SSL/certificate details in the address bar e.g. Firefox shows a green padlock icon which you can click on for more details.  

5. Troubleshooting Steps.

• Please ensure that you have not entered the wrong file name for steps in Section 3 Install the certificate on the VisibleThread appliance, step 3 of this document. It's encouraged to go check to make sure they are correct.
• The public certificate may be issued in several different formats. We require the certificate to be in Apache (x509) format.
  
  
• After running the below commands if successful, the certificate details will be displayed. Otherwise you will get an error message (e.g. unable to load certificate) and you will need to convert your certificate to Apache format.
  
  
• If you get "unable to load certificate" error we need to figure out what format it's in so we can convert it
  
  
• Open the cert using a text editor to see if it's human readable or in binary.
  e.g. human readable will have -----BEGIN CERTIFICATE----- followed by readable characters
  e.g. binary cert will have random characters that make no sense or "not human readable".
  
  
•  If the cert is human readable go through the list of conversions til you get information back. If the cert is in binary see DER format in the list below.

Convert your certificate to Apache format

First, we need to determine which type of certificate you have. Run through these commands until you get information back from your cert.

Pkcs12/pfx format:

Check format

openssl pkcs12 -in filename.p12 -nocerts

To convert a PFX/pkcs12 file to a PEM file that contains both the certificate and private key, the following command needs to be used:
# openssl pkcs12 -in filename.pfx -out cert.pem -nodes

Too convert to seperate files:

We can extract the private key form a PFX/pkcs12 to a PEM file with this command:
# openssl pkcs12 -in filename.pfx -nocerts -out key.pem

Exporting the certificate only:
# openssl pkcs12 -in filename.pfx -clcerts -nokeys -out cert.pem

Removing the password from the extracted private key:
# openssl rsa -in key.pem -out server.key

 

pkcs7/p7b format:

Check format

openssl pkcs7 -in myserver.com.p7b

To convert pkcs7/p7b to pem, run

# openssl pkcs7 -print_certs -in certificate.p7b -out certificate.cer.

 

DER format:

If the cert is in binary its most likely to be DER format, to confirm that it is run the following command,

openssl x509 -in MYCERT.der -inform der -text

To convert DER to PEM, run:

openssl x509 -inform der -in server.cer -out server.pem

 

PEM format:

Check format

openssl x509 -in myserver.com.crt -noout -text

If cert shows information it's the correct format and doesn't need to be converted.

 

When you find the format your cert is in and convert it to apache format revisit Section 3 of this guide to install the cert.

 

The resulting file may contain multiple certs for the chain of certificate authorities. In Apache, setting SSLCertificateKeyFile to point to this certificate file will handle verification up the certificate chain and no other configuration is required

After following all troubleshooting steps and still having issues please contact our support team by creating a ticket.