source: postlfs/security/make-ca.xml@ acf7e2c

basic
Last change on this file since acf7e2c was acf7e2c, checked in by Bruce Dubbs <bdubbs@…>, 4 years ago

Updates to Basic BLFS Chapter 3

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/branches/basic@20519 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 10.4 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY certhost "https://hg.mozilla.org/">
8 <!ENTITY certpath "/lib/ckfw/builtins/certdata.txt">
9 <!ENTITY make-ca-buildsize "6.6 MB (with all runtime deps)">
10 <!ENTITY make-ca-time "0.1 SBU (with all runtime deps)">
11
12 <!ENTITY make-ca-download "https://github.com/djlucas/make-ca/archive/v&make-ca-version;/make-ca-&make-ca-version;.tar.gz">
13 <!ENTITY make-ca-size "36 KB">
14 <!ENTITY make-ca-md5sum "0eeaf712eedeae4fa55d8bfa37f4ca32">
15]>
16
17<sect1 id="make-ca" xreflabel="make-ca-&make-ca-version;">
18 <?dbhtml filename="make-ca.html"?>
19
20 <sect1info>
21 <othername>$LastChangedBy$</othername>
22 <date>$Date$</date>
23 </sect1info>
24
25 <title>make-ca-&make-ca-version;</title>
26 <indexterm zone="make-ca">
27 <primary sortas="a-make-ca">make-ca</primary>
28 </indexterm>
29
30 <sect2 role="package">
31 <title>Introduction to make-ca</title>
32
33 <para>
34 Public Key Infrastructure (PKI) is a method to validate the authenticity
35 of an otherwise unknown entity across untrusted networks. PKI works by
36 establishing a chain of trust, rather than trusting each individual host
37 or entity explicitly. In order for a certificate presented by a remote
38 entity to be trusted, that certificate must present a complete chain of
39 certificates that can be validated using the root certificate of a
40 Certificate Authority (CA) that is trusted by the local machine.
41 </para>
42
43 <para>
44 Establishing trust with a CA involves validating things like company
45 address, ownership, contact information, etc., and ensuring that the CA
46 has followed best practices, such as undergoing periodic security audits
47 by independent investigators and maintaining an always available
48 certificate revocation list. This is well outside the scope of BLFS (as
49 it is for most Linux distributions). The certificate store provided here
50 is taken from the Mozilla Foundation, who have established very strict
51 inclusion policies described <ulink
52 url="https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/">here</ulink>.
53 </para>
54
55 &lfs83_checked;
56
57 <bridgehead renderas="sect3">Package Information</bridgehead>
58 <itemizedlist spacing="compact">
59 <listitem>
60 <para>Download (HTTP): <ulink url="&make-ca-download;"/></para>
61 </listitem>
62 <listitem>
63 <para>Download size: &make-ca-size;</para>
64 </listitem>
65 <listitem>
66 <para>Download MD5 Sum: &make-ca-md5sum;</para>
67 </listitem>
68 <listitem>
69 <para>Estimated disk space required: &make-ca-buildsize;</para>
70 </listitem>
71 <listitem>
72 <para>Estimated build time: &make-ca-time;</para>
73 </listitem>
74 </itemizedlist>
75
76 <bridgehead renderas="sect3">make-ca Dependencies</bridgehead>
77
78 <bridgehead renderas="sect4">Recommended</bridgehead>
79 <para role="recommended"><xref linkend="p11-kit"/> (required at runtime to
80 generate certificate stores from trust anchors)</para>
81
82 <bridgehead renderas="sect4">Optional (runtime)</bridgehead>
83 <para role="optional">
84 <ulink role="runtime" url="&blfs-book;general/openjdk.html">OpenJDK</ulink>
85 (to generate a java PKCS#12 store), and
86 <ulink role="runtime" url="&blfs-book;postlfs/nss.html">nss</ulink>
87 (to generate a shared NSSDB)
88 </para>
89
90 <para condition="html" role="usernotes">User Notes:
91 <ulink url='&blfs-wiki;/make-ca'/></para>
92 </sect2>
93
94 <sect2 role="installation">
95 <title>Installation of make-ca</title>
96
97 <para>The <application>make-ca</application> script will download and
98 process the certificates included in the <filename>certdata.txt</filename>
99 file for use as trust anchors for the <xref linkend="p11-kit"/> trust
100 module. Additionally, it will generate system certificate stores used by
101 BLFS applications (if the recommended and optional applications are present
102 on the system). Any local certificates stored in
103 <filename>/etc/ssl/local</filename> will be imported to both the trust
104 anchors and the generated certificate stores (overriding Mozilla's trust).
105 Certificates in this directory should be stored as PEM encoded
106 <application>OpenSSL</application> trusted certificates.</para>
107
108 <para>To create an <application>OpenSSL</application> trusted certificate
109 from a regular PEM encoded file, you need to add trust arguments to the
110 <command>openssl</command> command, and create a new certificate. There are
111 three trust types that are recognized by the
112 <application>make-ca</application> script, SSL/TLS, S/Mime, and code
113 signing. For example, using the
114 <ulink url="http://www.cacert.org/">CAcert</ulink> roots, if you want to
115 trust both for all three roles, the following commands will create
116 appropriate OpenSSL trusted certificates (run as the <systemitem
117 class="username">root</systemitem> user):</para>
118
119<screen role="nodump"><userinput>install -vdm755 /etc/ssl/local &amp;&amp;
120wget http://www.cacert.org/certs/root.crt &amp;&amp;
121wget http://www.cacert.org/certs/class3.crt &amp;&amp;
122openssl x509 -in root.crt -text -fingerprint -setalias "CAcert Class 1 root" \
123 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
124 > /etc/ssl/local/CAcert_Class_1_root.pem &amp;&amp;
125openssl x509 -in class3.crt -text -fingerprint -setalias "CAcert Class 3 root" \
126 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
127 > /etc/ssl/local/CAcert_Class_3_root.pem</userinput></screen>
128
129 <para>If one of the three trust arguments is omitted, the certificate is
130 neither trusted, nor rejected for that role. Clients that use
131 <application>OpenSSL</application> or <application>NSS</application>
132 encountering this certificate will present a warning to the user. Clients
133 using <application>GnuTLS</application> without
134 <application>p11-kit</application> support are not aware of trusted
135 certificates. To include this CA into the ca-bundle.crt (used for
136 <application>GnuTLS</application>), it must have <envar>serverAuth</envar>
137 trust. Additionally, to explicitly disallow a certificate for a particular
138 use, replace the <parameter>-addtrust</parameter> flag with the
139 <parameter>-addreject</parameter> flag.</para>
140
141 <para>To install the various certificate stores, first install the
142 <application>make-ca</application> script into the correct location.
143 As the <systemitem class="username">root</systemitem> user:</para>
144
145<screen role="root"><userinput>make install</userinput></screen>
146
147 <para>As the <systemitem class="username">root</systemitem> user, after
148 installing <xref linkend="p11-kit"/>, download the certificate source and
149 prepare for system use with the following command:</para>
150
151 <note>
152 <para>If running the script a second time with the same version of
153 <filename>certdata.txt</filename>, for instance, to add additional stores
154 as the requisite software is installed, add the <parameter>-r</parameter>
155 switch to the command line. If packaging, run <command>make-ca
156 --help</command> to see all available command line options.</para>
157 </note>
158
159<screen role="root"><userinput>/usr/sbin/make-ca -g</userinput></screen>
160
161 <para>You should periodically update the store with the above command
162 either manually, or via a <phrase revision="sysv">cron job.</phrase>
163 <phrase revision="systemd">systemd timer. A timer is installed at
164 <filename>/etc/systemd/system/update-pki.timer</filename> that, if enabled,
165 will check for updates weekly.</phrase></para>
166
167 <para>The default <filename>certdata.txt</filename> file provided by make-ca
168 is obtained from the mozilla-release branch, and is modified to provide a
169 Mercurial revision. This will be the correct version for most
170 systems. There are, however, several other variants of the file available
171 for use that might be preferred for one reason or another, including the
172 files shipped with Mozilla products in this book. RedHat and OpenSUSE,
173 for instance, use the version included in
174 <ulink role="runtime" url="&blfs-book;postlfs/nss.html">nss</ulink>. Additional
175 upstream downloads are available at the links below.</para>
176
177 <itemizedlist spacing="compact">
178 <listitem>
179 <para>Mozilla Release (the version provided by BLFS):
180 <ulink url="&certhost;releases/mozilla-release/raw-file/default/security/nss&certpath;"/>
181 </para>
182 </listitem>
183 <listitem>
184 <para>NSS (this is the latest available version):
185 <ulink url="&certhost;projects/nss/raw-file/tip&certpath;"/>
186 </para>
187 </listitem>
188 <listitem>
189 <para>Mozilla Central:
190 <ulink url="&certhost;mozilla-central/raw-file/default/security/nss&certpath;"/>
191 </para>
192 </listitem>
193 <listitem>
194 <para>Mozilla Beta:
195 <ulink url="&certhost;releases/mozilla-beta/raw-file/default/security/nss&certpath;"/>
196 </para>
197 </listitem>
198 <listitem>
199 <para>Mozilla Aurora:
200 <ulink url="&certhost;releases/mozilla-aurora/raw-file/default/security/nss&certpath;"/>
201 </para>
202 </listitem>
203 </itemizedlist>
204
205 </sect2>
206
207 <sect2 role="content">
208 <title>Contents</title>
209
210 <segmentedlist>
211 <segtitle>Installed Programs</segtitle>
212 <segtitle>Installed Libraries</segtitle>
213 <segtitle>Installed Directories</segtitle>
214
215 <seglistitem>
216 <seg>make-ca</seg>
217 <seg>None</seg>
218 <seg>/etc/ssl/{certs,java,local} and /etc/pki/{nssdb,anchors}</seg>
219 </seglistitem>
220 </segmentedlist>
221
222 <variablelist>
223 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
224 <?dbfo list-presentation="list"?>
225 <?dbhtml list-presentation="table"?>
226
227 <varlistentry id="make-ca-bin">
228 <term><command>make-ca</command></term>
229 <listitem>
230 <para>is a shell script that adapts a current version of
231 <filename>certdata.txt</filename>, and prepares it for use
232 as the system trust store.</para>
233 <indexterm zone="make-ca make-ca">
234 <primary sortas="b-make-ca">make-ca</primary>
235 </indexterm>
236 </listitem>
237 </varlistentry>
238 </variablelist>
239
240 </sect2>
241</sect1>
Note: See TracBrowser for help on using the repository browser.