Beyond Linux® From Scratch (systemd Edition) - Version r12.0-816

Chapter 4. Security

make-ca-1.13

Introduction to make-ca

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.

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 here.

[Note]

Note

Development versions of BLFS may not build or run some packages properly if LFS or dependencies have been updated since the most recent stable versions of the books.

Package Information

[Note]

Note

This package ships a CA certificate for validating the identity of https://hg.mozilla.org/. If the trust chain of this website has been changed after the release of make-ca-1.13, it may fail to get the revision of certdata.txt from server. Use an updated make-ca release at the release page if this issue happens.

make-ca Dependencies

Required

p11-kit-0.25.3 (runtime, built after libtasn1-4.19.0, required in the following instructions to generate certificate stores from trust anchors, and each time make-ca is run)

Optional (runtime)

nss-3.94 (to generate a shared NSSDB)

Installation of make-ca and Generation of the CA-certificates stores

The make-ca script will download and process the certificates included in the certdata.txt file for use as trust anchors for the p11-kit-0.25.3 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 /etc/ssl/local 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 /etc/ssl/local prior to any updates, preserving custom trust values that differ from Mozilla when using the trust utility from p11-kit to operate on the trust store.

To install the various certificate stores, first install the make-ca script into the correct location. As the root user: 

make install &&
install -vdm755 /etc/ssl/local
[Note]

Note

Technically, this package is already installed at this point. But most packages listing make-ca as a dependency actually requires the system certificate store set up by this package, instead of requiring the make-ca program itself. So the instructions for using make-ca for setting up the system certificate store is included in this section. You should make sure the required runtime dependency for make-ca is satisfied now, and continue to follow the instructions.

As the root user, download the certificate source and prepare for system use with the following command:

[Note]

Note

If running the script a second time with the same version of certdata.txt, for instance, to update the stores when make-ca is upgraded, or to add additional stores as the requisite software is installed, replace the -g switch with the -r switch in the command line. If packaging, run make-ca --help to see all available command line options. 

/usr/sbin/make-ca -g

You should periodically update the store with the above command, either manually, or via a systemd timer. A timer is installed at /usr/lib/systemd/system/update-pki.timer that, if enabled, will check for updates weekly. Execute the following commands, as the root user, to enable the systemd timer: 

systemctl enable update-pki.timer

Configuring make-ca

For most users, no additional configuration is necessary, however, the default certdata.txt 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 nss-3.94. Additional upstream downloads are available at the links included in /etc/make-ca/make-ca.conf.dist. Simply copy the file to /etc/make-ca.conf and edit as appropriate.

About Trust Arguments

There are three trust types that are recognized by the make-ca script, SSL/TLS, S/Mime, and code signing. For OpenSSL, these are serverAuth, emailProtection, and codeSigning respectively. If one of the three trust arguments is omitted, the certificate is neither trusted, nor rejected for that role. Clients that use OpenSSL or NSS encountering this certificate will present a warning to the user. Clients using GnuTLS without p11-kit support are not aware of trusted certificates. To include this CA into the ca-bundle.crt, email-ca-bundle.crt, or objsign-ca-bundle.crt files (the GnuTLS legacy bundles), it must have the appropriate trust arguments.

Adding Additional CA Certificates

The /etc/ssl/local directory is available to add additional CA certificates to the system trust store. This directory is also used to store certificates that were added to or modified in the system trust store by p11-kit-0.25.3 so that trust values are maintained across upgrades. Files in this directory must be in the OpenSSL trusted certificate format. Certificates imported using the trust utility from p11-kit-0.25.3 will utilize the x509 Extended Key Usage values to assign default trust values for the system anchors.

If you need to override trust values, or otherwise need to create an OpenSSL trusted certificate manually from a regular PEM encoded file, you need to add trust arguments to the openssl command, and create a new certificate. For example, using the CAcert roots, if you want to trust both for all three roles, the following commands will create appropriate OpenSSL trusted certificates (run as the root user after Wget-1.21.4 is installed): 

wget http://www.cacert.org/certs/root.crt &&
wget http://www.cacert.org/certs/class3.crt &&
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 &&
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 &&
/usr/sbin/make-ca -r

Overriding Mozilla Trust

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 /etc/ssl/local with different trust arguments. For example, if you'd like to distrust the "Makebelieve_CA_Root" file, run the following commands: 

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 &&
/usr/sbin/make-ca -r

Using make-ca with Python3

When Python3 was installed in LFS it included the pip3 module with vendored certificates from the Certifi module. That was necessary, but it means that whenever pip3 is used it can reference those certificates, primarily when creating a virtual environment or when installing a module with all its wheel dependencies in one go.

It is generally considered that the System Administrator should be in charge of which certificates are available. Now that make-ca-1.13 and p11-kit-0.25.3 have been installed and make-ca has been configured, it is possible to make pip3 use the system certificates.

The vendored certificates installed in LFS are a snapshot from when the pulled-in version of Certifi was created. If you regularly update the system certificates, the vendored version will become out of date.

To use the system certificates in Python3 you should set _PIP_STANDALONE_CERT to point to them, e.g for the bash shell: 

export _PIP_STANDALONE_CERT=/etc/pki/tls/certs/ca-bundle.crt
[Warning]

Warning

If you have created virtual environments, for example when testing modules, and those include the Requests and Certifi modules in ~/.local/lib/python3.11/ then those local modules will be used instead of the system certificates unless you remove the local modules.

To use the system certificates in Python3 with the BLFS profiles add the following variable to your system or personal profiles: 

mkdir -pv /etc/profile.d &&
cat > /etc/profile.d/pythoncerts.sh << "EOF"
# Begin /etc/profile.d/pythoncerts.sh

export _PIP_STANDALONE_CERT=/etc/pki/tls/certs/ca-bundle.crt

# End /etc/profile.d/pythoncerts.sh
EOF

Contents

Installed Programs: make-ca
Installed Directories: /etc/ssl/{certs,local} and /etc/pki/{nssdb,anchors,tls/{certs,java}}

Short Descriptions

make-ca

is a shell script that adapts a current version of certdata.txt, and prepares it for use as the system trust store