Consolidate certificate docs to admin-guide

The admin-guide and configuration.rst both had separate sections
that detailed certificate documentation. Much of the documentation
was exactly the same. Now that keystone owns it's own admin-guide,
we can remove the duplication and simplify our docs.

Change-Id: I387902723637174c259ff421083a2933942f07fd
This commit is contained in:
Lance Bragstad 2017-07-25 22:03:50 +00:00
parent c44a9eaaeb
commit 64165b8609

View File

@ -401,116 +401,6 @@ following property:
invalid, so typically the generator selection should be considered invalid, so typically the generator selection should be considered
immutable for a given installation. immutable for a given installation.
Certificates for PKI
====================
PKI stands for Public Key Infrastructure. Tokens are documents,
cryptographically signed using the X509 standard. In order to work correctly
token generation requires a public/private key pair. The public key must be
signed in an X509 certificate, and the certificate used to sign it must be
available as Certificate Authority (CA) certificate. These files can be either
externally generated or generated using the ``keystone-manage`` utility.
The files used for signing and verifying certificates are set in the keystone
configuration file. The private key should only be readable by the system user
that will run keystone. The values that specify the certificates are under the
``[signing]`` section of the configuration file. The configuration values are:
* ``certfile`` - Location of certificate used to verify tokens. Default is
``/etc/keystone/ssl/certs/signing_cert.pem``
* ``keyfile`` - Location of private key used to sign tokens. Default is
``/etc/keystone/ssl/private/signing_key.pem``
* ``ca_certs`` - Location of certificate for the authority that issued the
above certificate. Default is ``/etc/keystone/ssl/certs/ca.pem``
Signing Certificate Issued by External CA
-----------------------------------------
You may use a signing certificate issued by an external CA instead of generated
by ``keystone-manage``. However, certificate issued by external CA must satisfy
the following conditions:
* all certificate and key files must be in Privacy Enhanced Mail (PEM) format
* private key files must not be protected by a password
The basic workflow for using a signing certificate issued by an external CA
involves:
1. `Request Signing Certificate from External CA`_
2. Convert certificate and private key to PEM if needed
3. `Install External Signing Certificate`_
Request Signing Certificate from External CA
--------------------------------------------
One way to request a signing certificate from an external CA is to first
generate a PKCS #10 Certificate Request Syntax (CRS) using OpenSSL CLI.
First create a certificate request configuration file (e.g. ``cert_req.conf``):
.. code-block:: ini
[ req ]
default_bits = 2048
default_keyfile = keystonekey.pem
default_md = default
prompt = no
distinguished_name = distinguished_name
[ distinguished_name ]
countryName = US
stateOrProvinceName = CA
localityName = Sunnyvale
organizationName = OpenStack
organizationalUnitName = Keystone
commonName = Keystone Signing
emailAddress = keystone@openstack.org
Then generate a CRS with OpenSSL CLI. **Do not encrypt the generated private
key. The -nodes option must be used.**
For example:
.. code-block:: bash
$ openssl req -newkey rsa:2048 -keyout signing_key.pem -keyform PEM -out signing_cert_req.pem -outform PEM -config cert_req.conf -nodes
If everything is successfully, you should end up with ``signing_cert_req.pem``
and ``signing_key.pem``. Send ``signing_cert_req.pem`` to your CA to request a
token signing certificate and make sure to ask the certificate to be in PEM
format. Also, make sure your trusted CA certificate chain is also in PEM
format.
Install External Signing Certificate
------------------------------------
Assuming you have the following already:
* ``signing_cert.pem`` - (Keystone token) signing certificate in PEM format
* ``signing_key.pem`` - corresponding (non-encrypted) private key in PEM format
* ``cacert.pem`` - trust CA certificate chain in PEM format
Copy the above to your certificate directory. For example:
.. code-block:: bash
$ mkdir -p /etc/keystone/ssl/certs
$ cp signing_cert.pem /etc/keystone/ssl/certs/
$ cp signing_key.pem /etc/keystone/ssl/certs/
$ cp cacert.pem /etc/keystone/ssl/certs/
$ chmod -R 700 /etc/keystone/ssl/certs
**Make sure the certificate directory is root-protected.**
If your certificate directory path is different from the default
``/etc/keystone/ssl/certs``, make sure it is reflected in the ``[signing]``
section of the configuration file.
Service Catalog Service Catalog
=============== ===============