3e1100a70a
As per convention, we should avoid using "e.g." (we should use "for example" instead). Found and replaced them accordingly; didn't touch instances that looked copy-pasted from stdout. Change-Id: I45aae1a30b872f916744a6a33f6888abe8cf6eb0 Partial-Bug: #1217503
231 lines
13 KiB
XML
231 lines
13 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 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 nova-manage as root, you
|
|
can append --keystone-user and --keystone-group parameters
|
|
to set the username 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>token_format</literal> - Determines the
|
|
algorithm used to generate tokens. Can be either
|
|
<literal>UUID</literal> or <literal>PKI</literal>.
|
|
Defaults to <literal>PKI</literal>.</para>
|
|
</listitem>
|
|
<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>key_size</literal> - Default is
|
|
<literal>1024</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>valid_days</literal> - Default is
|
|
<literal>3650</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ca_password</literal> - Password required to
|
|
read the <literal>ca_file</literal>. Default is
|
|
<literal>None</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>If <literal>token_format=UUID</literal>, a typical token
|
|
looks like
|
|
<literal>53f7f6ef0cc344b5be706bcc8b1479e1</literal>. If
|
|
<literal>token_format=PKI</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,
|
|
certificate issued by 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 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 = 1024
|
|
default_keyfile = keystonekey.pem
|
|
default_md = sha1
|
|
|
|
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 successfully, 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>
|
|
<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>
|