Merge "blueprint 2-way-ssl"

2 files changed, 59 insertions, 0 deletions

diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index 9095b7c0..f6fb0239 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -60,6 +60,7 @@ values are organized into the following sections:
 * ``[catalog]`` - service catalog driver configuration
 * ``[token]`` - token driver configuration
 * ``[policy]`` - policy system driver configuration for RBAC
+* ``[ssl]`` - SSL configuration
 
 The Keystone configuration file is expected to be named ``keystone.conf``.
 When starting keystone, you can specify a different configuration file to
@@ -149,6 +150,58 @@ choosing the output levels and formats.
 .. _Paste: http://pythonpaste.org/
 .. _`python logging module`: http://docs.python.org/library/logging.html
 
+SSL
+---
+
+Keystone may be configured to support 2-way SSL out-of-the-box.  The x509
+certificates used by Keystone must be obtained externally and configured for use
+with Keystone as described in this section.  However, a set of sample certficates
+is provided in the examples/ssl directory with the Keystone distribution for testing.
+Here is the description of each of them and their purpose:
+
+Types of certificates
+^^^^^^^^^^^^^^^^^^^^^
+
+ca.pem
+    Certificate Authority chain to validate against.
+
+keystone.pem
+    Public certificate for Keystone server.
+
+middleware.pem
+    Public and private certificate for Keystone middleware/client.
+
+cakey.pem
+    Private key for the CA.
+
+keystonekey.pem
+    Private key for the Keystone server.
+
+Note that you may choose whatever names you want for these certificates, or combine
+the public/private keys in the same file if you wish.  These certificates are just
+provided as an example.
+
+Configuration
+^^^^^^^^^^^^^
+
+To enable SSL with client authentication, modify the etc/keystone.conf file accordingly
+under the [ssl] section.  SSL configuration example using the included sample
+certificates::
+
+    [ssl]
+    enable = True
+    certfile = <path to keystone.pem>
+    keyfile = <path to keystonekey.pem>
+    ca_certs = <path to ca.pem>
+    cert_required = True
+
+* ``enable``:  True enables SSL.  Defaults to False.
+* ``certfile``:  Path to Keystone public certificate file.
+* ``keyfile``:  Path to Keystone private certificate file.  If the private key is included in the certfile, the keyfile maybe omitted.
+* ``ca_certs``:  Path to CA trust chain.
+* ``cert_required``:  Requires client certificate.  Defaults to False.
+
+
 Sample Configuration Files
 --------------------------
 
diff --git a/doc/source/middlewarearchitecture.rst b/doc/source/middlewarearchitecture.rst
index 9216719b..dc0b1d53 100644
--- a/doc/source/middlewarearchitecture.rst
+++ b/doc/source/middlewarearchitecture.rst
@@ -133,6 +133,9 @@ a WSGI component. Example for the auth_token middleware::
     admin_tenant_name = service
     ;Uncomment next line and check ip:port to use memcached to cache tokens
     ;memcache_servers = 127.0.0.1:11211
+    ;Uncomment next 2 lines if Keystone server is validating client cert
+    certfile = <path to middleware public cert>
+    keyfile = <path to middleware private cert>
 
 Configuration Options
 ---------------------
@@ -153,6 +156,9 @@ Configuration Options
 * ``auth_port``: (optional, default `35357`) the port used to validate tokens
 * ``auth_protocol``: (optional, default `https`)
 * ``auth_uri``: (optional, defaults to `auth_protocol`://`auth_host`:`auth_port`)
+* ``certfile``: (required, if Keystone server requires client cert)
+* ``keyfile``: (required, if Keystone server requires client cert)  This can be
+  the same as the certfile if the certfile includes the private key.
 
 Caching for improved response
 -----------------------------