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.
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:
Log on to the VisibleThread virtual appliance console
- 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).
You will now be asked to enter details to be entered into your CSR:
Country Name: Use the two-letter code without punctuation for country, for example: US or CA.
- State or Province: Spell out the state completely; do not abbreviate the state or province name, for example: California
- 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
- 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.
- 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.
- 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”.
Do not enter a challenge password when generating a CSR.
- Your CSR will now have been created.
- 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
- 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 http://support.visiblethread.com/entries/23470636-Accessing-the-VisibleThread-Virtual-Appliance-using-Secure-FTP 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.
Save the certificate and any other files provided with the certificate (e.g. key chain files) in the "/home/visiblethread/cert" (Ubuntu) or "/opt/visiblethread/cert/" (RedHat) directory on the VisibleThread virtual appliance. 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).
- 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 DeploymentYou will need to enter the password for the visiblethread user
sudo pico /etc/apache2/sites-enabled/000-default.conf
# On RedHat Deployment
sudo vi /etc/httpd/conf.d/visiblethread.conf
- The relevant section to change is listed below.
SSLCertificateFile /home/visiblethread/cert/myserver.com.crt SSLCertificateKeyFile /home/visiblethread/cert/myserver.com.key
# On RedHat Deployment
- Save the changes to the file by typing 'Ctrl-o' and exit the editor by typing 'Ctrl-x'
Restart the VisibleThread application by running "/home/visiblethread/VisibleThreadTools/vt-restart-server.sh"
- Restart your Apache webserver.
# On Ubuntu Deployment
sudo service apache2 restart
# On RedHat Deployment
sudo systemctl restart httpd
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.
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
openssl pkcs7 -in myserver.com.p7b
To convert pkcs7/p7b to pem, run
# openssl pkcs7 -print_certs -in certificate.p7b -out certificate.cer.
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
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.