summaryrefslogtreecommitdiff
path: root/doc/source/admin/identity-certificates-for-pki.rst
blob: a5abb8264fcbe2a263988c22e66a355ce286b2ab (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
====================
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.