Month: December 2009

Version 8.4 and Higher

Follow the instructions in Article 1002 to configure HTTPS support in the Web Service.

<br>

Version 8.2 and Lower

SSL, a security system combining authentication and encryption, is used to protect communication between a web server and client. Enabling SSL on a web server allow all clients connecting to that server two key protections:

1. The client is able to identify the server. There is no way for a fake server to misrepresent itself to a client.
   
2. The communication between the client and server is encrypted, preventing a third-party from seeing what data is sent. This ensures the safety of private communication such as usernames and passwords, video data, and more.
   

NOTE: A self-signed certificate allows you to use a web browser, but it does not work with mobile devices. Only trusted third-party certificates work with mobile devices.

To use SSL in Windows with exacqVision Web Service, complete the following steps:

1. Either create a self-signed certificate, or purchase a certificate from a trusted third party. (Creating a Self-Signed SSL Certificate) COMMON NAME should be the IP address or FQDN that you use to access your exacqVision Web Service. If acquiring a third-party cert, you might need to provide them with a Certificate Signing Request (CSR) file as follows:
   
   a. Navigate to https://exacq.com/support/gencsr.php.
   
   b. Enter all fields to output a .csr file and RSA key file to a zip file. Submit this data to the CA from which you are purchasing the certificate.
   
   c. If you have purchased a chained certificate, be sure to download the appropriate intermediate bundle.
   
   d. Place the .crt file and the intermediate bundle file (also a .crt file) from your CA into the Apache\conf directory.
   
2. Rename the .crt file to server.crt and the .key file to server.key. Save the .crt and .key files to C:\Program Files (x86)\exacqVision\WebService\Apache\conf\.
   
3. Stop exacqVision Web Server using the link on the Start menu.
   
4. Open the Web Server Configuration file with Notepad as an administrator from C:\Program Files (x86)\exacqVision\WebService\Apache\conf\httpd.conf.
   
   Find the following line:
   
   LoadModule ssl_module modules/mod_ssl.so
   
   Delete any preceding pound sign (#) characters.
   
   Find the following line:
   
   Include conf/extra/httpd-ssl.conf
   
   Delete any preceding pound sign (#) characters.
   
   NOTE: Make sure your SSL Certificate File and SSL Certificate Key File are in the Apache\conf directory.
5. Open the Apache SSL Configuration file in Notepad as an administrator. The file is located at C:\Program Files (x86)\exacqVision\WebService\Apache\conf\extra\httpd-ssl.conf.
   Find the line that begins with:
   FilesMatch “…
   
   Change it to:
   
   FilesMatch “\.(cgi|shtml|phtml|php|html)$”
   
   NOTE: Those lines will also include angle brackets. Do not remove the brackets.
   
   When finished, save and close the file.
6. It is recommended, but not required, that you disable the access log for SSL, as this file can grow very large. To do this, open the Apache SSL Configuration file in Notepad as an administrator. The file is located at C:\Program Files (x86)\exacqVision\WebService\Apache\conf\extra\httpd-ssl.conf. Find the line with the following text:
   
   TransferLog “${SRVROOT}/logs/access.log”
   Change it to:#TransferLog “${SRVROOT}/logs/access.log”When finished, save and close the file.
7. Open the Web Service Configuration file in Notepad as an administrator. The file is located at C:\Program Files (x86)\exacqVision\WebService\WebService.ini.
   Add the following lines to the end of the document:
   
   [Broker]
   ssl_private_key = C:\Program Files (x86)\exacqVision\WebService\Apache\conf\server.key
   ssl_certificate = C:\Program Files (x86)\exacqVision\WebService\Apache\conf\server.crt
   
   When finished, save and close the file.
   
8. Open an exception for TCP port 443 in your firewall.
   
9. Start exacqVision Web Server using the link under the Start button.
   

<br>

Tips

1. When purchasing an SSL certificate, many providers offer an Intermediate Bundle, or additional certificates that need to be present that will link your certificate through the chain to a root certification authority. Usually the provider will also provide documentation that describes how to accomplish this with Apache, but is a good idea to ask them before or during the purchase process. Exacq is not responsible for making your certs capable of working with Apache.
   
2. The httpd-ssl.conf file contains sections for Server Certificate, Server Private Key, Server Certificate Chain, and Certificate Authority. You must modify these sections with the appropriate paths to your specific files.
   
3. It is possible to combine all the intermediate certificates that the provider might give you into one file and use that in the Server Certificate Chain section. Again, consult the provider for more information.
   
4. You should also find and modify the following line to include the name for which your certificate was issued (your server’s name) instead of:
   
   ServerName www.example.com:443

<br>

Troubleshooting

If exacqVision Web Service does not start after configuring it for SSL, complete the following steps:

1. Open the Apache error logs, found by default at C:\Program Files\exacqVision\WebService\Apache\logs\error.log.
   
2. Look for an entry similar to the following:
   
   [Wed Mar 04 09:08:54.512004 2015] [ssl:emerg] [pid 19116] AH02565: Certificate and private key www.example.com:443:0 from CERTIFCATE_FILE_NAME.crt and KEYFILE_NAME.key do not match AH00016: Configuration Failed
   
3. If you see this entry, complete the following steps:
   
   a.) Run the openssl utility (found by default at C:\Program Files\exacqVision\WebService\Apache\bin\openssl.exe).
   
   b.) Run the following commands, replacing the values in all caps with your values:
   
   openssl.exe x509 -noout -modulus -in PATH_TO_CRT | openssl md5
   openssl.exe rsa -noout -modulus -in PATH_TO_KEY | openssl md5
   openssl.exe req -noout -modulus -in PATH_TO_CSR | openssl md5
   
   For example:
   
   openssl.exe x509 -noout -modulus -in ..\conf\certificate.crt | openssl md5
   openssl.exe rsa -noout -modulus -in ..\conf\privateKey.key | openssl md5
   openssl.exe req -noout -modulus -in ..\conf\csr.csr | openssl md5
   
   c.) Compare the result values from all of the calls. Each resulting string should be identical. If the values do not match, confer with the certificate authority that issued the certificate.

NOTE: Web Sockets communication will not work using SSL encryption for Web Service versions 7.2.0 – 7.2.6.

<br>

Workaround

Disable Web Sockets in the client configuration page of the browser Client.

<br>

Resolution

Update to exacqVision Web Service version 8.4 or later.

<br>