glfs/postlfs/security/make-ca.xml
Pierre Labastie 9873d1ea37 Vim-8.2.1361
boost-1.74.0
libreoffice-6.4.6.2
a few tags

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@23547 af4574ff-66df-0310-9fd7-8a98e5e911e0
2020-08-17 06:23:35 +00:00

308 lines
13 KiB
XML

<?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.1 SBU (with all runtime deps)">
<!ENTITY make-ca-download "https://github.com/djlucas/make-ca/releases/download/v&make-ca-version;/make-ca-&make-ca-version;.tar.xz">
<!ENTITY make-ca-size "28.5 KB">
<!ENTITY make-ca-md5sum "e0356f5ae5623f227a3f69b5e8848ec6">
]>
<sect1 id="make-ca" xreflabel="make-ca-&make-ca-version;">
<?dbhtml filename="make-ca.html"?>
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<title>make-ca-&make-ca-version;</title>
<indexterm zone="make-ca">
<primary sortas="a-make-ca">make-ca</primary>
</indexterm>
<sect2 role="package">
<title>Introduction to 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>
&lfs10_checked;
<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="p11-kit"/> (required at runtime to
generate certificate stores from trust anchors)
</para>
<!-- /usr/bin/trust is needed to extract the certs to /etc/ssl/certs -->
<bridgehead renderas="sect4">Optional (runtime)</bridgehead>
<para role="optional">
<xref role="runtime" linkend="nss"/> (to generate a shared NSSDB)
</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 as trust anchors for the <xref linkend="p11-kit"/> trust module.
Additionally, it will generate system certificate stores used by BLFS
applications (if the recommended and optional applications are present
on the system). Any local certificates stored in
<filename>/etc/ssl/local</filename> will be imported to both the trust
anchors and the generated certificate stores (overriding Mozilla's
trust). Additionally, any modified trust values will be copied from the
trust anchors to <filename>/etc/ssl/local</filename> prior to any
updates, preserving custom trust values that differ from Mozilla when
using the <command>trust</command> utility from
<application>p11-kit</application> to operate on the trust store.
</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 &amp;&amp;
install -vdm755 /etc/ssl/local</userinput></screen>
<para>
As the <systemitem class="username">root</systemitem> user, after
installing <xref linkend="p11-kit"/>, download the certificate source and
prepare for system use 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>-r</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>/usr/lib/systemd/system/update-pki.timer</filename> that, if
enabled, will check for updates weekly.</phrase><phrase
revision="sysv">If you've installed <xref linkend="fcron"/> and
completed the section on periodic jobs, execute</phrase> <phrase
revision="systemd">Execute</phrase> the following commands, as the
<systemitem class="username">root</systemitem> user, to <phrase
revision="sysv">create a weekly cron job:</phrase><phrase
revision="systemd">enable the systemd timer:</phrase>
</para>
<screen role="nodump" revision="sysv"><userinput>cat &gt; /etc/cron.weekly/update-pki.sh &lt;&lt; "EOF" &amp;&amp;
<literal>#!/bin/bash
/usr/sbin/make-ca -g</literal>
EOF
chmod 754 /etc/cron.weekly/update-pki.sh</userinput></screen>
<screen role="root" revision="systemd"><userinput>systemctl enable update-pki.timer</userinput></screen>
</sect2>
<sect2 role="configuration" id="make-ca-config">
<title>Configuring make-ca</title>
<para>
For most users, no additional configuration is necessary, however,
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 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 included in
<filename>/etc/make-ca.conf.dist</filename>. Simply copy the file to
<filename>/etc/make-ca.conf</filename> and edit as appropriate.
</para>
<indexterm zone="make-ca make-ca-config">
<primary sortas="e-etc-make-ca-conf">/etc/make-ca.conf</primary>
</indexterm>
<bridgehead renderas="sect3">About Trust Arguments</bridgehead>
<para>
There are three trust types that are recognized by the
<application>make-ca</application> script, SSL/TLS, S/Mime, and code
signing. For <application>OpenSSL</application>, these are
<parameter>serverAuth</parameter>,
<parameter>emailProtection</parameter>, and
<parameter>codeSigning</parameter> respectively. 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
<filename>ca-bundle.crt</filename>,
<filename>email-ca-bundle.crt</filename>, or
<filename>objsign-ca-bundle.crt</filename> files
(the <application>GnuTLS</application> legacy bundles), it must have the
appropriate trust arguments.
</para>
<bridgehead renderas="sect3">Adding Additional CA Certificates</bridgehead>
<para>
The <filename class="directory">/etc/ssl/local</filename> directory
is available to add additional CA certificates to the system. For
instance, you might need to add an organization or government CA
certificate. Files in this directory must be in the
<application>OpenSSL</application> trusted certificate format. 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. 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 after <xref
linkend="wget"/> is installed):
</para>
<screen role="nodump"><userinput>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 &amp;&amp;
/usr/sbin/make-ca -r -f</userinput></screen>
<bridgehead renderas="sect3">Overriding Mozilla Trust</bridgehead>
<para>
Occasionally, there may be instances where you don't agree with
Mozilla's inclusion of a particular certificate authority. If you'd like
to override the default trust of a particular CA, simply create a copy of
the existing certificate in <filename
class="directory">/etc/ssl/local</filename> with different trust
arguments. For example, if you'd like to distrust the
"Makebelieve_CA_Root" file, run the following commands:
</para>
<screen role="nodump"><userinput>openssl x509 -in /etc/ssl/certs/Makebelieve_CA_Root.pem \
-text \
-fingerprint \
-setalias "Disabled Makebelieve CA Root" \
-addreject serverAuth \
-addreject emailProtection \
-addreject codeSigning \
> /etc/ssl/local/Disabled_Makebelieve_CA_Root.pem &amp;&amp;
/usr/sbin/make-ca -r -f</userinput></screen>
</sect2>
<sect2 role="content">
<title>Contents</title>
<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Directories</segtitle>
<seglistitem>
<seg>make-ca</seg>
<seg>/etc/ssl/{certs,local} and
/etc/pki/{nssdb,anchors,tls/{certs,java}}</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 trust store.
</para>
<indexterm zone="make-ca make-ca">
<primary sortas="b-make-ca">make-ca</primary>
</indexterm>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>