source: postlfs/security/make-ca.xml@ 5c3f3856

10.0 10.1 11.0 11.1 11.2 8.4 9.0 9.1 bdubbs/svn elogind lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since 5c3f3856 was 5c3f3856, checked in by DJ Lucas <dj@…>, 4 years ago

Update to make-ca-1.0. Fixes #11401.
Use configuration from bash-completions package if it is installed. Added bash-completion-2.8 to ghe BLFS wiki and linked from profile page. Fixes #11399.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@20770 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/releases/download/v&make-ca-version;/make-ca-&make-ca-version;.tar.xz">
13 <!ENTITY make-ca-size "28 KB">
14 <!ENTITY make-ca-md5sum "b038d38233f970aad60c29dfc0502021">
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">Required</bridgehead>
79 <para role="required"><xref linkend="p11-kit"/> (required at runtime to
80 generate certificate stores from trust anchors)</para>
81 <!-- /usr/bin/trust is needed to extract the certs to /etc/ssl/certs -->
82
83 <bridgehead renderas="sect4">Optional (runtime)</bridgehead>
84 <para role="optional">
85 <xref role="runtime" linkend="java"/> or
86 <xref role="runtime" linkend="openjdk"/> (to generate a java PKCS#12
87 store), and <xref role="runtime" linkend="nss"/> (to generate a shared
88 NSSDB)
89 </para>
90
91 <para condition="html" role="usernotes">User Notes:
92 <ulink url='&blfs-wiki;/make-ca'/></para>
93 </sect2>
94
95 <sect2 role="installation">
96 <title>Installation of make-ca</title>
97
98 <para>The <application>make-ca</application> script will download and
99 process the certificates included in the <filename>certdata.txt</filename>
100 file for use as trust anchors for the <xref linkend="p11-kit"/> trust
101 module. Additionally, it will generate system certificate stores used by
102 BLFS applications (if the recommended and optional applications are present
103 on the system). Any local certificates stored in
104 <filename>/etc/ssl/local</filename> will be imported to both the trust
105 anchors and the generated certificate stores (overriding Mozilla's trust).
106 Certificates in this directory should be stored as PEM encoded
107 <application>OpenSSL</application> trusted certificates.</para>
108
109 <para>To create an <application>OpenSSL</application> trusted certificate
110 from a regular PEM encoded file, you need to add trust arguments to the
111 <command>openssl</command> command, and create a new certificate. There are
112 three trust types that are recognized by the
113 <application>make-ca</application> script, SSL/TLS, S/Mime, and code
114 signing. For example, using the
115 <ulink url="http://www.cacert.org/">CAcert</ulink> roots, if you want to
116 trust both for all three roles, the following commands will create
117 appropriate OpenSSL trusted certificates (run as the <systemitem
118 class="username">root</systemitem> user after
119 <xref linkend="wget"/> is installed):</para>
120
121<screen role="nodump"><userinput>install -vdm755 /etc/ssl/local &amp;&amp;
122wget http://www.cacert.org/certs/root.crt &amp;&amp;
123wget http://www.cacert.org/certs/class3.crt &amp;&amp;
124openssl x509 -in root.crt -text -fingerprint -setalias "CAcert Class 1 root" \
125 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
126 > /etc/ssl/local/CAcert_Class_1_root.pem &amp;&amp;
127openssl x509 -in class3.crt -text -fingerprint -setalias "CAcert Class 3 root" \
128 -addtrust serverAuth -addtrust emailProtection -addtrust codeSigning \
129 > /etc/ssl/local/CAcert_Class_3_root.pem</userinput></screen>
130
131 <para>If one of the three trust arguments is omitted, the certificate is
132 neither trusted, nor rejected for that role. Clients that use
133 <application>OpenSSL</application> or <application>NSS</application>
134 encountering this certificate will present a warning to the user. Clients
135 using <application>GnuTLS</application> without
136 <application>p11-kit</application> support are not aware of trusted
137 certificates. To include this CA into the ca-bundle.crt (used for
138 <application>GnuTLS</application>), it must have <envar>serverAuth</envar>
139 trust. Additionally, to explicitly disallow a certificate for a particular
140 use, replace the <parameter>-addtrust</parameter> flag with the
141 <parameter>-addreject</parameter> flag.</para>
142
143 <para>To install the various certificate stores, first install the
144 <application>make-ca</application> script into the correct location.
145 As the <systemitem class="username">root</systemitem> user:</para>
146
147<screen role="root"><userinput>make install</userinput></screen>
148
149 <para>As the <systemitem class="username">root</systemitem> user, after
150 installing <xref linkend="p11-kit"/>, download the certificate source and
151 prepare for system use with the following command:</para>
152
153 <note>
154 <para>If running the script a second time with the same version of
155 <filename>certdata.txt</filename>, for instance, to add additional stores
156 as the requisite software is installed, add the <parameter>-r</parameter>
157 switch to the command line. If packaging, run <command>make-ca
158 --help</command> to see all available command line options.</para>
159 </note>
160
161<screen role="root"><userinput>/usr/sbin/make-ca -g</userinput></screen>
162
163 <!-- Remove at 8.5 or 9.0 -->
164 <para>Previous version of BLFS used the path
165 <filename>/etc/ssl/ca-bundle.crt</filename> for the
166 <xref linkend="gnutls"/> certificate store. If software is still installed
167 that references this file, create a compatibilty symlink for the old
168 location as the <systemitem class="username">root</systemitem> user:</para>
169
170<screen role="nodump"><userinput>ln -sfv /etc/pki/tls/certs/ca-bundle.crt \
171 /etc/ssl/ca-bundle.crt</userinput></screen>
172
173 <para>You should periodically update the store with the above command
174 either manually, or via a <phrase revision="sysv">cron job.</phrase>
175 <phrase revision="systemd">systemd timer. A timer is installed at
176 <filename>/etc/systemd/system/update-pki.timer</filename> that, if enabled,
177 will check for updates weekly.</phrase></para>
178
179 </sect2>
180
181 <sect2 role="configuration" id="make-ca-config">
182 <title>Configuring make-ca</title>
183
184 <para>Genearally, no configuration is necessary on an LFS system, however,
185 the default <filename>certdata.txt</filename> file provided by make-ca
186 is obtained from the mozilla-release branch, and is modified to provide a
187 Mercurial revision. This will be the correct version for most systems.
188 There are several other variants of the file available for use that might
189 be preferred for one reason or another, including the files shipped with
190 Mozilla products in this book. RedHat and OpenSUSE, for instance, use the
191 version included in <xref linkend="nss"/>. Additional upstream downloads
192 are available at the links included in
193 <filename>/etc/make-ca.conf.dist</filename>. Simply copy the file to
194 <filename>/etc/make-ca.conf</filename> and edit as appropriate.</para>
195
196 <indexterm zone="make-ca make-ca-config">
197 <primary sortas="e-etc-make-ca-conf">/etc/make-ca.conf</primary>
198 </indexterm>
199
200 </sect2>
201
202 <sect2 role="content">
203 <title>Contents</title>
204
205 <segmentedlist>
206 <segtitle>Installed Programs</segtitle>
207 <segtitle>Installed Directories</segtitle>
208
209 <seglistitem>
210 <seg>make-ca</seg>
211 <seg>/etc/ssl/{certs,java,local} and /etc/pki/{nssdb,anchors}</seg>
212 </seglistitem>
213 </segmentedlist>
214
215 <variablelist>
216 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
217 <?dbfo list-presentation="list"?>
218 <?dbhtml list-presentation="table"?>
219
220 <varlistentry id="make-ca-bin">
221 <term><command>make-ca</command></term>
222 <listitem>
223 <para>is a shell script that adapts a current version of
224 <filename>certdata.txt</filename>, and prepares it for use
225 as the system trust store.</para>
226 <indexterm zone="make-ca make-ca">
227 <primary sortas="b-make-ca">make-ca</primary>
228 </indexterm>
229 </listitem>
230 </varlistentry>
231 </variablelist>
232
233 </sect2>
234</sect1>
Note: See TracBrowser for help on using the repository browser.