From 16aca8906fc03420e8f0616aa29545bcfb5cbc9c Mon Sep 17 00:00:00 2001
From: Alex Szebenyi <alszeb@gmail.com>
Date: Thu, 18 Dec 2014 08:52:54 -0500
Subject: [PATCH] Documentation of SSL support for RexsterHttpServer.

---
 doc/Rexster-Configuration.textile | 20 +++++++++++++
 doc/Rexster-SSL.textile           | 47 +++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 doc/Rexster-SSL.textile

diff --git a/doc/Rexster-Configuration.textile b/doc/Rexster-Configuration.textile
index b22de1c0..e557f31a 100644
--- a/doc/Rexster-Configuration.textile
+++ b/doc/Rexster-Configuration.textile
@@ -26,6 +26,7 @@ The XML configuration file has a basic structure as follows:
     <web-root>public</web-root>
     <character-set>UTF-8</character-set>
     <enable-jmx>false</enable-jmx>
+    <enable-ssl>false</enable-ssl>
     <enable-doghouse>true</enable-doghouse>
     <max-post-size>2097152</max-post-size>
     <max-header-size>8192</max-header-size>
@@ -86,6 +87,23 @@ The XML configuration file has a basic structure as follows:
         </configuration>
     </authentication>
   </security>
+  <ssl>
+    <protocol>TLS</protocol>
+    <trust-store-provider>JKS</trust-store-provider>
+    <key-store-provider>JKS</key-store-provider>
+    <trust-store></trust-store>
+    <key-store>config/ssl/serverKeyStore.jks</key-store>
+    <trust-store-password></trust-store-password>
+    <key-store-password></key-store-password>
+    <key-manager-factory>
+      <algorithm>SunX509</algorithm>
+    </key-manager-factory>
+    <trust-manager-factory>
+      <algorithm>SunX509</algorithm>
+    </trust-manager-factory>
+    <need-client-auth>false</need-client-auth>
+    <want-client-auth>false</want-client-auth>
+  </ssl>
     <metrics>
         <reporter>
             <type>jmx</type>
@@ -204,6 +222,8 @@ When configured in this fashion, Rexster accepts all incoming requests.  The oth
 
 The @<users>@ element allows specification of one or more @<user>@ child elements which each must contain a @<username>@ and @<password>@ combination.  These @<user>@ elements represent the list of users that will have access to Rexster.  
 
+The @<ssl>@ section can be used to configure SSL. See the [[Rexster SSL]] page for more information.
+
 The @<metrics>@ section configured the various realt-time monitoring options for Rexster.  See the [[Monitoring]] page for more information.
 
 h2. graphs Section 
diff --git a/doc/Rexster-SSL.textile b/doc/Rexster-SSL.textile
new file mode 100644
index 00000000..3d37e317
--- /dev/null
+++ b/doc/Rexster-SSL.textile
@@ -0,0 +1,47 @@
+Rexster communication can be secured with SSL by [[configuration|Rexster Configuration]] through @rexster.xml@.  Server and client authentication are currently supported on [[REST|Basic REST API]] and [[Dog House|the Dog House]].
+
+A typical Rexster-SSL configuration might be as follows:
+
+```xml
+<rexster>
+  ...
+  <ssl>
+    <protocol>TLS</protocol>
+    <trust-store-provider>JKS</trust-store-provider>
+    <key-store-provider>JKS</key-store-provider>
+    <trust-store></trust-store>
+    <key-store>config/ssl/serverKeyStore.jks</key-store>
+    <trust-store-password></trust-store-password>
+    <key-store-password>keyStorePassword</key-store-password>
+    <key-manager-factory>
+      <algorithm>SunX509</algorithm>
+    </key-manager-factory>
+    <trust-manager-factory>
+      <algorithm>SunX509</algorithm>
+    </trust-manager-factory>
+    <need-client-auth>false</need-client-auth>
+    <want-client-auth>false</want-client-auth>
+  </ssl>
+  ...
+</rexster>
+```
+
+Once SSL has been enabled for a server (see how below), no further action is necessary for its' communications to be secured by SSL. Clients communicating with SSL secured servers will also require appropriately configured SSL and valid certificates (if client authorization is turned on).
+
+h1. Enable SSL for HTTP Web Service
+
+After configuring SSL in the @<ssl>@ section of @rexster.xml@, enable it for HTTP calls by setting @http.enable-ssl@ to true and changing @http@ to @https@ in the @http.base-uri@ property.
+
+```xml
+<rexster>
+  <http>
+    ...
+    <base-uri>https://your-hostname</base-uri>
+    ...
+    <enable-ssl>true</enable-ssl>
+    ...
+  </http>
+  ...
+</rexster>
+```
+