The ``keystone-manage pki_setup`` command has been removed already. This patch removes the related doc. Change-Id: Ieba6848bd205e5f09267033490cd47fc4db30414
6.6 KiB
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 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:
[ 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:
$ 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:
# 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 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 oldsigning_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.