tls.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
      xml:id="tls">
  <title>TLS certificate creation</title>

  <para>Certificates are an essential security mechanism for most
  federated and distributed technologies on the Internet.</para>

  <para>Certificates may be referred to as X.509 certificates, SSL
  certificates or TLS certificates.  For most purposes, these terms all
  refer to the same thing and the term TLS certificate is used throughout
  this documentation.</para>

  <para>The prices of TLS certificates vary significantly.  It is not
  necessarily useful to purchase the most expensive one.</para>

  <para>The free TLS certificates from the
  <link xlink:href="https://letsencrypt.org/">Let's Encrypt Project</link>,
  which is supported by the EFF and Linux Foundation, are a good choice
  for the vast majority of RTC projects, including WebRTC.  Let's Encrypt
  is not just a new Certificate Authority, they also promote the use
  of an automated tool for the acquisition and renewal of certificates.
  This dramatically reduces the amount of manual effort involved in using
  certificates, especially for people who host multiple sites and domains.
  That said, the initial version of the Let's Encrypt tool has been
  designed for use with web servers and some manual tweaking is
  required to use it with SIP, XMPP, WebSocket and TURN servers.
  Early versions of the tool also failed to operate correctly on
  some servers with IPv6 addresses and some Apache configurations,
  although most of these issues were resolved by mid-2016.</para>

  <para>You do need to make sure that the certificate issued by the
  Certificate Authority (CA) includes both the <emphasis>TLS client</emphasis>
  and <emphasis>TLS server</emphasis> Extended Key Usage (EKU) extensions, some
  only include the latter.  The free certificates from
  <emphasis>StartSSL/StartCom</emphasis> do not have the
  <emphasis>TLS client</emphasis> extension and can't be used.  The
  <link xlink:href="https://www.gandi.net/ssl/standard#single">Gandi.net SSL
  Standard certificate</link> which costs about $16 (free with a
  domain registration or transfer) is known to be suitable.</para>

  <para>If you are using some older IP desk phones, the phones
  may not have support for the Let's Encrypt root certificate in
  their firmware.  If this is the case, you may need to update the firmware,
  obtain a newer model phone or use certificates from a more established
  Certificate Authority.  For example, some older Polycom phones do
  not work with Let's Encrypt but they work fine with the low cost
  Gandi.net certificates.</para>

  <sect1 xml:id="tls-common-name">
    <title>Certificate Common Name</title>
    <para>Certificates confirm the identity of a service.  The identity
    is specified by the <emphasis>Common Name</emphasis> (CN) and in
    some cases the <literal>subjectAltName</literal> embedded in the
    certificate.</para>

    <para>Some vendors refer to <literal>subjectAltName</literal>
    certificates as SAN certificates.  This acronym is more commonly used
    for Storage Area Network and can cause confusion.</para>

    <para>Early versions of the federated XMPP specification proposed a
    custom OID, <literal>xmppAddr</literal>, rather than using
    <literal>subjectAltName</literal>.  This practice was not widely
    supported by certificate authorities.  Furthermore, it meant that
    such certificates could not be used for purposes other than XMPP,
    such as SMTP email or SIP.  The XMPP specification has since been
    relaxed and it is now possible to use a single certificate on a server
    for SIP, XMPP, SMTP and other purposes.</para>

    <para>Many web sites use a name such as <literal>www.example.org</literal>
    and include the <literal>www</literal> prefix in the CN in their
    certificate.  When purchasing a certificate for SIP and XMPP, it is
    important to ensure that the certificate contains a CN or
    <literal>subjectAltName</literal> that specifies the domain alone.  For
    the <literal>example.org</literal> domain, the certificate should include
    <literal>CN=example.org</literal> or
    <literal>subjectAltName=example.org</literal> and not something like
    <literal>CN=www.example.org</literal>.</para>

    <para>In a <emphasis>wildcard certificate</emphasis>, the CN will
    include an asterisk (<literal>*</literal>), for example,
    <literal>CN=*.example.org</literal>.  This type of certificate can be
    used for the domain <literal>example.org</literal> and subdomains or
    hostnames such as <literal>www.example.org</literal> or
    <literal>mail.example.org</literal>.</para>

    <para>Some organizations have <emphasis>wildcard</emphasis>
    certificates for all servers/subdomains in the organization.  These
    are not always suitable for RTC purposes, in particular,
    <link xlink:href="https://tools.ietf.org/html/rfc5922#section-7.2">RFC 5922
    section 7.2</link> prohibits the use of wildcard certificates for SIP.
    Some SIP products offer the ability to override this restriction and
    use wildcard certificates anyway, however, this is not suitable for
    the public Internet as you can't be sure that other servers will
    have the same override enabled.</para>

    <para>The correct domain needs to be specified when creating the
    <emphasis>certificate signing request</emphasis> (CSR) and should be
    confirmed by the CA in their web-based ordering form.  If using
    the Let's Encrypt utility to obtain certificates, this part of
    the process is automated.</para>
  </sect1>

  <sect1 xml:id="tls-install-openssl">
    <title>Install the OpenSSL utility</title>

    <para>Make sure the OpenSSL package is available, it can be installed
    using the package manager as demonstrated in
    <xref linkend="tls-install-openssl-debian"/> and
    <xref linkend="tls-install-openssl-redhat"/>.</para>

    <example xml:id="tls-install-openssl-debian">
      <title>Installing <literal>openssl</literal> on Debian/Ubuntu</title>
      <programlisting format="linespecific">$ sudo apt-get install ssl-cert openssl</programlisting>
    </example>

    <example xml:id="tls-install-openssl-redhat">
      <title>Installing <literal>openssl</literal> on Fedora/RHEL/CentOS</title>
      <programlisting format="linespecific">$ sudo yum install openssl</programlisting>
    </example>
  </sect1>

  <sect1 xml:id="tls-install-certbot">
    <title>Install the Let's Encrypt <literal>certbot</literal> utility</title>

    <para>If you have decided to use Let's Encrypt certificates,
    it is necessary to install the <literal>certbot</literal> utility
    or an equivalent utility implementing the
    <link xlink:href="https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment">Automated Certificate Management Environment (ACME)</link>.
    Install <literal>certbot</literal> using the package manager as
    demonstrated in
    <xref linkend="tls-install-certbot-debian"/> and
    <xref linkend="tls-install-certbot-redhat"/>.</para>

    <example xml:id="tls-install-certbot-debian">
      <title>Installing <literal>certbot</literal> on Debian/Ubuntu</title>
      <programlisting format="linespecific">$ sudo apt-get install -t jessie-backports ssl-cert certbot</programlisting>
    </example>

    <example xml:id="tls-install-certbot-redhat">
      <title>Installing <literal>certbot</literal> on Fedora/RHEL/CentOS</title>
      <programlisting format="linespecific">$ sudo yum install certbot</programlisting>
    </example>
  </sect1>

  <sect1 xml:id="tls-install-certificate-certbot">
    <title>Install a TLS certificate using Let's Encrypt (certbot)</title>

    <para>If using a web server for exactly the same domain name
    as your RTC service, it is possible to use the <literal>certbot</literal>
    command for your web server to setup the certificate the first time.
    </para>

    <para>If there is no HTTPS web server for the domain, it is possible
    to use the <literal>certbot certonly</literal> sub-command
    to request a certificate.</para>

    <para>As the <literal>certbot</literal> utility is still quite new
    and evolving, it is recommend that you consult the
    <link xlink:href="https://certbot.eff.org/"><literal>certbot</literal>
    web site</link> for the most up-to-date detailed instructions.</para>

    <para>After running <literal>certbot</literal>, the certificate
    files will be present at locations such as
    <literal>/etc/letsencrypt/live/example.org/fullchain.pem</literal>
    and the private key files will be present at locations such as
    <literal>/etc/letsencrypt/live/example.org/privkey.pem</literal>
    </para>
  </sect1>

  <sect1 xml:id="tls-install-certificate">
    <title>Install a TLS certificate manually</title>

    <para>If you have decided not to use Let's Encrypt and
    <literal>certbot</literal>, use these instructions to create
    your certificate(s) manually.  Otherwise, this section can be
    skipped.</para>

    <para>On each Linux platform, there are different locations for
    private key files and local server certificates.  To simplify the
    examples, we define environment variables referring to them.
    See <xref linkend="tls-pki-location-debian"/> and
    <xref linkend="tls-pki-location-redhat"/>.</para>

    <para>On the server, create an <emphasis>RSA key pair</emphasis>
    and a <emphasis>certificate signing request</emphasis> (CSR) as
    demonstrated in <xref linkend="tls-keypair-and-csr"/>.</para>

    <example xml:id="tls-pki-location-debian">
      <title>PKI directories (Debian/Ubuntu)</title>
      <programlisting format="linespecific">$ PKI_HOME=/etc/ssl
$ PRIVATE_KEY_DIR=${PKI_HOME}/private
$ CERT_DIR=${PKI_HOME}/public
$ CSR_DIR=${PKI_HOME}/csr</programlisting>
    </example>

    <example xml:id="tls-pki-location-redhat">
      <title>PKI directories (Fedora/RHEL/CentOS)</title>
      <programlisting format="linespecific">$ PKI_HOME=/etc/pki/tls
$ PRIVATE_KEY_DIR=${PKI_HOME}/private
$ CERT_DIR=${PKI_HOME}/certs
$ CSR_DIR=${PKI_HOME}/csr</programlisting>
    </example>

    <example xml:id="tls-keypair-and-csr">
      <title>Creating RSA key pair and CSR</title>
      <programlisting format="linespecific">$ MY_DOMAIN=example.org
$ sudo mkdir -p $PRIVATE_KEY_DIR
$ PRIVATE_KEY_PEM=${PRIVATE_KEY_DIR}/${MY_DOMAIN}-key.pem
$ CSR_PEM=${CSR_DIR}/${MY_DOMAIN}-csr.pem
$ sudo openssl genrsa -out ${PRIVATE_KEY_PEM} 2048
$ sudo chmod 0640 ${PRIVATE_KEY_PEM}
$ sudo chgrp ssl-cert ${PRIVATE_KEY_PEM}
$ sudo mkdir -p ${CSR_DIR} ${CERT_DIR}
$ sudo openssl req -new \
          -key ${PRIVATE_KEY_PEM} \
          -out ${CSR_PEM} \
          -subj "/CN=${MY_DOMAIN}"
$ sudo cat ${CSR_PEM} </programlisting>
    </example>

    <para>Your CA will ask you to copy the CSR text and paste it into a
    form on their web site.  The CA will now issue a certificate; it may
    be displayed in the browser or sent to you by email.  Copy and paste
    it into the server after the <literal>cat</literal> command in
    <xref linkend="tls-install-certificate-commands"/>, pressing
    <literal>CTRL-D</literal> or typing <literal>EOF</literal> to finish.</para>

    <para>If the CA provides an <emphasis>intermediate certificate</emphasis>,
    you must also append it to the certificate file.  The certificate
    file should contain the certificate for your domain, following by
    each intermediate certificate in order up to but not including
    the root.</para>

    <example xml:id="tls-install-certificate-commands">
      <title>Installing the certificate</title>
      <programlisting format="linespecific">$ sudo cat > /etc/ssl/public/${MY_DOMAIN}.pem &lt;&lt; EOF
-----BEGIN CERTIFICATE-----
MIIHWTCCBUGgAwIBAgIDCkGKMA0GCSqGSIb3DQEBCwUAMHkxEDAOBgNVBAoTB1Jv
b3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAGA1UEAxMZ
Q0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYSc3VwcG9y
.
.
.
d+pLncdBu8fA46A/5H2kjXPmEkvfoXNzczqA6NXLji/L6hOn1kGLrPo8idck9U60
4GGSt/M3mMS+lqO3ig==
-----END CERTIFICATE-----
EOF </programlisting>
    </example>

    <para>The certificate is now ready for use by both the SIP and
    XMPP servers.  It can also be used to secure a web server, SMTP
    server or any other application.</para>
  </sect1>

</chapter>