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.
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" 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" file to refer to the public key file, certificate file and other files provided with the certificate.
sudo pico /etc/apache2/sites-enabled/000-defaultYou will need to enter the password for the visiblethread user
- The relevant section to change is listed below.
SSLCertificateFile /home/visiblethread/cert/myserver.com.crt SSLCertificateKeyFile /home/visiblethread/cert/myserver.com.key
- 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.
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.
1. 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.
2.The public certificate may be issued in several different formats. We require the certificate to be in Apache (x509) format. To check if the certificate is already in Apache format :
openssl x509 -in myserver.com.crt -noout -text
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.
Convert your certificate to Apache format
First, we need to determine which type of certificate you have.
- Check if your certificate is in pkcs12 format :
openssl pkcs12 -in filename.p12 -nocertsIf this displays the certificate details then run the following to convert it to Apache format
To convert a PFX 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
Conversion to separate PEM files
We can extract the private key form a PFX 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
- Check if your certificate is in pkcs7 format :
openssl pkcs7 -in myserver.com.p7bIf this displays the certificate details (e.g. -----BEGIN PKCS7-----) then run the following to convert it to Apache format :
openssl pkcs7 -print_certs -in myserver.com.p7b -out myserver.com.crt
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.