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
parent
c44a9eaaeb
commit
64165b8609
@ -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
|
||||||
===============
|
===============
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user