Title:  Configuring Apache Rave for SSL
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

## Prerequisites

To follow these instructions you'll need a working copy of Apache Rave up and running under Tomcat 6.  Please see the [Installing Rave][1] page for instructions on how to get up and running.

These instructions are written assuming a Tomcat installation path of /temp/tomcat so you may want to use that path for testing while you follow these instructions.

Also note that these instructions were written and tested using Tomcat running on Windows.  Tomcat on other platforms *should* be exaclty the same except for startup scripts (.bat vs .sh) and file locations (c:\ vs /).

## Enabling SSL in Tomcat

These instructions demonstrate how to get Tomcat 6 running over SSL using a self signed certificate.

 - Copy the default cacerts file to /temp/tomcat (this allows you to not have to pollute your real cacerts file with test certs).
    
        cp "%JAVA_HOME%/jre/lib/security/cacerts" "/temp/tomcat/custom-cacerts"

 - Generate a self signed certificate that you'll use with Tomcat.

        "%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -validity 365 -storepass changeit -keystore /temp/tomcat/custom-cacerts
    
        What is your first and last name?  
          [Unknown]:  rave-server.example.com  
        What is the name of your organizational unit?  
          [Unknown]:  example unit  
        What is the name of your organization?  
          [Unknown]:  example organization  
        What is the name of your City or Locality?  
          [Unknown]:  example city  
        What is the name of your State or Province?  
          [Unknown]:  example state  
        What is the two-letter country code for this unit?  
          [Unknown]:  US  
        Is CN=rave-server.example.com, OU=example unit, O=example organization, L=example city, ST=example state, C=US correct?  
          [no]:  yes  
          
        Enter key password for <tomcat>  
                (RETURN if same as keystore password):  

 - Edit Tomcats startup.bat file to get the JVM to use our alternate cacerts file.  It is important for the JVM to trust our self signed certificate because Apache Rave makes HTTP requests to Shindig to fetch gadget metadata, and if those requests are over SSL then the JVM must trust the certificate being used for the SSL communication.

    (added the following line above the "call "%EXECUTABLE%" start ..." line)
    
        set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore=c:\temp\tomcat\custom-cacerts
    
 - Edit Tomcats server.xml to enable an SSL listener on port 443 using our alternate cacerts file.  By default Tomcat looks for a certificate with the alias "tomcat" which is what we used to create our self signed certificate.

    (did a search and replace of 8443 with 443)    
    (uncommented the HTTPS connector and configured it to use our custom cacerts file)
    
        <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true"
                   maxThreads="150" scheme="https" secure="true"
                   keystoreFile="c:\temp\tomcat\custom-cacerts" keystorePass="changeit"
                   clientAuth="false" sslProtocol="TLS" />

 - Startup Tomcat and verify that Apache Rave still runs properly on http://localhost:8080/portal/

 - Make sure you can access the portal login page at https://rave-server.example.com/portal
    
    Note - if you already have an authenticated session open in your browser you'll probably need to close and re-open your browser to access the login page.
    Also note that the rest of Apache Rave wont work over SSL yet.
    
## Configure Apache Rave and Shindig to run over SSL.

 - Edit the /temp/tomcat/webapps/portal/WEB-INF/classes/portal.properties file to configure Apache Rave to use SSL.

    (updated the following values at the top of the portal.properties config file with)
    
        portal.opensocial_engine.protocol=https
        portal.opensocial_engine.root=rave-server.example.com
        portal.opensocial_engine.gadget_path=/gadgets

 - Edit the /temp/tomcat/webapps/ROOT/WEB-INF/classes/rave.shindig.properties and /temp/tomcat/webapps/ROOT/WEB-INF/classes/containers/default/container.js files to configure Shindig to use SSL.
    
    Note - there may be other ways to get Shindig to use SSL but this method does work.
    Also note - the changes to container.js are a search and replace of http:// with https://
    
    (updated the following values at the top of the rave.shindig.properties config file with)
    
        shindig.host=rave-server.example.com
        shindig.port=
        shindig.contextroot=
    
 - Startup Tomcat and verify that Rave runs properly on https://rave-server.example.com/portal

## Complete diff of modified files follows

<blockquote>
diff -r tomcat-vanilla\bin\startup.bat tomcat\bin\startup.bat
<br>56c56,57
<br>< 
<br>---
<br>>  
<br>> set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore=c:\temp\tomcat\custom-cacerts
<br>
<br>diff -r tomcat-vanilla\conf\server.xml tomcat\conf\server.xml
<br>71c71
<br><                redirectPort="8443" />
<br>---
<br>>                redirectPort="443" />
<br>77c77
<br><                redirectPort="8443" />
<br>---
<br>>                redirectPort="443" />
<br>79c79
<br><     &lt;!-- Define a SSL HTTP/1.1 Connector on port 8443
<br>---
<br>>     &lt;!-- Define a SSL HTTP/1.1 Connector on port 443
<br>83,84c83
<br><     &lt;!--
<br><     &lt;Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
<br>---
<br>>     &lt;Connector port="443" protocol="HTTP/1.1" SSLEnabled="true"
<br>85a85
<br>> 			   keystoreFile="c:\temp\tomcat\custom-cacerts" keystorePass="changeit"
<br>87d86
<br><     -->
<br>90c89
<br><     &lt;Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
<br>---
<br>>     &lt;Connector port="8009" protocol="AJP/1.3" redirectPort="443" />
<br>
<br>diff -r tomcat-vanilla\webapps\portal\WEB-INF\classes\portal.properties tomcat\webapps\portal\WEB-INF\classes\portal.properties
<br>25,26c25,26
<br>< portal.opensocial_engine.protocol=http
<br>< portal.opensocial_engine.root=localhost:8080
<br>---
<br>> portal.opensocial_engine.protocol=https
<br>> portal.opensocial_engine.root=rave-server.example.com
<br>
<br>diff -r tomcat-vanilla\webapps\ROOT\WEB-INF\classes\containers\default\container.js tomcat\webapps\ROOT\WEB-INF\classes\containers\default\container.js
<br>10c10
<br><  *     http://www.apache.org/licenses/LICENSE-2.0
<br>---
<br>>  *     https://www.apache.org/licenses/LICENSE-2.0
<br>78c78
<br>< "gadgets.jsUriTemplate" : "http://%host%${CONTEXT_ROOT}/gadgets/js/%js%",
<br>---
<br>> "gadgets.jsUriTemplate" : "https://%host%${CONTEXT_ROOT}/gadgets/js/%js%",
<br>86c86
<br>< "gadgets.uri.js.host" : "http://www.example.com/",
<br>---
<br>> "gadgets.uri.js.host" : "https://www.example.com/",
<br>99c99
<br>< "gadgets.osDataUri" : "http://%host%${CONTEXT_ROOT}/rpc",
<br>---
<br>> "gadgets.osDataUri" : "https://%host%${CONTEXT_ROOT}/rpc",
<br>106,107c106,107
<br>< //"defaultShindigTestHost": "http://${SERVER_HOST}:${SERVER_PORT}",
<br>< "defaultShindigTestHost":"http://%authority%",
<br>---
<br>> //"defaultShindigTestHost": "https://${SERVER_HOST}:${SERVER_PORT}",
<br>> "defaultShindigTestHost":"https://%authority%",
<br>154c154
<br><       "urlTemplate" : "http://localhost${CONTEXT_ROOT}/gadgets/profile?{var}",
<br>---
<br>>       "urlTemplate" : "https://localhost${CONTEXT_ROOT}/gadgets/profile?{var}",
<br>159c159
<br><       "urlTemplate" : "http://localhost${CONTEXT_ROOT}/gadgets/canvas?{var}",
<br>---
<br>>       "urlTemplate" : "https://localhost${CONTEXT_ROOT}/gadgets/canvas?{var}",
<br>260c260
<br><     "path" : "http://%host%${CONTEXT_ROOT}/rpc",
<br>---
<br>>     "path" : "https://%host%${CONTEXT_ROOT}/rpc",
<br>262c262
<br><     "invalidatePath" : "http://%host%${CONTEXT_ROOT}/rpc",
<br>---
<br>>     "invalidatePath" : "https://%host%${CONTEXT_ROOT}/rpc",
<br>290c290
<br><     "endPoints" : [ "http://%host%${CONTEXT_ROOT}/rpc" ]
<br>---
<br>>     "endPoints" : [ "https://%host%${CONTEXT_ROOT}/rpc" ]
<br>
<br>diff -r tomcat-vanilla\webapps\ROOT\WEB-INF\classes\rave.shindig.properties tomcat\webapps\ROOT\WEB-INF\classes\rave.shindig.properties
<br>24,25c24,25
<br>< shindig.host=localhost
<br>< shindig.port=8080
<br>---
<br>> shindig.host=rave-server.example.com
<br>> shindig.port=
</blockquote>

[1]: installing.html