Enterprise SSL Support

01 Enterprise SSL Support This document describes the setup of SSL (Secure Sockets 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 certificate (indicating that it was issued by a trusted party, typically a trusted root CA), that the certificate is still valid and that the certificate is related to the Application Server. 1

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. 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. 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

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 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. file. Make sure that the internet user (www/ inet_usr) has read access to the copied 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 wwsettings.xml. 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 cert.p12 The private key 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: 3

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). 3. Installing the Certificates The following sections explain how to install the certificates on Windows 2003 Server, Mac OS X and Linux. Make sure that the Common Name (CN) field contains the name of the Enterprise Server as shown in the URL that is used to connect to the server. 4

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 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. 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 certificate 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 5

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 running 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> 6

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/ cert.pem 7

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 following command: cd your_ssl_sdk_folder openssl s_client -connect your_ server_name:443 -state -debug -CAfile cacert.pem It should give an extensive report, but no errors. Step 2. Check if the Enterprise Web applications are able to run correctly by entering the URL for the Server in a Web browser (for example: https://your_server_name/enterprise). 8

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 certificate 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 generate 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 setting in the config_drupal.php file) to point to your Drupal certificate. You can configure Drupal on the same machine, but different port (e.g. 1234) which enables you to specify a different certificate 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. The your_server_name placeholder must be replaced with the machine name on which Drupal runs. 9

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.) 10

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 enable cacertpath Description SSL support needs to be explicitly set. Possible values: true, false 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 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. 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: <SCEnt:ServerInfo name="enterprise" url="http://10.0.0.1/enterprise/index.php" cryptkey="..."/> Dynamic: <SCEnt:ServerInfo name="sc Enterprise" url="http://10.0.0.1/enterprise/index.php" cryptkey="..."/> 11

6. Content Station Installation The following information applies to Content Station version 8 only. The certificate is loaded on startup of Content Station; when changing the cacertpath value you will have to restart Content Station. 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 certificates 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 internal 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 certificates only in a test environment and not for production. 12

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 certificate 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. 13

6.2 MAC OS Installation The following steps apply to running Content Station Air on Mac OS. If you get an error referring to CURL 60, your TransferServerSSLCertificates setting is not correct. 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 accessible location, for example /Library/Application Support/WoodWing. Step 2. Modify the WWSettings.xml file by adding the following option: <SCEnt:SSL enable="true" cacertpath="/library/ Application Support/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, 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 correctly. 14

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. If you get an error referring to CURL 60, your TransferServerSSLCertificates setting is not correct. If you get the install certificate dialogs when opening Content Station for a second time, the Common Name of your certificate does not match the IP address of the server. Step 1. Copy the server.pem file to an accessible location, for example C:\Documents and Settings\All Users\Application Data\WoodWing. Step 2. Modify the WWSettings.xml file by adding the following 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. 15

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 Added as a new section. 16