Merge "Remove Certificates for PKI guide"
This commit is contained in:
commit
cd5088e06c
|
@ -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.
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue