source: postlfs/security/make-ca.xml@ 24aff8a

ken/refactor-virt lazarus trunk
Last change on this file since 24aff8a was 24aff8a, checked in by DJ Lucas <dj@…>, 2 months ago

Update to make-ca-1.9. Fixes #15548.

  • Property mode set to 100644
File size: 13.1 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/lfs-book/make-ca/releases/download/v&make-ca-version;/make-ca-&make-ca-version;.tar.xz">
13 <!ENTITY make-ca-size "30 KB">
14 <!ENTITY make-ca-md5sum "68c8625c9456815ed17e4f2219c79372">
15]>
16
17<sect1 id="make-ca" xreflabel="make-ca-&make-ca-version;">
18 <?dbhtml filename="make-ca.html"?>
19
20 <sect1info>
21 <date>$Date$</date>
22 </sect1info>
23
24 <title>make-ca-&make-ca-version;</title>
25 <indexterm zone="make-ca">
26 <primary sortas="a-make-ca">make-ca</primary>
27 </indexterm>
28
29 <sect2 role="package">
30 <title>Introduction to make-ca</title>
31
32 <para>
33 Public Key Infrastructure (PKI) is a method to validate the authenticity
34 of an otherwise unknown entity across untrusted networks. PKI works by
35 establishing a chain of trust, rather than trusting each individual host
36 or entity explicitly. In order for a certificate presented by a remote
37 entity to be trusted, that certificate must present a complete chain of
38 certificates that can be validated using the root certificate of a
39 Certificate Authority (CA) that is trusted by the local machine.
40 </para>
41
42 <para>
43 Establishing trust with a CA involves validating things like company
44 address, ownership, contact information, etc., and ensuring that the CA
45 has followed best practices, such as undergoing periodic security audits
46 by independent investigators and maintaining an always available
47 certificate revocation list. This is well outside the scope of BLFS (as
48 it is for most Linux distributions). The certificate store provided here
49 is taken from the Mozilla Foundation, who have established very strict
50 inclusion policies described <ulink
51 url="https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/">here</ulink>.
52 </para>
53
54 &lfs110a_checked;
55
56 <bridgehead renderas="sect3">Package Information</bridgehead>
57 <itemizedlist spacing="compact">
58 <listitem>
59 <para>
60 Download (HTTP): <ulink url="&make-ca-download;"/>
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Download size: &make-ca-size;
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Download MD5 Sum: &make-ca-md5sum;
71 </para>
72 </listitem>
73 <listitem>
74 <para>
75 Estimated disk space required: &make-ca-buildsize;
76 </para>
77 </listitem>
78 <listitem>
79 <para>
80 Estimated build time: &make-ca-time;
81 </para>
82 </listitem>
83 </itemizedlist>
84
85 <bridgehead renderas="sect3">make-ca Dependencies</bridgehead>
86
87 <bridgehead renderas="sect4">Required</bridgehead>
88 <para role="required">
89 <xref linkend="p11-kit"/> (required at runtime to
90 generate certificate stores from trust anchors)
91 </para>
92 <!-- /usr/bin/trust is needed to extract the certs to /etc/ssl/certs -->
93
94 <bridgehead renderas="sect4">Optional (runtime)</bridgehead>
95 <para role="optional">
96 <xref role="runtime" linkend="nss"/> (to generate a shared NSSDB)
97 </para>
98
99 <para condition="html" role="usernotes">User Notes:
100 <ulink url='&blfs-wiki;/make-ca'/></para>
101 </sect2>
102
103 <sect2 role="installation">
104 <title>Installation of make-ca</title>
105
106 <para>
107 The <application>make-ca</application> script will download and process
108 the certificates included in the <filename>certdata.txt</filename> file
109 for use as trust anchors for the <xref linkend="p11-kit"/> trust module.
110 Additionally, it will generate system certificate stores used by BLFS
111 applications (if the recommended and optional applications are present
112 on the system). Any local certificates stored in
113 <filename>/etc/ssl/local</filename> will be imported to both the trust
114 anchors and the generated certificate stores (overriding Mozilla's
115 trust). Additionally, any modified trust values will be copied from the
116 trust anchors to <filename>/etc/ssl/local</filename> prior to any
117 updates, preserving custom trust values that differ from Mozilla when
118 using the <command>trust</command> utility from
119 <application>p11-kit</application> to operate on the trust store.
120 </para>
121
122 <para>
123 To install the various certificate stores, first install the
124 <application>make-ca</application> script into the correct location.
125 As the <systemitem class="username">root</systemitem> user:
126 </para>
127
128<screen role="root"><userinput>make install &amp;&amp;
129install -vdm755 /etc/ssl/local</userinput></screen>
130
131 <para>
132 As the <systemitem class="username">root</systemitem> user, after
133 installing <xref linkend="p11-kit"/>, download the certificate source and
134 prepare for system use with the following command:
135 </para>
136
137 <note>
138 <para>
139 If running the script a second time with the same version of
140 <filename>certdata.txt</filename>, for instance, to add additional
141 stores as the requisite software is installed, add the
142 <parameter>-r</parameter> switch to the command line. If packaging,
143 run <command>make-ca --help</command> to see all available command
144 line options.
145 </para>
146 </note>
147
148<screen role="root"><userinput>/usr/sbin/make-ca -g</userinput></screen>
149
150 <para>
151 You should periodically update the store with the above command,
152 either manually, or via a <phrase revision="sysv">cron job.</phrase>
153 <phrase revision="systemd">systemd timer. A timer is installed at
154 <filename>/usr/lib/systemd/system/update-pki.timer</filename> that, if
155 enabled, will check for updates weekly.</phrase><phrase
156 revision="sysv">If you've installed <xref linkend="fcron"/> and
157 completed the section on periodic jobs, execute</phrase> <phrase
158 revision="systemd">Execute</phrase> the following commands, as the
159 <systemitem class="username">root</systemitem> user, to <phrase
160 revision="sysv">create a weekly cron job:</phrase><phrase
161 revision="systemd">enable the systemd timer:</phrase>
162 </para>
163
164<screen role="nodump" revision="sysv"><userinput>cat &gt; /etc/cron.weekly/update-pki.sh &lt;&lt; "EOF" &amp;&amp;
165<literal>#!/bin/bash
166/usr/sbin/make-ca -g</literal>
167EOF
168chmod 754 /etc/cron.weekly/update-pki.sh</userinput></screen>
169
170<screen role="root" revision="systemd"><userinput>systemctl enable update-pki.timer</userinput></screen>
171
172 </sect2>
173
174 <sect2 role="configuration" id="make-ca-config">
175 <title>Configuring make-ca</title>
176
177 <para>
178 For most users, no additional configuration is necessary, however,
179 the default <filename>certdata.txt</filename> file provided by make-ca
180 is obtained from the mozilla-release branch, and is modified to provide a
181 Mercurial revision. This will be the correct version for most systems.
182 There are several other variants of the file available for use that might
183 be preferred for one reason or another, including the files shipped with
184 Mozilla products in this book. RedHat and OpenSUSE, for instance, use the
185 version included in <xref linkend="nss"/>. Additional upstream downloads
186 are available at the links included in
187 <filename>/etc/make-ca.conf.dist</filename>. Simply copy the file to
188 <filename>/etc/make-ca.conf</filename> and edit as appropriate.
189 </para>
190
191 <indexterm zone="make-ca make-ca-config">
192 <primary sortas="e-etc-make-ca-conf">/etc/make-ca.conf</primary>
193 </indexterm>
194
195 <bridgehead renderas="sect3">About Trust Arguments</bridgehead>
196
197 <para>
198 There are three trust types that are recognized by the
199 <application>make-ca</application> script, SSL/TLS, S/Mime, and code
200 signing. For <application>OpenSSL</application>, these are
201 <parameter>serverAuth</parameter>,
202 <parameter>emailProtection</parameter>, and
203 <parameter>codeSigning</parameter> respectively. If one of the three
204 trust arguments is omitted, the certificate is neither trusted, nor
205 rejected for that role. Clients that use
206 <application>OpenSSL</application> or <application>NSS</application>
207 encountering this certificate will present a warning to the user.
208 Clients using
209 <application>GnuTLS</application> without
210 <application>p11-kit</application> support are not aware of trusted
211 certificates. To include this CA into the
212 <filename>ca-bundle.crt</filename>,
213 <filename>email-ca-bundle.crt</filename>, or
214 <filename>objsign-ca-bundle.crt</filename> files
215 (the <application>GnuTLS</application> legacy bundles), it must have the
216 appropriate trust arguments.
217 </para>
218
219 <bridgehead renderas="sect3">Adding Additional CA Certificates</bridgehead>
220
221 <para>
222 The <filename class="directory">/etc/ssl/local</filename> directory
223 is available to add additional CA certificates to the system trust store.
224 This directory is also used to store certificates that were added to or
225 modified in the system trust store by <xref linkend="p11-kit"/> so that
226 trust values are maintained across upgrades. Files in this directory must
227 be in the <application>OpenSSL</application> trusted certificate format.
228 Certificates imported using the <command>trust</command> utility from
229 <xref linkend="p11-kit"/> will utilize the x509 Extended Key Usage values
230 to assign default trust values for the system anchors.
231 </para>
232
233 <para>If you need to override trust values, or otherwise need to create
234 an <application>OpenSSL</application> trusted certificate manually
235 from a regular PEM encoded file, you need to add trust arguments to the
236 <command>openssl</command> command, and create a new certificate. For
237 example, using the <ulink url="http://www.cacert.org/">CAcert</ulink>
238 roots, if you want to trust both for all three roles, the following
239 commands will create appropriate OpenSSL trusted certificates (run as
240 the <systemitem class="username">root</systemitem> user after <xref
241 linkend="wget"/> is installed):
242 </para>
243
244<screen role="nodump"><userinput>wget http://www.cacert.org/certs/root.crt &amp;&amp;
245wget http://www.cacert.org/certs/class3.crt &amp;&amp;
246openssl x509 -in root.crt -text -fingerprint -setalias "CAcert Class 1 root" \
247 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
248 > /etc/ssl/local/CAcert_Class_1_root.pem &amp;&amp;
249openssl x509 -in class3.crt -text -fingerprint -setalias "CAcert Class 3 root" \
250 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
251 > /etc/ssl/local/CAcert_Class_3_root.pem &amp;&amp;
252/usr/sbin/make-ca -r</userinput></screen>
253
254 <bridgehead renderas="sect3">Overriding Mozilla Trust</bridgehead>
255
256 <para>
257 Occasionally, there may be instances where you don't agree with
258 Mozilla's inclusion of a particular certificate authority. If you'd like
259 to override the default trust of a particular CA, simply create a copy of
260 the existing certificate in <filename
261 class="directory">/etc/ssl/local</filename> with different trust
262 arguments. For example, if you'd like to distrust the
263 "Makebelieve_CA_Root" file, run the following commands:
264 </para>
265
266<screen role="nodump"><userinput>openssl x509 -in /etc/ssl/certs/Makebelieve_CA_Root.pem \
267 -text \
268 -fingerprint \
269 -setalias "Disabled Makebelieve CA Root" \
270 -addreject serverAuth \
271 -addreject emailProtection \
272 -addreject codeSigning \
273 > /etc/ssl/local/Disabled_Makebelieve_CA_Root.pem &amp;&amp;
274/usr/sbin/make-ca -r</userinput></screen>
275
276 </sect2>
277
278 <sect2 role="content">
279 <title>Contents</title>
280
281 <segmentedlist>
282 <segtitle>Installed Programs</segtitle>
283 <segtitle>Installed Directories</segtitle>
284
285 <seglistitem>
286 <seg>make-ca</seg>
287 <seg>/etc/ssl/{certs,local} and
288 /etc/pki/{nssdb,anchors,tls/{certs,java}}</seg>
289 </seglistitem>
290 </segmentedlist>
291
292 <variablelist>
293 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
294 <?dbfo list-presentation="list"?>
295 <?dbhtml list-presentation="table"?>
296
297 <varlistentry id="make-ca-bin">
298 <term><command>make-ca</command></term>
299 <listitem>
300 <para>
301 is a shell script that adapts a current version of
302 <filename>certdata.txt</filename>, and prepares it for use
303 as the system trust store
304 </para>
305 <indexterm zone="make-ca make-ca">
306 <primary sortas="b-make-ca">make-ca</primary>
307 </indexterm>
308 </listitem>
309 </varlistentry>
310 </variablelist>
311
312 </sect2>
313
314</sect1>
Note: See TracBrowser for help on using the repository browser.