From a060d540d8d8b5542a24dfbcc114a9229b450b57 Mon Sep 17 00:00:00 2001 From: Michael Johnson Date: Thu, 25 Oct 2018 17:30:44 -0700 Subject: [PATCH] Adds a certificates configuration guide This patch adds an administrator guide that describes the process for setting up a dual certificate authority configuration for Octavia. Change-Id: Ibe236a851833ffa24c19695ef67547b504453f9c --- doc/source/admin/guides/certificates.rst | 312 ++++++++++++++++++ .../admin/guides/sample-configs/openssl.cnf | 106 ++++++ doc/source/admin/index.rst | 1 + 3 files changed, 419 insertions(+) create mode 100644 doc/source/admin/guides/certificates.rst create mode 100644 doc/source/admin/guides/sample-configs/openssl.cnf diff --git a/doc/source/admin/guides/certificates.rst b/doc/source/admin/guides/certificates.rst new file mode 100644 index 0000000000..192a2fa647 --- /dev/null +++ b/doc/source/admin/guides/certificates.rst @@ -0,0 +1,312 @@ +.. + Copyright 2018 Rackspace, US Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain a + copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======================================= +Octavia Certificate Configuration Guide +======================================= + +This document is intended for Octavia administrators setting up certificate +authorities for the two-way TLS authentication used in Octavia for command +and control of :term:`Amphora`. + +This guide does not apply to the configuration of `TERMINATED_TLS` listeners +on load balancers. See the `Load Balancing Cookbook`_ for instructions on +creating `TERMINATED_TLS` listeners. + +.. _Load Balancing Cookbook: ../../user/guides/basic-cookbook.html#deploy-a-tls-terminated-https-load-balancer + +Two-way TLS Authentication in Octavia +===================================== + +The Octavia controller processes communicate with the Amphora over +a TLS connection much like an HTTPS connection to a website. However, Octavia +validates that both sides are trusted by doing a two-way TLS authentication. + +.. note:: + + This is a simplification of the full TLS handshake process. See the + `TLS 1.3 RFC 8446 `_ for the full + handshake. + +Phase One +--------- + +When a controller process, such as the Octavia worker process, connects to +an Amphora, the Amphora will present its `server` certificate +to the controller. The controller will then validate it against the `server` +Certificate Authority (CA) certificate stored on the controller. If the +presented certificate is validated against the `server` CA certificate, the +connection goes into phase two of the two-way TLS authentication. + +Phase Two +--------- + +Once phase one is complete, the controller will present its `client` +certificate to the Amphora. The Amphora will then validate the +certificate against the `client` CA certificate stored inside the Amphora. +If this certificate is successfully validated, the rest of the TLS handshake +will continue to establish the secure communication channel between the +controller and the Amphora. + +Certificate Lifecycles +---------------------- + +The `server` certificates are uniquely generated for each amphora by the +controller using the `server` certificate authority certificates and keys. +These `server` certificates are automatically rotated by the Octavia +housekeeping controller process as they near expiration. + +The `client` certificates are used for the Octavia controller processes. +These are managed by the operator and due to their use on the control plane +of the cloud, typically have a long lifetime. + +See the `Operator Maintenance Guide `_ for more +information about the certificate lifecycles. + +Creating the Certificate Authorities +==================================== + +As discussed above, this configuration uses two certificate authorities; one +for the `server` certificates, and one for the `client` certificates. + +.. note:: + + Technically Octavia can be run using just one certificate authority by + using it to issue certificates for both roles. However, this weakens the + security as a `server` certificate from an amphora could be used to + impersonate a controller. We recommend you use two certificate authorities + for all deployments outside of testing. + +For this document we are going to setup simple OpenSSL based certificate +authorities. However, any standards compliant certificate authority software +can be used to create the required certificates. + +1. Create a working directory for the certificate authorities. Make sure to + set the proper permissions on this directory such that others cannot + access the private keys, random bits, etc. being generated here. + + .. code-block:: bash + + $ mkdir certs + $ chmod 700 certs + $ cd certs + +2. Create the OpenSSL configuration file. This can be shared between the + two certificate authorities. + + .. code-block:: bash + + $ vi openssl.cnf + + .. literalinclude:: sample-configs/openssl.cnf + :language: ini + +3. Make any locally required configuration changes to the openssl.cnf. Some + settings to consider are: + + * The default certificate lifetime is 10 years. + * The default bit length is 2048. + +4. Make directories for the two certificate authorities. + + .. code-block:: bash + + $ mkdir client_ca + $ mkdir server_ca + +5. Starting with the `server` certificate authority, prepare the CA. + + .. code-block:: bash + + $ cd server_ca + $ mkdir certs crl newcerts private + $ chmod 700 private + $ touch index.txt + $ echo 1000 > serial + +6. Create the `server` CA key. + + * You will need to specify a passphrase to protect the key file. + + .. code-block:: bash + + $ openssl genrsa -aes256 -out private/ca.key.pem 4096 + $ chmod 400 private/ca.key.pem + +7. Create the `server` CA certificate. + + * You will need to specify the passphrase used in step 6. + * You will also be asked to provide details for the certificate. These are + up to you and should be appropriate for your organization. + * You may want to mention this is the `server` CA in the common name field. + * Since this is the CA certificate, you might want to give it a very long + lifetime, such as twenty years shown in this example command. + + .. code-block:: bash + + $ openssl req -config ../openssl.cnf -key private/ca.key.pem -new -x509 -days 7300 -sha256 -extensions v3_ca -out certs/ca.cert.pem + +8. Moving to the `client` certificate authority, prepare the CA. + + .. code-block:: bash + + $ cd ../client_ca + $ mkdir certs crl csr newcerts private + $ chmod 700 private + $ touch index.txt + $ echo 1000 > serial + +9. Create the `client` CA key. + + * You will need to specify a passphrase to protect the key file. + + .. code-block:: bash + + $ openssl genrsa -aes256 -out private/ca.key.pem 4096 + $ chmod 400 private/ca.key.pem + +10. Create the `client` CA certificate. + + * You will need to specify the passphrase used in step 9. + * You will also be asked to provide details for the certificate. These are + up to you and should be appropriate for your organization. + * You may want to mention this is the `client` CA in the common name field. + * Since this is the CA certificate, you might want to give it a very long + lifetime, such as twenty years shown in this example command. + + .. code-block:: bash + + $ openssl req -config ../openssl.cnf -key private/ca.key.pem -new -x509 -days 7300 -sha256 -extensions v3_ca -out certs/ca.cert.pem + +11. Create a key for the `client` certificate to use. + + * You can create one certificate and key to be used by all of the + controllers or you can create a unique certificate and key for each + controller. + * You will need to specify a passphrase to protect the key file. + + .. code-block:: bash + + $ openssl genrsa -aes256 -out private/client.key.pem 2048 + +12. Create the certificate request for the `client` certificate used on the + controllers. + + * You will need to specify the passphrase used in step 11. + * You will also be asked to provide details for the certificate. These are + up to you and should be appropriate for your organization. + * You must fill in the common name field. + * You may want to mention this is the `client` certificate in the common + name field, or the individual controller information. + + .. code-block:: bash + + $ openssl req -config ../openssl.cnf -new -sha256 -key private/client.key.pem -out csr/client.csr.pem + +13. Sign the `client` certificate request. + + * You will need to specify the CA passphrase used in step 9. + * Since this certificate is used on the control plane, you might want to + give it a very long lifetime, such as twenty years shown in this example + command. + + .. code-block:: bash + + $ openssl ca -config ../openssl.cnf -extensions usr_cert -days 7300 -notext -md sha256 -in csr/client.csr.pem -out certs/client.cert.pem + +14. Create a concatenated `client` certificate and key file. + + * You will need to specify the CA passphrase used in step 11. + + .. code-block:: bash + + $ openssl rsa -in private/client.key.pem -out private/client.cert-and-key.pem + $ cat certs/client.cert.pem >> private/client.cert-and-key.pem + + +Configuring Octavia +=================== + +In this section we will configure Octavia to use the certificates and keys +created during the `Creating the Certificate Authorities`_ section. + +1. Copy the required files over to your Octavia controllers. + + * Only the Octavia worker, health manager, and housekeeping processes will + need access to these files. + * The first command should return you to the "certs" directory created in + step 1 of the `Creating the Certificate Authorities`_ section. + * These commands assume you are running the octavia processes under the + "octavia" user. + * Note, some of these steps should be run with "sudo" and are indicated by + the "#" prefix. + + .. code-block:: bash + + $ cd .. + # mkdir /etc/octavia/certs + # chmod 700 /etc/octavia/certs + # cp server_ca/private/ca.key.pem /etc/octavia/certs/server_ca.key.pem + # chmod 700 /etc/octavia/certs/server_ca.key.pem + # cp server_ca/certs/ca.cert.pem /etc/octavia/certs/server_ca.cert.pem + # cp client_ca/certs/ca.cert.pem /etc/octavia/certs/client_ca.cert.pem + # cp client_ca/private/client.cert-and-key.pem /etc/octavia/certs/client.cert-and-key.pem + # chmod 700 /etc/octavia/certs/client.cert-key.pem + # chown -R octavia.octavia /etc/octavia/certs + +2. Configure the [certificates] section of the octavia.conf file. + + * Only the Octavia worker, health manager, and housekeeping processes will + need these settings. + * The "" should be replaced with the passphrase + that was used in step 6 of the `Creating the Certificate Authorities`_ + section. + + .. code-block:: ini + + [certificates] + cert_generator = local_cert_generator + ca_certificate = /etc/octavia/certs/server_ca.cert.pem + ca_private_key = /etc/octavia/certs/server_ca.key.pem + ca_private_key_passphrase = + +3. Configure the [controller_worker] section of the octavia.conf file. + + * Only the Octavia worker, health manager, and housekeeping processes will + need these settings. + + .. code-block:: ini + + [controller_worker] + client_ca = /etc/octavia/certs/client_ca.cert.pem + +4. Configure the [haproxy_amphora] section of the octavia.conf file. + + * Only the Octavia worker, health manager, and housekeeping processes will + need these settings. + + .. code-block:: ini + + [haproxy_amphora] + client_cert = /etc/octavia/certs/client.cert-and-key.pem + server_ca = /etc/octavia/certs/server_ca.cert.pem + +5. Start the controller processes. + + .. code-block:: bash + + # systemctl start octavia-worker + # systemctl start octavia-healthmanager + # systemctl start octavia-housekeeping diff --git a/doc/source/admin/guides/sample-configs/openssl.cnf b/doc/source/admin/guides/sample-configs/openssl.cnf new file mode 100644 index 0000000000..01b398549b --- /dev/null +++ b/doc/source/admin/guides/sample-configs/openssl.cnf @@ -0,0 +1,106 @@ +# OpenSSL root CA configuration file. + +[ ca ] +# `man ca` +default_ca = CA_default + +[ CA_default ] +# Directory and file locations. +dir = ./ +certs = $dir/certs +crl_dir = $dir/crl +new_certs_dir = $dir/newcerts +database = $dir/index.txt +serial = $dir/serial +RANDFILE = $dir/private/.rand + +# The root key and root certificate. +private_key = $dir/private/ca.key.pem +certificate = $dir/certs/ca.cert.pem + +# For certificate revocation lists. +crlnumber = $dir/crlnumber +crl = $dir/crl/ca.crl.pem +crl_extensions = crl_ext +default_crl_days = 30 + +# SHA-1 is deprecated, so use SHA-2 instead. +default_md = sha256 + +name_opt = ca_default +cert_opt = ca_default +default_days = 3650 +preserve = no +policy = policy_strict + +[ policy_strict ] +# The root CA should only sign intermediate certificates that match. +# See the POLICY FORMAT section of `man ca`. +countryName = match +stateOrProvinceName = match +organizationName = match +organizationalUnitName = optional +commonName = supplied +emailAddress = optional + +[ req ] +# Options for the `req` tool (`man req`). +default_bits = 2048 +distinguished_name = req_distinguished_name +string_mask = utf8only + +# SHA-1 is deprecated, so use SHA-2 instead. +default_md = sha256 + +# Extension to add when the -x509 option is used. +x509_extensions = v3_ca + +[ req_distinguished_name ] +# See . +countryName = Country Name (2 letter code) +stateOrProvinceName = State or Province Name +localityName = Locality Name +0.organizationName = Organization Name +organizationalUnitName = Organizational Unit Name +commonName = Common Name +emailAddress = Email Address + +# Optionally, specify some defaults. +countryName_default = US +stateOrProvinceName_default = Oregon +localityName_default = +0.organizationName_default = OpenStack +organizationalUnitName_default = Octavia +emailAddress_default = +commonName_default = example.org + +[ v3_ca ] +# Extensions for a typical CA (`man x509v3_config`). +subjectKeyIdentifier = hash +authorityKeyIdentifier = keyid:always,issuer +basicConstraints = critical, CA:true +keyUsage = critical, digitalSignature, cRLSign, keyCertSign + +[ usr_cert ] +# Extensions for client certificates (`man x509v3_config`). +basicConstraints = CA:FALSE +nsCertType = client, email +nsComment = "OpenSSL Generated Client Certificate" +subjectKeyIdentifier = hash +authorityKeyIdentifier = keyid,issuer +keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment +extendedKeyUsage = clientAuth, emailProtection + +[ server_cert ] +# Extensions for server certificates (`man x509v3_config`). +basicConstraints = CA:FALSE +nsCertType = server +nsComment = "OpenSSL Generated Server Certificate" +subjectKeyIdentifier = hash +authorityKeyIdentifier = keyid,issuer:always +keyUsage = critical, digitalSignature, keyEncipherment +extendedKeyUsage = serverAuth + +[ crl_ext ] +# Extension for CRLs (`man x509v3_config`). +authorityKeyIdentifier=keyid:always diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 0aae97a0e2..1e424064d3 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -29,6 +29,7 @@ Operator Reference :maxdepth: 1 ../contributor/guides/dev-quick-start.rst + guides/certificates.rst guides/operator-maintenance.rst guides/upgrade.rst ../configuration/configref.rst