Enterprise SSL Support
This document describes the setup of SSL (SecureSockets Layer) over HTTP for Enterprise clients, servers and integrations.
1. Overview
Since the release of Enterprise version 4.1 build 90, Enterprise supports the use of SSL as a means to secure the communication between Smart Connection Enterprise clients and Enterprise Server. SSL uses a third party—the Certificate Authority (CA)—to identify one or both sides. Since Enterprise 5.0.8 build 88, SSL support is added for the Web applications as well as for letting them run via the https protocol.
Since Enterprise 7.4.1, SSL support is added for the Drupal integration. This allows Enterprise Server to connect to Drupal over HTTPS.
In short, SSL works as follows:
1. The client application performs a secure request, identified by the https prefix of the URL.
2. The Application Server sends its public key with its certificate.
3. The client application checks the identity of the Application Server by means of the certifi-cate (indicating that it was issued by a trusted party, typically a trusted root CA), that the certifi-cate is still valid and that the certificertifi-cate is related to the Application Server.
4. The client application uses the public key of the Application Server to encrypt a random generated encryption key—called the session key—and sends it to the Application Server. 5. The Application Server decrypts the session key using its private key.
6. The Application Server sends back the requested data which has been encrypted using the shared session key.
Step 7. The client decrypts the data using the shared session key.
The identity of the Application Server within the SSL protocol is checked by the client application (client authentication by the server is optional), which means that the client application needs reference to the root certificate (the cacert.p12 file) and the Application Server needs reference to an installed server certificate (the cert.p12 file) which is derived from (signed by) the same root certificate.
2. Installation for Enterprise Server
There are two ways to generate server certificates for Enterprise:
1. Using a certificate signed by the WoodWing provided CA certificate.
2. Using a certificate signed by a trusted root Certificate Authority, such as VeriSign (For more information, visit http://www.verisign.com). Each is explained in the following sections.
2.1 Generating a Server Certificate
This implementation of SSL relies on the fact that both client and server are from the same party: WoodWing. This removes the necessity to use a third party as the one trusted by both parties.
Step 1. Download and unzip the SSL.SDK.zip package from the Community site, for instance from the Enterprise 6.1 Documentation page (http://community.woodwing.net/products/ Enterprise%206.1.x/Documentation).
The files can be used for all versions of Enterprise.
The following steps are optional but if step 3 is performed, make sure that step 2 is performed first.
Step 2. Generate a new CA certificate and use that instead of the one provided by WoodWing by using the genCA script:
Mac OS: run genCA.sh
Windows: run genCA.cmd
Important: the common name (CN) must match the host name as used in URL. After a successful run, the newcerts folder will contain the following:
cert.pem The certificate in PEM format), key.pem The private key
cert.p12 The certificate and private key in PKCS#12 format, by default the password is ‘ww’).
Obviously the private keys should remain private.
Step 3. Run the genSignedCert script, and complete the questions:
Mac OS: run genSignedCert.sh
Windows: run genSigndedCert.cmd
Step 4. Copy the generated cacert.pem file to your server on <web root>/Enterprise/config/ encryptkeys. During this process, overwrite the existing file.
Make sure that the internet user (www/ inet_usr) has read access to the copied file.
This file is picked up by the Health Check (wwtest page) and Drupal integration (Server plug-in).
Future versions of the client plug-in will have a WoodWing CA certificate built-in, which removes the need for using the wwset-tings.xml.
2.2 Using a CA Signed Certificate
To use a trusted root CA signed certificate, purchase an SSL certificate from a Certificate Authority such as VeriSign (For more information, visit http://www.verisign. com).
Make sure that the Common Name (CN) field con-tains the name of the Enterprise Server as shown in the URL that is used to connect to the server.
3. Installing the Certificates
The following sections explain how to install the certifi-cates on Windows 2003 Server, Mac OS X and Linux.
3.1 Windows 2003 Server
The following is a compilation of the information found on the Microsoft Knowledge Base:
#290625 How To Configure SSL in a Windows 2000 IIS 5.0 Test Environment by Using Certificate Server 2.0
#299525 How to set up SSL by using IIS 5.0 and Certificate Server 2.0
A compilation of the information in these article is below;
To install the server certificate:
Step 1. Start the IIS Manager and then expand the Server Name so that you can view the Web sites.
Step 2. Expand again, right-click Default Web Site and click Properties.
Step 3. Click the Directory Security tab. Step 4. Under Secure Communications, click Server Certificate…
The Web Server Certificate Wizard appears. Step 5. Click Next to continue.
Step 6. In the list Select the method you want to use for this Web site, select Import a cer-tificate from a .pfx file.
Step 7. Click Next.
Step 8. Browse to the server certificate file. For server certificates derived from the WoodWing root CA certificate, browse to
the cert.p12 file. (In order to see the file, select All Files (*.*) from the File Type list.
Step 9. Type the password of the certificate. Use "ww" for server certificates derived from the WoodWing root CA.
Step 10. Use the default supplied Port number and click Next to finish the installation.
3.1.1 Enabling SSL for the Enterprise Server To enable SSL for the Enterprise Application Server, do the following:
Step 1. Start the IIS Manager and then expand the Server Name so that you can view the Web sites.
Step 2. Expand again, right-click Default Web Site and click Properties.
Step 3. Click the Directory Security tab. 4. Under Secure Communications, click Edit…
5. Select Require Secure Channel (SSL).
3.2 Mac OSX / Linux - Apache v1
The following installation instructions are written for Apache v1.3. You can check your Apache version by run-ning the following command in the Terminal: httpd -v. For Apache v2, see Section 3.3 Mac OSX / Linux - Apache v2.
Step 1. Open the /etc/httpd/httpd.conf Apache configuration file and uncomment the following options by removing the "#" character at the beginning of each line:
LoadModule ssl_module libexec/httpd/libssl.so AddModule mod_ssl.c
Step 2. If not present, create a new ssl folder in the /usr/local folder, using the following Terminal commands:
cd /usr/local sudo mkdir ssl cd ssl
Step 3. Copy the cert.pem file and the key_unenc.pem file to the /usr/local/ssl folder and apply the same access rights to those files as those of the ssl folder.
Step 4. Add the following fragment to your httpd.conf file and fill in your_server_name: Listen 443 <VirtualHost _default_:443> ServerName your_server_name SSLEngine on SSLCertificateFile /usr/local/ssl/cert.pem SSLCertificateKeyFile /usr/local/ssl/key_unenc.pem </VirtualHost>
Step 5. Restart the Web server, for example by running the following command:
sudo apachectl -k restart
(Optional) You can change the default https port 443 into something else, for example 1234. In that case you need to change the two 443 values into 1234 in your httpd.conf file, restart the Web service and run the following URL in a Web browser:
https://your_server_name:1234/Enterprise
3.3 Mac OSX / Linux - Apache v2 To enable SSL for the Apache 2, do the following: For Apache v1, see Section 3.2 Mac OSX / Linux - Apache v1.
Step 1. Open the /private/etc/apache2/ httpd.conf file and uncomment the following option by removing the "#" character at the beginning of the line:
Include /private/etc/apache2/extra/ httpd-ssl.conf
Step 2. If not present, create a new ssl folder in the /usr/local folder, using the following Terminal commands:
cd /usr/local sudo mkdir ssl cd ssl
Step 3. Copy the cert.pem file and the key_unenc.pem file to the /usr/local/ssl folder and apply the same access rights to those files as those of the ssl folder.
Step 4. The httpd-ssl.conf file should already be enabled with the following information (if not, please make any necessary changes to these settings at this time):
Listen 443
<VirtualHost _default_:443> SSLEngine on
</VirtualHost>
There are also three other settings within the <VirtualHost> settings you must modify:
ServerName your_server_name:443 SSLCertificateFile/usr/local/ssl/
SSLCertificateKeyFile/
usr/local/ssl/key_unenc.pem Step 5. Restart the Web server, for example by running the following command:
sudo apachectl -k restart
(Optional) You can change the default https port 443 into something else, for example 1234. In that case you need to change the two 443 values into 1234 in your httpd.conf file, restart the Web service and run the following URL in a Web browser:
https://your_server_name:1234/Enterprise
3.4 Test Web Server with Certificates Step 1. To check the certificates, run the fol-lowing command:
cd your_ssl_sdk_folder
openssl s_client -connect your_ server_name:443 -state -debug -CAfilecacert.pem
It should give an extensive report, but no errors.
Step 2. Check if the Enterprise Web applica-tions are able to run correctly by entering the URL for the Server in a Web browser (for exam-ple: https://your_server_name/Enterprise).
4. Drupal Installation
This section only applies to Enterprise 7.4.1 or later installations.
In order to let Drupal run on HTTPS (and thereby making the connection between Enterprise Server and Drupal secure) and set up the connection between Drupal and Enterprise Server, perform the following steps:
Step 1. Perform the following step only when the following is not true:
Enterprise Server and Drupal run on the same machine and SSL is set up for Enterprise Server
You are happy to reuse the same certifi-cate for Drupal
Step 1a. Repeat the steps from Section 2.
Installation for Enterprise Server but now for the Drupal server (see notes below).
Step 1b. Repeat the steps from Section 3.
Installing the Certificates but now for the Drupal server (see notes below).
You can choose whether or not to gener-ate the cacert.pem file. But if you do, and there is already one installed or used on <web_ root>/Enterprise/config/encryptkeys/
cacert.pem, you should not overwrite this file but create another file (for instance cacert_ drupal.pem). In that case, you need to adjust the "local_cert" option (in the DRUPAL_SITES set-ting in the config_drupal.php file) to point to your Drupal certificate.
The your_server_name placeholder must be replaced with the machine name on which Drupal runs.
You can configure Drupal on the same machine, but different port (e.g. 1234) which enables you to specify a different certifi-cate than used for Enterprise Server.
Step 2. Set up the Drupal configuration as described in the Enterprise Admin Guide, while making sure of the following:
In the config_drupal.php file, fill in the HTTPS location of Drupal in the "url" option of the DRUPAL_SITES setting.
Use the machine name as specified while creating the certificates:
'url' => 'https://your_server_name:443/ drupal/'
Step 3. Run the Publish to Drupal test of the Health Check (wwtest page). Fix any errors where necessary.
When the certificate does not match, the following type of error is shown:
Drupal - Publish error from Drupal: Error in cURL request: SSL certificate problem, verify that the CA cert is OK. Details: error:1407E086:SSL routines:SSL2_SET_CERTIFICATE:certificate verify failed
Fix this by checking your "local_cert" option in the DRUPAL_SITES setting of the config_ drupal.php file.
5. Smart Connection Client Installation For the client applications it makes no difference which method was chosen to generate the server certificate. The client simply requires the availability of the CA certificate(s).
Generated server certificates
Use either the cacert.pem file delivered with the SSL.SDK file or the file generated by yourself.
Trusted root CA signed certificates
Use the root CA certificate delivered by the Certificate Authority. This file must be in PEM format. Alternatively you can use the CA bundle file from the http://curl.haxx. se/docs/caextract.html.
5.1 Configuration
Settings need to be added to the WWSettings.xml file in order to enable SSL for the client applications.
The location of the WWSettings.xml file is:
Mac OS Enterprise v6 (or older): /Library/Preferences/ WoodWing
Enterprise v7 (or newer): /Library/Application Support/WoodWing
Windows XP Enterprise v6 (or older): C:\Documents and Settings\ All Users\Application Data\WoodWing
Enterprise v7 (or newer): C:\Documents and Settings\<username>\Local Settings\Application Data\WoodWing
This folder is hidden by default. To display this folder, change the folder options. (For more information on displaying hidden folders, see the Windows XP Help file.)
Windows Vista C:\Program Data\WoodWing
This folder is hidden by default. To display this folder, change the folder options. (For more information on displaying hidden folders, see the Windows Vista Help file.)
The WWSettings.xml file can be changed using a plain text editor such as Notepad, TextEditor or TextWrangler. Add the following setting between the <Settings> tags: <SCEnt:SSL enable="true" cacertPath="c:\cacert.pem"/> Table 5.1 shows the parameters used:
Table 5.1 SCEnt:SSL parameters
Parameter Description
enable SSL support needs to be explicitly set. Possible values: true, false cacertPath Platform specific path to the file that
contains the CA certificates, needed to verify the origin and validity of the certificate sent by the server. On Macintosh use a posix style path. Value: string
SSL will only be used for connections that have a url that starts with https://.
Encryption keys
To let a user connect to Enterprise by making use of an encryption key, add cryptkey="[key name]" to the server URL: Static: < S C E n t : S e r v e r I n f o n a m e = " E n t e r p r i s e " url="http://10.0.0.1/Enterprise/index.php" cryptkey="..."/> Dynamic: < S C E n t : S e r v e r I n f o n a m e = " S C E n t e r p r i s e " url="http://10.0.0.1/Enterprise/index.php" cryptkey="..."/> SSL Connections
Starting with Enterprise 7.6.3, Smart Connection forces SSL connections to use TLSv1 by default. This behavior can be changed by using the sslVersion attribute:
<SCEnt:SSL sslVersion="SSLv3"/> <SCEnt:SSL sslVersion="Auto"/>
The use of 'Auto' is not encouraged because of potential incompatibilities between the versions of OpenSSL used on the client and on the server. These incompatibilities result in connection failures.
6. Content Station Installation
The following information applies to Content Station version 8 only.
Content Station Air uses the internal key store of Flash to communicate with Enterprise Server. For downloading and uploading files, a key file has to be provided. There are several ways to provide the key file:
1. In a production environment, the certificate is signed by for example VeriSign or Comodo. In this scenario you do not have to provide the key file.
They key is validated against the root certificate of the certificate authority. This list of root certifi-cates is precompiled in Content Station. If you are using an old Content Station build the precompiled root certificates are maybe no longer valid, please use option 3 in that case. 2. On Mac OS, the root certificates of the inter-nal key store of the OS are also used.
3. For self-singed certificates on Windows and Mac OS, you can configure your own key file (in PEM format) and refer to it through the cacert-Path option of the WWSettings file:
<SCEnt:SSL enable="true" cacertPath="/Applications/ MAMP/conf/apache/server.pem" sslVersion="TLSv1"/> Available options for the sslVersion parameter: Auto, SSLv3, TLSv1 (default).
For security reasons, use self-signed cer-tificates only in a test environment and not for production.
The certificate is loaded on startup of Content Station; when changing the cac-ertPath value you will have to restart Content Station.
6.1 MAMP Configuration
To configure the MAMP Web server on Mac OS, perform the following steps:
It is assumed that the latest MAMP version is installed and that a fully working instance of Enterprise Server 8 is up and running.
Step 1. Open the following file:
/Applications/MAMP/conf/apache/httpd.conf Step 2. Uncomment the following options:
LoadModule ssl_module modules/mod_ ssl.so
Include /Applications/MAMP/conf/ apache/extra/httpd-ssl.conf
Step 3. Open the following file:
/Applications/MAMP/conf/extra/httpd-ssl.conf Step 4. Change the DocumentRoot option to "/Applications/MAMP/htdocs".
Step 5. Uncomment the SSLCertificateFile option and change it to:
SSLCertificateFile "/Applications/MAMP/ conf/apache/server.crt"
Step 6. Uncomment the SSLCertificateKeyFile option and change it to:
SSLCertificateKeyFile "/Applications/ MAMP/conf/apache/server.crt"
Step 7. Lookup the IP address of your server, for example 192.168.10.10. Use this for the cer-tificate and to connect to your server.
Step 8. Open a Terminal instance and execute the following commands:
cd /Applications/MAMP/conf/apache openssl genrsa -des3 -out server. key 1024
pass phrase (for example 1234) cp server.key server-pw.key
openssl rsa -in server-pw.key -out server.key
openssl req -new -key server.key -out server.csr Country: NL State: NH City:Zaandam Organization: WoodWing Section:WoodWing
Common name: The ip address of your server, for example 192.168.10.10 !
email: your email address Challenge: 1234
company name: empty
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
openssl x509 -in server.crt -out server.pem -outform PEM
Step 9. Restart your Web server.
Step 10. Open https://<your IP address>/ enterprise in a Web browser.
Because this is a self-signed certificate and not an official signed certificate (such as a VeriSign certificate) your browser will warn you that the site is not trusted.
Step 11. Continue past the warning.
The log-in page of Enterprise should appear, indicating that your server is configured correctly.
6.2 MAC OS Installation
The following steps apply to running Content Station Air on Mac OS.
It is assumed here that Content Station Air has been successfully installed. For detailed instructions, see the Enterprise Admin Guide.
Step 1. Copy the server.pem file to an acces-sible location, for example /Library/Application Support/WoodWing.
Step 2. Modify the WWSettings.xml file by add-ing the followadd-ing option:
<SCEnt:SSL enable="true" cacertPath="/Library/ A p p l i c a t i o n S u p p o r t / W o o d W i n g /s e r v e r. p e m"
sslVersion="TLSv1"/>
Step 3. Modify your serverinfo to https by changing "url="http://xxx"" to "url="https://xxx"". Step 4. Start Content Station.
Because this is the first time that Content Station is started in the new SSL environment, warnings will appear that the SSL certificates are not valid.
Step 5. Click Show Certificate.
Step 6. Select the check box Always trust “127.0.0.1” when connecting to “127.0.0.1”. Step 7. Click Continue.
Warnings for the second certificate appear. Step 8. Repeat steps 5 to 7.
Step 9. Upload a file to see if all is configured
If you get an error referring to CURL 60, your TransferServerSSLCertificates set-ting is not correct.
6.3 Windows Installation
The following steps apply to running Content Station Air on Windows.
It is assumed here that Content Station Air has been successfully installed. For detailed instructions, see the Enterprise Admin Guide.
Step 1. Copy the server.pem file to an acces-sible location, for example C:\Documents and Settings\All Users\Application Data\WoodWing. Step 2. Modify the WWSettings.xml file by add-ing the followadd-ing option:
<SCEnt:SSL enable="true" cacertPath="C:\Documents and Settings\All Users\Application Data\WoodWing\ server.pem" sslVersion="TLSv1"/>
Step 3. Modify your serverinfo to https by changing "url="http://xxx"" to "url="https://xxx"". Step 4. Start Content Station.
Because this is the first time that Content Station is started in the new SSL environment, a warning will appear that the SSL certificate is not valid.
Step 5. Click Show Certificate. Step 6. Click Install Certificate.
Warnings for the second certificate appear. Step 7. Repeat steps 5 to 7.
Step 8. Upload a file to see if all is configured correctly.
If you get an error referring to CURL 60, your TransferServerSSLCertificates set-ting is not correct.
If you get the install certificate dialogs when opening Content Station for a sec-ond time, the Common Name of your certificate does not match the IP address of the server.
7. Troubleshooting
For troubleshooting SSL, visit http://httpd.apache.org/ docs/2.0/ssl/ssl_faq.html.
8. Revisions
Version 2.0.0, September 2012 Section 6. Content Station
