Merge "Consolidate certificate docs to admin-guide"

This commit is contained in:
Jenkins 2017-08-09 14:12:09 +00:00 committed by Gerrit Code Review
commit 6167850d12
1 changed files with 0 additions and 110 deletions

View File

@ -313,116 +313,6 @@ following property:
invalid, so typically the generator selection should be considered
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
===============