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

11.0 11.1 11.2 lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since e40b2f25 was e40b2f25, checked in by Xi Ruoyao <xry111@…>, 16 months ago

tag, mainly for CA related stuff

  • Property mode set to 100644
File size: 12.6 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/releases/download/v&make-ca-version;/make-ca-&make-ca-version;.tar.xz">
13 <!ENTITY make-ca-size "28.5 KB">
14 <!ENTITY make-ca-md5sum "e0356f5ae5623f227a3f69b5e8848ec6">
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. For
224 instance, you might need to add an organization or government CA
225 certificate. Files in this directory must be in the
226 <application>OpenSSL</application> trusted certificate format. To
227 create an <application>OpenSSL</application> trusted certificate from
228 a regular PEM encoded file, you need to add trust arguments to the
229 <command>openssl</command> command, and create a new certificate. For
230 example, using the <ulink url="http://www.cacert.org/">CAcert</ulink>
231 roots, if you want to trust both for all three roles, the following
232 commands will create appropriate OpenSSL trusted certificates (run as
233 the <systemitem class="username">root</systemitem> user after <xref
234 linkend="wget"/> is installed):
235 </para>
236
237<screen role="nodump"><userinput>wget http://www.cacert.org/certs/root.crt &amp;&amp;
238wget http://www.cacert.org/certs/class3.crt &amp;&amp;
239openssl x509 -in root.crt -text -fingerprint -setalias "CAcert Class 1 root" \
240 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
241 > /etc/ssl/local/CAcert_Class_1_root.pem &amp;&amp;
242openssl x509 -in class3.crt -text -fingerprint -setalias "CAcert Class 3 root" \
243 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
244 > /etc/ssl/local/CAcert_Class_3_root.pem &amp;&amp;
245/usr/sbin/make-ca -r -f</userinput></screen>
246
247 <bridgehead renderas="sect3">Overriding Mozilla Trust</bridgehead>
248
249 <para>
250 Occasionally, there may be instances where you don't agree with
251 Mozilla's inclusion of a particular certificate authority. If you'd like
252 to override the default trust of a particular CA, simply create a copy of
253 the existing certificate in <filename
254 class="directory">/etc/ssl/local</filename> with different trust
255 arguments. For example, if you'd like to distrust the
256 "Makebelieve_CA_Root" file, run the following commands:
257 </para>
258
259<screen role="nodump"><userinput>openssl x509 -in /etc/ssl/certs/Makebelieve_CA_Root.pem \
260 -text \
261 -fingerprint \
262 -setalias "Disabled Makebelieve CA Root" \
263 -addreject serverAuth \
264 -addreject emailProtection \
265 -addreject codeSigning \
266 > /etc/ssl/local/Disabled_Makebelieve_CA_Root.pem &amp;&amp;
267/usr/sbin/make-ca -r -f</userinput></screen>
268
269 </sect2>
270
271 <sect2 role="content">
272 <title>Contents</title>
273
274 <segmentedlist>
275 <segtitle>Installed Programs</segtitle>
276 <segtitle>Installed Directories</segtitle>
277
278 <seglistitem>
279 <seg>make-ca</seg>
280 <seg>/etc/ssl/{certs,local} and
281 /etc/pki/{nssdb,anchors,tls/{certs,java}}</seg>
282 </seglistitem>
283 </segmentedlist>
284
285 <variablelist>
286 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
287 <?dbfo list-presentation="list"?>
288 <?dbhtml list-presentation="table"?>
289
290 <varlistentry id="make-ca-bin">
291 <term><command>make-ca</command></term>
292 <listitem>
293 <para>
294 is a shell script that adapts a current version of
295 <filename>certdata.txt</filename>, and prepares it for use
296 as the system trust store
297 </para>
298 <indexterm zone="make-ca make-ca">
299 <primary sortas="b-make-ca">make-ca</primary>
300 </indexterm>
301 </listitem>
302 </varlistentry>
303 </variablelist>
304
305 </sect2>
306
307</sect1>
Note: See TracBrowser for help on using the repository browser.