Using SSL with Web Interface

User Manuals > Web Interface > Using SSL with Web Interface

CommitCRM Web Interface supports the ability to accept SSL connections (https rather than http).

Using SSL with CommitCRM Web Interface is OPTIONAL. You can use CommitCRM Web Interface without setting up SSL.

The first step you should take if you want to use SSL with CommitCRM Web Interface is to obtain SSL certificates from an authorized SSL authority such as Verisign or Thawte.

If you'd like to read a SSL Certificate creation tutorial, please click here.

Saving the Certificates Files

CommitCRM requires that your certificates files be in the .pem file format. You should have three certificates files with the following names:

Key.pem
Cert.pem
Root.pem

Place your certificates files in the following folder:

<Installation_DIR>\CommitCRM\WebInterface

If your certificates are in another file format, convert them to the .pem file format. Read the SSL Troubleshooting to see how to convert certain types of SSL certificate file formats.

Activating SSL with CommitCRM

You need to instruct CommitCRM Web Interface to use SSL. To do so, you must edit the following file:
<Installation_DIR>\CommitCRM\WebInterface\CommitWebInterface.ini

Change the token settings in the above file to Yes as follows:
UseSSLEncryption=Y

Setting the SSL Port

The SSL communication between users/browsers and CommitCRM Web Interface uses a dedicated port.

Set a port number for CommitCRM Web Interface. This port should not be in use by any other application or service.

We recommend using the CommitCRM default port for SSL: 4962.

If you decide to use another port, make sure that:

1. You select a DIFFERENT port than the one used for standard connections (ServerPort).
2. You select a port value other than the standard SSL port (443) which is probably already in use on your server (by IIS for example).

To configure the SSL port, set the SSLPort token value in the following settings file:
<Installation_DIR>\CommitCRM\WebInterface\CommitWebInterface.ini

Important Note:
If you use a firewall, proxy, etc., it is recommended that you open Port 4962 in order to allow a connection to be established with CommitCRM Web Interface.
If this port is blocked by a firewall, a connection cannot be established.

Setting SSL Certificate Password

If you have a password for your SSL Certificate (SSL Certificate passwords are optional), enter the password for the SSlPassword token in:
<Installation_DIR>\CommitCRM\WebInterface\CommitWebInterface.ini

Modifying the Login Page to Use SSL

To use an SSL secure connection, modify your login page as follows:

You should change:

• Http to Https

• Standard Port (default 4961) to the SSL Port (default 4962)

For example:
If you've used the predefined login page (as described in section C.(1) above)the link, from your web site, to the secure login page should appear as follows:

<A HREF="https://127.0.0.1:4962">Click to login</A>

If you have embedded the login fields on one of your web pages (as described in section C.(2) above), modify the JavaScript used to post the login request as follows:

Original: Method="post" action="http://127.0.0.1:4961"
Modified: Method="post" action="https://127.0.0.1:4962"

SSL Troubleshooting

Note:
The Web Interface Installation Troubleshooting section of this document is valid for SSL settings as well. Make sure you read it as well.

This section only deals with SSL specific issues:

Preparing SSL Certificate files (including converting them to the .pem file format if needed)

• General Information

This issue is relevant only when you configure CommitCRM Web Interface to use SSL. CommitCRM requires that your certificate files all have the .pem format.

If your certificates are in another format, convert them to the .pem format by following these instructions:

Note: This procedure assumes that you have already received your key and certificate pair from a Certificate Authority (like Verisign or Thawte) and that you have installed them in Microsoft Internet Explorer under the Personal Certificates tab.

Note 2: To install the certificates in Internet Explorer, follow these instructions:
Open Internet Options window: Internet Explorer > Tools > Internet Options
Navigate to the: Content tab
Click on the "Certificates" button
The Certificates Window dialog box will open.
Navigate to the Personal tab, select the Import option and follow the wizard to install your certificate.

• Export Certificate

The first step is to export your certificate to a .pfx file format.
Open Internet Options window: Internet Explorer > Tools > Internet Options
Navigate to the Content tab.
Click on the Certificates.
The Certificates Window dialog box will open.
Navigate to the Personal tab, select your installed certificate and select Export.
Follow the wizard and select to export it as a .pfx file (Personal Exchange Format).
You may optionally protect it with a password.

• Convert the exported .pfx file to a .pem format

To convert the .pfx file to a .pem file, you need to use a utility called openssl.exe.
The utility can be downloaded from CommitCRM's web site at the following URL:
http://www.CommitCRM.com/downloads/openssl.exe

After downloading this file and saving it to your disk, open a command window and navigate to the folder where the utility is stored. Run the following command:

openssl.exe pkcs12 –in <your file>.pfx –out <your file>.pem

Where <your file> is the name of the file created during the export phase.

Openssl.exe will prompt you for a password. Enter it if you used one during the export phase, or leave it blank if you did not specify one.
It will also prompt you for a new password for the .pem file. This is optional, but if you protect it with a password be sure to enter the SSLPassword token in the CommitWebInterface.ini file as explained above.

• Splitting the .pem file

Now it is time to split the newly created .pem file into the different files required by Commit Web Interface.

If you examine the new .pem file with Notepad, you will notice that it consists of two parts:

1. The private key
2. the certificate (public key) part

Using Notepad, create a file called Key.pem
Into this file, paste everything between AND including these two statements:

-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----

Using Notepad create a file named: Cert.pem Into this file, paste everything between AND including these two statements:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

The final stage is to obtain the Root.pem file.
This is the Certificate Authority certificate file. You can obtain this from Internet Explorer > Tools > Internet Options.
Navigate to the Content tab and click on Certificates.
In Trusted Root Certificate Authority tab, select the Authority that issued your certificate and the Export it in Base64 (cer) format.

The exported file format is the SAME as the .pem format, so after exporting it simply rename the file Root.pem and save it with the other certificate file in folder
<Installation_DIR>\CommitCRM\WebInterface

See Also

• Web Interface
• Troubleshooting