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
|
bootstrap.rst
|
||||||
cli-manage-projects-users-and-roles.rst
|
cli-manage-projects-users-and-roles.rst
|
||||||
cli-keystone-manage-services.rst
|
cli-keystone-manage-services.rst
|
||||||
certificates-for-pki.rst
|
|
||||||
domain-specific-config.rst
|
domain-specific-config.rst
|
||||||
url-safe-naming.rst
|
url-safe-naming.rst
|
||||||
case-insensitive.rst
|
case-insensitive.rst
|
||||||
|
|
Loading…
Reference in New Issue