===============
HTTPS security
===============

To see information about the management web server's TLS certificate,
visit the HTTPS Security page in the Administration section of the web
application. This page shows details of the certificate including the
common name (domain name), issuer, start and end dates, and
fingerprints, and displays a Certificate Signing Request (CSR) that can
be used to request a certificate from an authority.

On a new management server installation, the web server uses a
certificate from `Let's Encrypt <https://letsencrypt.org/>`__, which is
a free certificate authority that is supported by all modern browsers.
Some organizations may wish to replace this certificate with one signed
by a different authority.

Warning messages are shown if the certificate is not signed by a
recognized authority, or if the certificate is expired or nearing
expiration.

Checking the certificate
-------------------------

You can easily perform a Qualys SSL Labs test of the TLS configuration-
just click the "Perform SSL Check" button on the HTTPS Security page.

|image0|

This opens a new browser window running the test. The check warns about
incomplete or improperly configured TLS certificates. If the certificate
is signed by an accepted authority, is not expired, and includes the
necessary chain certificates, the test rating should be an A.

Obtaining a custom certificate
-------------------------------

To get a certificate signed by a different authority, review the
information in the "Certificate signing request" section of the HTTPS
Security page. If the domain name, organization, email, and locality
information are correct, you can submit the displayed CSR to your
preferred vendor. Refer to your vendor's documentation for the complete
steps to get a signed certificate.

Installing a new certificate
-----------------------------

.. note::
    If you are not comfortable following these instructions, don't worry.
    Just email your certificate to `Technical
    support <../spaces/technical-support.html>`__ and we will install it for
    you. Never send private keys by email.

.. warning::
    Never send private keys by email. When using a single-domain certificate
    purchased with the provided CSR, no keys need to be transferred because
    the key is already present on the management server. If using a wildcard
    certificate shared with other servers, you do need to copy the private
    key to the management server, and this should be done by putting it
    directly on the server via SCP or SSH.


To install a certificate for the management web server, follow these
steps:

-  Begin an SSH session to the management server.
-  Copy the existing key and certificate to a safe location in case they
   need to be restored. For example:
   ``cp /etc/bondingadmin/*.pem /var/backups/``
-  If you're using a wildcard certificate or otherwise need to copy a
   key to the management server, SCP it to ``/etc/bondingadmin/key.pem``
   or overwrite that file using a text editor in your SSH session. If
   you've purchased a single-domain certificate using the provided CSR,
   this step is not necessary.
-  If the certificate to be replaced is from Let's Encrypt, run the
   ``disable-letsencrypt`` command to switch to a custom setup
-  Using a text editor in your SSH session, open the file
   ``/etc/bondingadmin/crt.pem``. Overwrite the contents with your new
   server certificate and issuer certificates. The server certificate is
   listed first, followed by issuer chain certificates. For example, the
   contents of the file might be:

   ::

       -----BEGIN CERTIFICATE-----
       MIIEQTCCAymgAwIBAgIDCX5wMA0GCSqGSIb3DQEBCwUAMEcxCzAJBgNVBAYTAlVT
       MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMSAwHgYDVQQDExdSYXBpZFNTTCBTSEEy
       ...................... server certificate ......................
       mHJxLBhLpA0cBcKkkRB2tP42YztzPPCCFj3vdbnC+VEC7z8uD6OzzOhzVnMWGw6h
       T59XI87MzDVL+gOz61iyUy49ELxnZzFijeb1g0TBhMJsEDb/3g==
       -----END CERTIFICATE-----
       -----BEGIN CERTIFICATE-----
       MIIEJTCCAw2gAwIBAgIDAjp3MA0GCSqGSIb3DQEBCwUAMEIxCzAJBgNVBAYTAlVT
       MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMRswGQYDVQQDExJHZW9UcnVzdCBHbG9i
       ...................... issuer certificate ......................
       uLLGTxN5279PURt/aQ1RKsHWFf83UTRlUfQevjhq7A6rvz17OQV79PP7GqHQyH5O
       ZI3NjGFVkP46yl0lD/gdo0p0Vk8aVUBwdSWmMy66S6VdU5oNMOGNX2Esr8zvsJmh
       gP8L8mJMcCaY
       -----END CERTIFICATE-----
       [ ... further issuer certificates, if necessary ... ]

   Save and close the file.

-  Alternatively, you may replace ``/etc/bondingadmin/key.pem`` and
   ``/etc/bondingadmin/crt.pem`` with symlinks to a PEM-formatted key
   and a PEM-formatted certificate chain in another location.
-  Restart the web server:
   ``systemctl restart nginx``
   If the certificate was installed incorrectly, the server may fail to
   start. You should either check your certificate file for issues, or
   restore the key and certificate file from your backup and restart the
   service.
-  Run a certificate test using the method described above under
   "Checking the certificate". If problems are reported, you may need to
   carefully check the certificate chain, correct the problem, restart
   the web server, and re-run the test. If you are unable to fix any
   issues, please contact `Technical
   support <../spaces/technical-support.html>`__.

.. |image0| image:: /attachments/12320793/12320792.png
