From d46f58fdd9e03fdd5fd62f780bb952008965e23d Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Tue, 11 Dec 2018 16:06:35 +0100 Subject: [PATCH] Remove Certificates for PKI guide The "Certificates for PKI" guide is about generating certificate pairs for signing PKI tokens, which we don't support anymore. Remove the crufty guide. Change-Id: I0aff718cf580892d3e5378c6705c089f496c88fd --- doc/source/admin/certificates-for-pki.rst | 198 ---------------------- doc/source/admin/index.rst | 1 - 2 files changed, 199 deletions(-) delete mode 100644 doc/source/admin/certificates-for-pki.rst diff --git a/doc/source/admin/certificates-for-pki.rst b/doc/source/admin/certificates-for-pki.rst deleted file mode 100644 index a5abb8264f..0000000000 --- a/doc/source/admin/certificates-for-pki.rst +++ /dev/null @@ -1,198 +0,0 @@ -==================== -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 a Certificate Authority (CA) -certificate. These files should be externally generated. The files need to -be in the locations specified by the top level Identity service -configuration file ``/etc/keystone/keystone.conf`` as specified in the -above section. Additionally, the private key should only be readable by -the system user that will run the Identity service. - - -.. warning:: - - The certificates can be world readable, but the private key cannot - be. The private key should only be readable by the account that is - going to sign tokens. - -The values that specify where to read 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``. - -- ``ca_key`` - Location of the private key used by the CA. Default is - ``/etc/keystone/ssl/private/cakey.pem``. - -- ``key_size`` - Default is ``2048``. - -- ``valid_days`` - Default is ``3650``. - -- ``cert_subject`` - Certificate subject (auto generated certificate) for token signing. - Default is ``/C=US/ST=Unset/L=Unset/O=Unset/CN=www.example.com``. - -.. warning:: - - Keystone utilities do not support to ability to generate certificates from - Pike, and the related command :command:`keystone-manage pki_setup` has been - removed as well. So most of the configuration options above are useless now. - To keep backwards compatibility, they are still supported in Keystone - server. Only ``certfile`` and ``keyfile`` are used to get revocation list - (GET, HEAD /v3/auth/tokens/OS-PKI/revoked). And ``ca_certs`` is for get or - list CA certificate (GET, HEAD /v3/OS-SIMPLE-CERT/). - -Sign certificate issued by external CA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A certificate issued by an 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 - -When using a signing certificate issued by an external CA, you do not -need to specify ``key_size``, ``valid_days``, and ``ca_password`` as -they will be ignored. - -The basic workflow for using a signing certificate issued by an external -CA involves: - -#. Request Signing Certificate from External CA - -#. Convert certificate and private key to PEM if needed - -#. Install External Signing Certificate - -Request a signing certificate from an 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. - -Create a certificate request configuration file. For example, create the -``cert_req.conf`` file, as follows: - -.. code-block:: ini - - [ req ] - default_bits = 4096 - default_keyfile = keystonekey.pem - default_md = sha256 - - 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. You must use the -nodes option.** - -For example: - -.. code-block:: console - - $ openssl req -newkey rsa:1024 -keyout signing_key.pem -keyform PEM \ - -out signing_cert_req.pem -outform PEM -config cert_req.conf -nodes - -If everything is successful, 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 an 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:: console - - # 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 - -.. note:: - - Make sure the certificate directory is only accessible by root. - -.. note:: - - The procedure of copying the key and cert files may be improved if - done after first running :command:`keystone-manage pki_setup` since this - command also creates other needed files, such as the ``index.txt`` - and ``serial`` files. - - Also, when copying the necessary files to a different server for - replicating the functionality, the entire directory of files is - needed, not just the key and cert files. - -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. - -Switching out expired signing certificates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following procedure details how to switch out expired signing -certificates with no cloud outages. - -#. Generate a new signing key. - -#. Generate a new certificate request. - -#. Sign the new certificate with the existing CA to generate a new - ``signing_cert``. - -#. Append the new ``signing_cert`` to the old ``signing_cert``. Ensure the - old certificate is in the file first. - -#. Remove all signing certificates from all your hosts to force OpenStack - Compute to download the new ``signing_cert``. - -#. Replace the old signing key with the new signing key. Move the new - signing certificate above the old certificate in the ``signing_cert`` - file. - -#. After the old certificate reads as expired, you can safely remove the - old signing certificate from the file. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index fe52debad8..213e98eb9d 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -18,7 +18,6 @@ command-line client. bootstrap.rst cli-manage-projects-users-and-roles.rst cli-keystone-manage-services.rst - certificates-for-pki.rst domain-specific-config.rst url-safe-naming.rst case-insensitive.rst