From 64165b8609e7c4ccad28e91c75ef5366376fcac4 Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Tue, 25 Jul 2017 22:03:50 +0000 Subject: [PATCH] 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 --- doc/source/configuration.rst | 110 ----------------------------------- 1 file changed, 110 deletions(-) diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index a97cc7163f..3d734d9937 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -401,116 +401,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 ===============