Index: postlfs/security/make-ca.xml
===================================================================
--- postlfs/security/make-ca.xml	(revision 2198a3224bc5a1c999e3fff336401b9b2ae790f0)
+++ postlfs/security/make-ca.xml	(revision 2198a3224bc5a1c999e3fff336401b9b2ae790f0)
@@ -0,0 +1,232 @@
+<?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 make-ca-buildsize     "6.6 MB (with all runtime deps)">
+  <!ENTITY make-ca-time          "0.3 SBU (with all runtime deps)">
+
+  <!ENTITY make-ca-download      "https://github.com/djlucas/make-ca/archive/v&make-ca-version;/make-ca-&make-ca-version;.tar.gz">
+  <!ENTITY make-ca-size          "36 KB">
+  <!ENTITY make-ca-md5sum        "4f180b9bf3b11f29d6a79e6022aeae23">
+]>
+
+<sect1 id="make-ca" xreflabel="make-ca">
+  <?dbhtml filename="make-ca.html"?>
+
+  <sect1info>
+    <othername>$LastChangedBy$</othername>
+    <date>$Date$</date>
+  </sect1info>
+
+  <title>make-ca</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>
+
+  &lfs82_checked;
+
+  <indexterm zone="make-ca">
+    <primary sortas="a-make-ca">make-ca</primary>
+  </indexterm>
+
+  <sect2 role="package">
+    <title>Introduction to make-ca</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: &make-ca-buildsize;</para>
+      </listitem>
+      <listitem>
+        <para>Estimated build time: &make-ca-time;</para>
+      </listitem>
+    </itemizedlist>
+
+    <bridgehead renderas="sect3">make-ca 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;/make-ca'/></para>
+  </sect2>
+
+  <sect2 role="installation">
+    <title>Installation of make-ca</title>
+
+    <para>The <application>make-ca</application> script will download and
+    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, 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</application> script, SSL/TLS, S/Mime, and code
+    signing. For example, using the
+    <ulink url="http://www.cacert.org/">CAcert</ulink> roots, if you want to
+    trust both for all three roles, the following commands will create
+    appropriate OpenSSL trusted certificates (run as the <systemitem
+    class="username">root</systemitem> user):</para>
+
+<screen role="nodump"><userinput>install -vdm755 /etc/ssl/local &amp;&amp;
+wget http://www.cacert.org/certs/root.crt &amp;&amp;
+wget http://www.cacert.org/certs/class3.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 &amp;&amp;
+openssl x509 -in class3.crt -text -fingerprint -setalias "CAcert Class 3 root" \
+        -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
+        > /etc/ssl/local/CAcert_Class_3_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</application> script into the correct location.
+    As the <systemitem class="username">root</systemitem> user:</para>
+
+<screen role="root"><userinput>make install</userinput></screen>
+
+   <para>As the <systemitem class="username">root</systemitem> user, download
+   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
+      --help</command> to see all available command line options.</para>
+    </note>
+
+<screen role="root"><userinput>/usr/sbin/make-ca -g</userinput></screen>
+
+    <para>You should periodically update the store with the above command
+    either manually, or via a <phrase revision="sysv">cron job.</phrase>
+    <phrase revision="systemd">systemd timer. A timer is installed at
+    <filename>/etc/systemd/system/update-pki.timer</filename> that, if enabled,
+    will check for updates weekly.</phrase></para>
+
+    <para>The default <filename>certdata.txt</filename> file provided by make-ca
+    is obtained from the mozilla-release branch, and is modified to provide a
+    Mercurial 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</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-bin">
+        <term><command>make-ca</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="make-ca make-ca">
+            <primary sortas="b-make-ca">make-ca</primary>
+          </indexterm>
+        </listitem>
+      </varlistentry>
+   </variablelist>
+
+  </sect2>
+</sect1>
