source: postlfs/security/cacerts.xml@ 96e9478

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY certhost              "https://hg.mozilla.org/">
  <!ENTITY certpath              "/lib/ckfw/builtins/certdata.txt">
  <!ENTITY ca-bundle-download    "&sources-anduin-http;/other/certdata.txt">
  <!ENTITY ca-bundle-size        "1.6 MB">
  <!ENTITY cacerts-buildsize     "6.5 MB (with all runtime deps)">
  <!ENTITY cacerts-time          "0.2 SBU (with all runtime deps)">

  <!ENTITY make-ca-download      "&sources-anduin-http;/other/make-ca.sh-&make-ca-version;">
  <!ENTITY make-ca-size          "24 KB">
  <!ENTITY make-ca-md5sum        "a21a04d6ff5c4645c748220dbaa9f221">
]>

<sect1 id="cacerts" xreflabel="Certificate Authority Certificates">
  <?dbhtml filename="cacerts.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Certificate Authority Certificates</title>

  <para>Public Key Infrastructure (PKI) is a method to validate the
  authenticity of an otherwise unknown entity across untrusted networks. PKI
  works by establishing a chain of trust, rather than trusting each individual
  host or entity explicitly. In order for a certificate presented by a remote
  entity to be trusted, that certificate must present a complete chain of
  certificates that can be validated using the root certificate of a
  Certificate Authority (CA) that is trusted by the local machine.</para>
  
  <para>Establishing trust with a CA involves validating things like company
  address, ownership, contact information, etc., and ensuring that the CA has
  followed best practices, such as undergoing periodic security audits by
  independent investigators and maintaining an always available certificate
  revocation list. This is well outside the scope of BLFS (as it is for most
  Linux distributions). The certificate store provided here is taken from the
  Mozilla Foundation, who have established very strict inclusion policies
  described
  <ulink url="https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/">here</ulink>.</para>

  &lfs81_checked;

  <indexterm zone="cacerts">
    <primary sortas="a-cacerts">Certificate Authority Certificates</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Certificate Authorities</title>

   <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&make-ca-download;"/></para>
      </listitem>
      <listitem>
        <para>Download size: &make-ca-size;</para>
      </listitem>
      <listitem>
        <para>Download MD5 Sum: &make-ca-md5sum;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &cacerts-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &cacerts-time;</para>
      </listitem>
    </itemizedlist>


    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          CA Certificates
          <ulink url="&ca-bundle-download;"/>
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Certificate Authority Certificates Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="openssl"/></para>

   <bridgehead renderas="sect4">Optional (runtime)</bridgehead>
    <para role="optional">
      <xref role="runtime" linkend="java"/> or
      <xref role="runtime" linkend="openjdk"/>,
      <xref role="runtime" linkend="nss"/>, and
      <xref role="runtime" linkend="p11-kit"/>
    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url='&blfs-wiki;/cacerts'/></para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Certificate Authority Certificates</title>

    <para>The <application>make-ca.sh</application> script will process the
    certificates included in the <filename>certdata.txt</filename> file
    for use in multiple certificate stores (if the associated applications are
    present on the system). Additionally, any local certificates stored in
    <filename>/etc/ssl/local</filename> will be imported to the certificate
    stores. Certificates in this directory should be stored as PEM encoded
    <application>OpenSSL</application> trusted certificates.</para>

    <para>To create an <application>OpenSSL</application> trusted certificate
    from a regular PEM encoded file, provided by a CA not included in Mozilla's
    certificate distribution, you need to add trust arguments to the
    <command>openssl</command> command, and create a new certificate. There are
    three trust types that are recognized by the
    <application>make-ca.sh</application> script, SSL/TLS, S/Mime, and code
    signing. For example, using the
    <ulink url="http://www.cacert.org/">CAcert</ulink> root, if you want it to
    be trusted for all three roles, the following commands will create an
    appropriate OpenSSL trusted certificate:</para>

<screen role="root"><userinput>install -vdm755 /etc/ssl/local &amp;&amp;
wget http://www.cacert.org/certs/root.crt &amp;&amp;
openssl x509 -in root.crt -text -fingerprint -setalias "CAcert Class 1 root" \
        -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
        > /etc/ssl/local/CAcert_Class_1_root.pem</userinput></screen>

    <para>If one of the three trust arguments is omitted, the certificate is
    neither trusted, nor rejected for that role. Clients that use
    <application>OpenSSL</application> or <application>NSS</application>
    encountering this certificate will present a warning to the user. Clients
    using <application>GnuTLS</application> without
    <application>p11-kit</application> support are not aware of trusted
    certificates. To include this CA into the ca-bundle.crt (used for
    <application>GnuTLS</application>), it must have <envar>serverAuth</envar>
    trust. Additionally, to explicitly disallow a certificate for a particular
    use, replace the <parameter>-addtrust</parameter> flag with the
    <parameter>-addreject</parameter> flag.</para> 

    <para>To install the various certificate stores, first install the
    <application>make-ca.sh</application> script into the correct location.
    As the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -vm755 make-ca.sh-&make-ca-version; /usr/sbin/make-ca.sh</userinput></screen>

   <para>As the <systemitem class="username">root</systemitem> user, make sure
   that certdata.txt is in the current directory, and update the certificate
   stores with the following command:</para>

    <note>
      <para>If running the script a second time with the same version of
      <filename>certdata.txt</filename>, for instance, to add additional stores
      as the requisite software is installed, add the <parameter>-f</parameter>
      switch to the command line. If packaging, run <command>make-ca.sh
      --help</command> to see all available command line options.</para>
    </note>

<screen role="root"><userinput>/usr/sbin/make-ca.sh</userinput></screen>

    <para>You should periodically download a copy of
    <filename>certdata.txt</filename> and run the
    <application>make-ca.sh</application> script (as the
    <systemitem class="username">root</systemitem> user), or as part of a
    monthly <application>cron</application> job to ensure that you have the
    latest available version of the certificates.</para>

    <para>The <filename>certdata.txt</filename> file provided by BLFS is
    obtained from the mozilla-release branch, and is modified to provide a
    simple dated revision. This will be the correct version for most
    systems. There are, however, several other variants of the file available
    for use that might be preferred for one reason or another, including the
    files shipped with Mozilla products in this book. RedHat and OpenSUSE,
    for instance, use the version included in <xref linkend="nss"/>. Additional
    upstream downloads are available at the links below.</para>

    <itemizedlist spacing="compact">
      <listitem>
        <para>Mozilla Release (the version provided by BLFS):
        <ulink url="&certhost;releases/mozilla-release/raw-file/default/security/nss&certpath;"/>
        </para>
      </listitem>
      <listitem>
        <para>NSS (this is the latest available version):
        <ulink url="&certhost;projects/nss/raw-file/tip&certpath;"/>
        </para>
      </listitem>
      <listitem>
        <para>Mozilla Central:
        <ulink url="&certhost;mozilla-central/raw-file/default/security/nss&certpath;"/>
        </para>
      </listitem>
      <listitem>
        <para>Mozilla Beta:
        <ulink url="&certhost;releases/mozilla-beta/raw-file/default/security/nss&certpath;"/>
        </para>
      </listitem>
      <listitem>
        <para>Mozilla Aurora:
        <ulink url="&certhost;releases/mozilla-aurora/raw-file/default/security/nss&certpath;"/>
        </para>
      </listitem>
    </itemizedlist>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>make-ca.sh</seg>
        <seg>None</seg>
        <seg>/etc/ssl/{certs,java,local} and /etc/pki/{nssdb,anchors}</seg>
      </seglistitem>
    </segmentedlist>

   <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="make-ca">
        <term><command>make-ca.sh</command></term>
        <listitem>
          <para>is a shell script that adapts a current version of
          <filename>certdata.txt</filename>, and prepares it for use
          as the system certificate store.</para>
          <indexterm zone="cacerts make-ca">
            <primary sortas="b-make-ca">make-ca</primary>
          </indexterm>
        </listitem>
      </varlistentry>
   </variablelist>

  </sect2>
</sect1>