From a461eda42f1344e1aa4019986b56e72f2ab4f9fd Mon Sep 17 00:00:00 2001 From: Dolph Mathews Date: Wed, 30 Nov 2011 10:18:57 -0600 Subject: [PATCH] Added ssl docs to index; fixed rst syntax (bug 898211) Change-Id: I21a810254c4985faad8c43b064f7cf10b3c4b4b2 --- doc/source/index.rst | 1 + doc/source/ssl.rst | 127 ++++++++++++++++++++++++++----------------- 2 files changed, 79 insertions(+), 49 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 50e01c0052..c338e57a05 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -60,6 +60,7 @@ Administration controllingservers configuringservices endpoints + ssl API Use Case Examples diff --git a/doc/source/ssl.rst b/doc/source/ssl.rst index 67190da5d5..839e951ea7 100644 --- a/doc/source/ssl.rst +++ b/doc/source/ssl.rst @@ -14,76 +14,105 @@ License for the specific language governing permissions and limitations under the License. -===================================================== -Instructions for Keystone x.509 client authentication -===================================================== - -.. toctree:: - :maxdepth: 1 +=========================== +x.509 Client Authentication +=========================== Purpose -------- -Allows the Keystone middleware to authenticate itself with the Keystone server -via an x.509 client certificate. Both Service API and Admin API may be secured +======= + +Allows the Keystone middleware to authenticate itself with the Keystone server +via an x.509 client certificate. Both Service API and Admin API may be secured with this feature. Certificates ------------- +============ + The following types of certificates are required. A set of 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: -1. ca.pem : Certificate Authority chain to validate against. -2. keystone.pem : Public certificate for Keystone server. -3. middleware-key.pem: Public and private certificate for Keystone middleware. -4. cakey.pem : Private key for the CA. -5. keystonekey.pem : Private key for the Keystone server. +ca.pem + Certificate Authority chain to validate against. + +keystone.pem + Public certificate for Keystone server. + +middleware-key.pem + Public and private certificate for Keystone middleware. + +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 +the public/private keys in the same file if you wish. These certificates are just provided as an example. -Keystone server ---------------- -By default, the Keystone server does not use SSL. To enable SSL with client authentication, +Configuration +============= + +By default, the Keystone server does not use SSL. To enable SSL with client authentication, modify the etc/keystone.conf file accordingly: -1. To enable SSL for Service API: - service_ssl = True -2. To enable SSL for Admin API: - admin_ssl = True -3. To enable SSL client authentication: - cert_required = True -4. Set the location of the Keystone certificate file (example): - certfile = /etc/keystone/ca/certs/keystone.pem -5. Set the location of the Keystone private file (example): - keyfile = /etc/keystone/ca/private/keystonekey.pem -6. Set the location of the CA chain: - ca_certs = /etc/keystone/ca/certs/ca.pem +1. To enable SSL for Service API:: + + service_ssl = True + +2. To enable SSL for Admin API:: + + admin_ssl = True + +3. To enable SSL client authentication:: + + cert_required = True + +4. Set the location of the Keystone certificate file (example):: + + certfile = /etc/keystone/ca/certs/keystone.pem + +5. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/private/keystonekey.pem + +6. Set the location of the CA chain:: + + ca_certs = /etc/keystone/ca/certs/ca.pem Middleware ----------- -Add the following to your middleware configuration to support x.509 client authentication. -If cert_required is set to False on the keystone server, the certfile and keyfile parameters +========== + +Add the following to your middleware configuration to support x.509 client authentication. +If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters in steps 3) and 4) may be commented out. -1. Specify 'https' as the auth_protocol: - auth_protocol = https +1. Specify 'https' as the auth_protocol:: + + auth_protocol = https + 2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured - for SSL: - auth_uri = https://localhost:5000/ -3. Set the location of the middleware certificate file (example): - certfile = /etc/keystone/ca/certs/middleware-key.pem -4. Set the location of the Keystone private file (example): - keyfile = /etc/keystone/ca/certs/middleware-key.pem - -For an example, take a look at the 'echo.ini' middleware configuration for the 'echo' example + for SSL:: + + auth_uri = https://localhost:5000/ + +3. Set the location of the middleware certificate file (example):: + + certfile = /etc/keystone/ca/certs/middleware-key.pem + +4. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/certs/middleware-key.pem + +For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example service in the examples/echo directory. Testing -------- -You can test out how it works by using the 'echo' example service in the examples/echo directory -and the certficates included in the examples/ssl directory. Invoke the echo_client.py with -the path to the client certificate: +======= + +You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory +and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with +the path to the client certificate:: - python echo_client.py -s + python echo_client.py -s