267bca2f5a
Updated PKI generation example to comply with current best practices. Changed key size to 4096 and hash to sha256. Updated both XML and RST. Change-Id: I3d0cb977c87c3fe2c22b63c0790bb06f6215ada2 Closes-Bug: #1480313
306 lines
16 KiB
XML
306 lines
16 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:id="certificates-for-pki">
|
|
<?dbhtml stop-chunking?>
|
|
<title>Certificates for PKI</title>
|
|
<para>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 can be generated either using the
|
|
<command>keystone-manage</command> utility, or externally
|
|
generated. The files need to be in the locations specified by
|
|
the top level Identity Service configuration file
|
|
<filename>keystone.conf</filename> as specified in the
|
|
above section. Additionally, the private key should only be
|
|
readable by the system user that will run the Identity
|
|
Service.</para>
|
|
<warning>
|
|
<para>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. When generating
|
|
files with the <command>keystone-manage
|
|
pki_setup</command> command, your best option is to
|
|
run as the pki user. If you run <command>keystone-manage</command>
|
|
as root, you can append <parameter>--keystone-user</parameter>
|
|
and <parameter>--keystone-group</parameter>
|
|
parameters to set the user name and group keystone is going
|
|
to run under.</para>
|
|
</warning>
|
|
<para>The values that specify where to read the certificates are
|
|
under the <literal>[signing]</literal> section of the
|
|
configuration file. The configuration values are:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>certfile</literal> - Location of certificate
|
|
used to verify tokens. Default is
|
|
<literal>/etc/keystone/ssl/certs/signing_cert.pem</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>keyfile</literal> - Location of private key
|
|
used to sign tokens. Default is
|
|
<literal>/etc/keystone/ssl/private/signing_key.pem</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ca_certs</literal> - Location of certificate
|
|
for the authority that issued the above certificate.
|
|
Default is
|
|
<literal>/etc/keystone/ssl/certs/ca.pem</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ca_key</literal> - Location of the private key
|
|
used by the CA. Default is
|
|
<literal>/etc/keystone/ssl/private/cakey.pem</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>key_size</literal> - Default is
|
|
<literal>2048</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>valid_days</literal> - Default is
|
|
<literal>3650</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>cert_subject</literal> - Certificate subject (auto
|
|
generated certificate) for token signing. Default is
|
|
<literal>/C=US/ST=Unset/L=Unset/O=Unset/CN=www.example.com</literal>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>When generating certificates with the
|
|
<command>keystone-manage pki_setup</command> command, the
|
|
<literal>ca_key</literal>, <literal>key_size</literal>, and
|
|
<literal>valid_days</literal> configuration options are used.
|
|
</para>
|
|
<para>If the <command>keystone-manage pki_setup</command> command
|
|
is not used to generate certificates, or you are providing
|
|
your own certificates, these values do not need
|
|
to be set.</para>
|
|
<para>If
|
|
<literal>provider=keystone.token.providers.uuid.Provider</literal> in
|
|
the <literal>[token]</literal> section of the keystone configuration, a
|
|
typical token looks like
|
|
<literal>53f7f6ef0cc344b5be706bcc8b1479e1</literal>. If
|
|
<literal>provider=keystone.token.providers.pki.Provider</literal>, a
|
|
typical token is a much longer string, such as:</para>
|
|
<screen>MIIKtgYJKoZIhvcNAQcCoIIKpzCCCqMCAQExCTAHBgUrDgMCGjCCCY8GCSqGSIb3DQEHAaCCCYAEggl8eyJhY2Nlc3MiOiB7InRva2VuIjogeyJpc3N1ZWRfYXQiOiAiMjAxMy0wNS0z
|
|
MFQxNTo1MjowNi43MzMxOTgiLCAiZXhwaXJlcyI6ICIyMDEzLTA1LTMxVDE1OjUyOjA2WiIsICJpZCI6ICJwbGFjZWhvbGRlciIsICJ0ZW5hbnQiOiB7ImRlc2NyaXB0aW9uIjogbnVs
|
|
bCwgImVuYWJsZWQiOiB0cnVlLCAiaWQiOiAiYzJjNTliNGQzZDI4NGQ4ZmEwOWYxNjljYjE4MDBlMDYiLCAibmFtZSI6ICJkZW1vIn19LCAic2VydmljZUNhdGFsb2ciOiBbeyJlbmRw
|
|
b2ludHMiOiBbeyJhZG1pblVSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4xMDA6ODc3NC92Mi9jMmM1OWI0ZDNkMjg0ZDhmYTA5ZjE2OWNiMTgwMGUwNiIsICJyZWdpb24iOiAiUmVnaW9u
|
|
T25lIiwgImludGVybmFsVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4Nzc0L3YyL2MyYzU5YjRkM2QyODRkOGZhMDlmMTY5Y2IxODAwZTA2IiwgImlkIjogIjFmYjMzYmM5M2Y5
|
|
ODRhNGNhZTk3MmViNzcwOTgzZTJlIiwgInB1YmxpY1VSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4xMDA6ODc3NC92Mi9jMmM1OWI0ZDNkMjg0ZDhmYTA5ZjE2OWNiMTgwMGUwNiJ9XSwg
|
|
ImVuZHBvaW50c19saW5rcyI6IFtdLCAidHlwZSI6ICJjb21wdXRlIiwgIm5hbWUiOiAibm92YSJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3
|
|
LjEwMDozMzMzIiwgInJlZ2lvbiI6ICJSZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjMzMzMiLCAiaWQiOiAiN2JjMThjYzk1NWFiNDNkYjhm
|
|
MGU2YWNlNDU4NjZmMzAiLCAicHVibGljVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDozMzMzIn1dLCAiZW5kcG9pbnRzX2xpbmtzIjogW10sICJ0eXBlIjogInMzIiwgIm5hbWUi
|
|
OiAiczMifSwgeyJlbmRwb2ludHMiOiBbeyJhZG1pblVSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4xMDA6OTI5MiIsICJyZWdpb24iOiAiUmVnaW9uT25lIiwgImludGVybmFsVVJMIjog
|
|
Imh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo5MjkyIiwgImlkIjogIjczODQzNTJhNTQ0MjQ1NzVhM2NkOTVkN2E0YzNjZGY1IiwgInB1YmxpY1VSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4x
|
|
MDA6OTI5MiJ9XSwgImVuZHBvaW50c19saW5rcyI6IFtdLCAidHlwZSI6ICJpbWFnZSIsICJuYW1lIjogImdsYW5jZSJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6
|
|
Ly8xOTIuMTY4LjI3LjEwMDo4Nzc2L3YxL2MyYzU5YjRkM2QyODRkOGZhMDlmMTY5Y2IxODAwZTA2IiwgInJlZ2lvbiI6ICJSZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDov
|
|
LzE5Mi4xNjguMjcuMTAwOjg3NzYvdjEvYzJjNTliNGQzZDI4NGQ4ZmEwOWYxNjljYjE4MDBlMDYiLCAiaWQiOiAiMzQ3ZWQ2ZThjMjkxNGU1MGFlMmJiNjA2YWQxNDdjNTQiLCAicHVi
|
|
bGljVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4Nzc2L3YxL2MyYzU5YjRkM2QyODRkOGZhMDlmMTY5Y2IxODAwZTA2In1dLCAiZW5kcG9pbnRzX2xpbmtzIjogW10sICJ0eXBl
|
|
IjogInZvbHVtZSIsICJuYW1lIjogImNpbmRlciJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4NzczL3NlcnZpY2VzL0FkbWluIiwg
|
|
InJlZ2lvbiI6ICJSZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjg3NzMvc2VydmljZXMvQ2xvdWQiLCAiaWQiOiAiMmIwZGMyYjNlY2U4NGJj
|
|
YWE1NDAzMDMzNzI5YzY3MjIiLCAicHVibGljVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4NzczL3NlcnZpY2VzL0Nsb3VkIn1dLCAiZW5kcG9pbnRzX2xpbmtzIjogW10sICJ0
|
|
eXBlIjogImVjMiIsICJuYW1lIjogImVjMiJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDozNTM1Ny92Mi4wIiwgInJlZ2lvbiI6ICJS
|
|
ZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjUwMDAvdjIuMCIsICJpZCI6ICJiNTY2Y2JlZjA2NjQ0ZmY2OWMyOTMxNzY2Yjc5MTIyOSIsICJw
|
|
dWJsaWNVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjUwMDAvdjIuMCJ9XSwgImVuZHBvaW50c19saW5rcyI6IFtdLCAidHlwZSI6ICJpZGVudGl0eSIsICJuYW1lIjogImtleXN0
|
|
b25lIn1dLCAidXNlciI6IHsidXNlcm5hbWUiOiAiZGVtbyIsICJyb2xlc19saW5rcyI6IFtdLCAiaWQiOiAiZTVhMTM3NGE4YTRmNDI4NWIzYWQ3MzQ1MWU2MDY4YjEiLCAicm9sZXMi
|
|
OiBbeyJuYW1lIjogImFub3RoZXJyb2xlIn0sIHsibmFtZSI6ICJNZW1iZXIifV0sICJuYW1lIjogImRlbW8ifSwgIm1ldGFkYXRhIjogeyJpc19hZG1pbiI6IDAsICJyb2xlcyI6IFsi
|
|
YWRiODM3NDVkYzQzNGJhMzk5ODllNjBjOTIzYWZhMjgiLCAiMzM2ZTFiNjE1N2Y3NGFmZGJhNWUwYTYwMWUwNjM5MmYiXX19fTGB-zCB-AIBATBcMFcxCzAJBgNVBAYTAlVTMQ4wDAYD
|
|
VQQIEwVVbnNldDEOMAwGA1UEBxMFVW5zZXQxDjAMBgNVBAoTBVVuc2V0MRgwFgYDVQQDEw93d3cuZXhhbXBsZS5jb20CAQEwBwYFKw4DAhowDQYJKoZIhvcNAQEBBQAEgYCAHLpsEs2R
|
|
nouriuiCgFayIqCssK3SVdhOMINiuJtqv0sE-wBDFiEj-Prcudqlz-n+6q7VgV4mwMPszz39-rwp+P5l4AjrJasUm7FrO-4l02tPLaaZXU1gBQ1jUG5e5aL5jPDP08HbCWuX6wr-QQQB
|
|
SrWY8lF3HrTcJT23sZIleg==</screen>
|
|
<section xml:id="signing-certificate-issued-by-external-ca">
|
|
<title>Sign certificate issued by external CA</title>
|
|
<para>You can use a signing certificate issued by an external
|
|
CA instead of generated by
|
|
<command>keystone-manage</command>. However, a
|
|
certificate issued by an external CA must satisfy the
|
|
following conditions:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>All certificate and key files must be in Privacy
|
|
Enhanced Mail (PEM) format</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Private key files must not be protected by a
|
|
password</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>When using a signing certificate issued by an
|
|
external CA, you do not need to specify
|
|
<literal>key_size</literal>,
|
|
<literal>valid_days</literal>, and
|
|
<literal>ca_password</literal> as they will be
|
|
ignored.</para>
|
|
<para>The basic workflow for using a signing certificate
|
|
issued by an external CA involves:</para>
|
|
<orderedlist numeration="arabic">
|
|
<listitem>
|
|
<para>Request Signing Certificate from External CA
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Convert certificate and private key to PEM if
|
|
needed</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Install External Signing Certificate</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
<section xml:id="request-signing-certificate-from-external-ca">
|
|
<title>Request a signing certificate from an external
|
|
CA</title>
|
|
<para>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.</para>
|
|
<para>Create a certificate request configuration file. For
|
|
example, create the <filename>cert_req.conf</filename>
|
|
file, as follows:</para>
|
|
<programlisting language="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
|
|
</programlisting>
|
|
<para>Then generate a CRS with OpenSSL CLI. <emphasis
|
|
role="strong">Do not encrypt the generated private
|
|
key. Must use the -nodes option.</emphasis>
|
|
</para>
|
|
<para>For example:</para>
|
|
<screen><prompt>$</prompt> <userinput>openssl req -newkey rsa:1024 -keyout signing_key.pem -keyform PEM \
|
|
-out signing_cert_req.pem -outform PEM -config cert_req.conf -nodes</userinput></screen>
|
|
<para>If everything is successful, you should end up with
|
|
<filename>signing_cert_req.pem</filename> and
|
|
<filename>signing_key.pem</filename>. Send
|
|
<filename>signing_cert_req.pem</filename> 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.
|
|
</para>
|
|
</section>
|
|
<section xml:id="install-external-signing-certificate">
|
|
<title>Install an external signing certificate</title>
|
|
<para>Assuming you have the following already:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<filename>signing_cert.pem</filename> - (Keystone
|
|
token) signing certificate in PEM format</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<filename>signing_key.pem</filename> -
|
|
corresponding (non-encrypted) private key in PEM
|
|
format</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<filename>cacert.pem</filename> - trust CA
|
|
certificate chain in PEM format</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Copy the above to your certificate directory. For
|
|
example:</para>
|
|
<screen><prompt>#</prompt> <userinput>mkdir -p /etc/keystone/ssl/certs</userinput>
|
|
<prompt>#</prompt> <userinput>cp signing_cert.pem /etc/keystone/ssl/certs/</userinput>
|
|
<prompt>#</prompt> <userinput>cp signing_key.pem /etc/keystone/ssl/certs/</userinput>
|
|
<prompt>#</prompt> <userinput>cp cacert.pem /etc/keystone/ssl/certs/</userinput>
|
|
<prompt>#</prompt> <userinput>chmod -R 700 /etc/keystone/ssl/certs</userinput></screen>
|
|
<note>
|
|
<para>Make sure the certificate directory is only
|
|
accessible by root.</para>
|
|
</note>
|
|
<note>
|
|
<para>The procedure of copying the key and cert files
|
|
may be improved if done after first running
|
|
<command>keystone-manage pki_setup</command>
|
|
since this command also creates other needed files,
|
|
such as the <filename>index.txt</filename>
|
|
and <filename>serial</filename> files.</para>
|
|
<para>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.</para>
|
|
</note>
|
|
<para>If your certificate directory path is different from the
|
|
default <filename>/etc/keystone/ssl/certs</filename>, make
|
|
sure it is reflected in the <literal>[signing]</literal>
|
|
section of the configuration file.</para>
|
|
</section>
|
|
<section xml:id="switching-expired-signing-certs">
|
|
<title>Switching out expired signing certificates</title>
|
|
<para>The following procedure details how to switch out
|
|
expired signing certificates with no cloud outages.</para>
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
Generate a new signing key.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Generate a new certificate request.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Sign the new certificate with the existing CA to generate a new
|
|
<filename>signing_cert</filename>.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Append the new <filename>signing_cert</filename> to
|
|
the old <filename>signing_cert</filename>. Ensure
|
|
the old certificate is in the file first.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Remove all signing certificates from all your hosts to force OpenStack
|
|
Compute to download the new <filename>signing_cert</filename>.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Replace the old signing key with the new signing key.
|
|
Move the new signing certificate above the old certificate
|
|
in the <filename>signing_cert</filename> file.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
After the old certificate reads as expired, you can safely remove
|
|
the old signing certificate from the file.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
</section>
|