“Standard” certificate authorities (CAs) like Let’s Encrypt are just exactly that: They wait for applicants, sign their certificate signing requests, and return end entity (EE) certificates to the applicants.
But when I setup my own public key infrastructure, I typically have both my own CA and a couple of EE certificates, signed by my CA, in my own hands.
I need a PKI that I can configure (but only if I want) and that creates all files that are related to a certificate (e.g. the key pair, the CSR, but also certificate chains and PKCS#12 files and such) in the correct order, and only if needed.
Each PKI “solution” I found so far is either proprietary or is just a
Howto of OpenSSL callings. Easy-RSA makes a
very good job, but it also has the separation between CA and EE, and I
have to execute several easyrsa calls by hand.
The PKI tools wrap the execution of the OpenSSL commands for creating a CA, EE certificates, and the signing of the certificates by the related CA.
All files, related to a particular certificate (e.g. the private key pair and the CSR) are stored in one directory. Instead of transferring the CSR to the related CA, signing it there, and transferring the signed certificate back to the requester, the CA makes a “house call”.
The PKI tools create a file, only if it is necessary, that is, if it is not already available, or if it is older than the file(s), it depends on.
For each step, one gen-... script is responsible, which
is a wrapper for the related OpenSSL call. The handling is the same for
all certificates (including the root CA, which for example also has its
CSR, that is, there is no special “root CA magic”, except that the root
CA of course signs its own CSR).
All steps are executed in a well-defined order by a
Makefile.
Each command may be executed at any time without harm, that is, the
PKI tools will not overwrite existing irretrievable files
accidentally. (The only exceptions are the “dangerous”
make clean... commands.)
As a prerequisite, you need bash, openssl, and GNU make. On a “Debianic” system, install them as follows (unless already available):
sudo apt-get install bash openssl makeFurthermore, you need Functional Bash, because it makes my life easier. Clone and “install” it from GitLab as described there.
Now, clone pki_tools to an arbitrary directory, e.g. to
~/repositories:
mkdir -p ~/repositories && cd $_
git clone https://gitlab.com/w6g/pki_toolsExcept of Functional Bash (where one script has to be copied
to /usr/local/lib - I hope, you can live with this), no
actual installation is necessary (e.g. additions to
PATH or alike).
In the PKI tools environment, the root CA signs the certificates of the following intermediate CAs:
A server EE certificate is used by a web server, but also by a mail server, a VPN server or WPA-TLS (Radius).
A client EE certificate is used by a web client, a mail server (for a client connection to another mail server), a VPN client, or WPA-TLS.
A user EE certificate is used for S/MIME, but is also useful for WPA-TLS, when the certificates are related to real persons (“users”) instead of (machine) clients.
In the following, we will setup our own PKI with a root CA, an intermediate CA (for servers), and a server EE, named server1.
Okay, it’s quite a mouthful. But I think, this way you can see best, how to handle the PKI tools.
First of all, we create a directory that will contain our PKI. (Do
not use the PKI tools directory for that.) Since it is a good
idea to have our PKI under (Git) version control, we use
~/repositories/pki.
Normally, we would use rsa as algorithm for our certificate
keys. But different algorithms are also possible, e.g. ECDSA
(ec for short). The algorithms should not be mixed up;
therefore, we will create a subdirectory with our selected algorithm
name: ~/repositories/pki/ec.
A certificate belongs to a domain, e.g. example.org. It is
possible to handle more than one domain. To keep things clear, we use a
subdirectory with the same name as the domain:
~/repositories/pki/ec/example.org. Let’s create and enter
this directory path:
mkdir -p ~/repositories/pki/ec/example.org && cd $_You are totally free in selecting a directory structure. The path above is just a suggestion.
Now, we let the PKI tools create a global configuration for
our selected algorithm and domain. For this, we call
~/repositories/pki_tools/pki with the full path to the
PKI tools directory:
~/repositories/pki_tools/pki -c -d example.org -a ecOption -c creates a (global) configuration file in the
current directory with the same name as the directory and the file
extension .conf.
Option -d defines the domain in use. Since
example.org is the default, we could also skip
-d example.org here.
With option -a we select the algorithm. Because
rsa is the default, we set -a ec here
explicitly.
After execution, in the current directory we find
pki_tools (a symlink to the PKI tools directory)
and pki (a symlink to the tool pki in the
PKI tools directory). Therefore, it is sufficient to enter
./pki from now on.
example.org.conf is the global configuration file. It
looks as follows:
# example.org.conf
pki_tools_dir = <where you cloned the PKI tools>
chains_with_root = no
# Optional DN elements:
#
# countryName = C
# stateOrProvinceName = ST
# localityName = L
# organizationName = O
# organizationalUnitName = OU
# emailAddress = emailAddress
days = 365
crldays = 365
# Optional absolute dates in ISO 8601 format instead of 'days' and 'crldays':
#
# startdate = YYYY-MM-DDTHH:MM:SSZ
# enddate = YYYY-MM-DDTHH:MM:SSZ
# crlenddate = YYYY-MM-DDTHH:MM:SSZ
# Optional Certificate Revocation List Distribution Point:
#
# crl_base_uri = http://crldp.example.org
domain = example.org
algorithm = ec
ec_paramgen_curve = secp521r1
# EOF - vim:cc=0:syn=dosiniThis file is allowed to be modified. Once the file is created, it is not overwritten. If you re-enter the command above, you will get the message
pki: 'example.org.conf' already exists - not overwritten!to prevent your possible modifications from being lost. You must move the file out of the way by hand after double-check.
pki_tools_dir is the path to the PKI tools directory and is unlikely to be changed.
chains_with_root is initially set to no. Setting this option to yes adds chain files that contain the root CA certificate as last element. (A chain file is a file that contains the concatenation of certificates.) chains_with_root is useful for DANE TLSA, but normally it is not necessary to add the root CA certificate to a chain. So, we leave this option unchanged.
As a default, the distinguished name (DN) only contains the common name (CN). It is possible to add further elements, e.g. countryName = DE. But we leave this unchanged for now.
Option days defines the number of days a certificate will be valid. Option crldays defines the number of days until the next update of a certificate revocation list. Both options define the validity start time as now.
As an alternative, the option startdate defines the absolute beginning of a certificate validity (now, if unset), and option enddate defines the absolute end time of a certificate validity.
Option crlenddate defines the absolute time of the next CRL update. Note that there is no crlstartdate option available.
The format of the absolute time values is ISO 8601, e.g. 2024-07-18T21:07:42Z. Shorter expressions are also possible, e.g. 2024-07-18.
At least days or enddate as well as crldays or crlenddate must be given, where absolute time values take precedence over the days and crldays values.
Later, you may adjust the validity time values individually for each certificate in its local configuration (see below).
It is possible to define a Certificate Revocation List Distribution Point with option crl_base_uri. As a default, there is no CRLDP set, that is, the option is commented out.
The options domain and algorithm hold the values
that have been set at pki execution via command line option
-d or -a, respectively.
Depending on the algorithm, an additional option may be set: For rsa the option rsa_bits defines the key size in bits (default: 4096). For ec the option ec_paramgen_curve defines the elliptic curve in use (default: secp521r1).
The next step is to create a local configuration for the root CA. We enter our example.org directory (unless we are already there):
cd ~/repositories/pki/ec/example.orgInside this directory, we use the tool pki again. Due to
the symlink, we do not need the full path:
./pki -t ca rootOption -t defines the X509 type, which is
ca here. root is the ID.
After execution, we find a new subdirectory, named
example.org_ca_root_ec. This directory will contain all
elements that belong to the root CA (e.g. the root CA certificate
itself).
The directory name consists of the following elements, separated with
underscores: DOMAIN_X509-TYPE_ID_ALGORITHM, example:
example.org_ca_root_ec.
Let’s enter the subdirectory example.org_ca_root_ec and
see, what’s inside:
cd example.org_ca_root_ec && ls -ldb.d contains the root CA database, which consists of
the files index.txt and serial.
Makefile is a symlink to pki_tools/Makefile
(where pki_tools is a symlink to the PKI tools
directory).
example.org_ca_root_ec.conf is the local configuration
file for our root CA:
# example.org_ca_root_ec.conf
commonName = example.org_ca_root_ec
days = 365
crldays = 365
domain = example.org
x509_type = ca
id = root
algorithm = ec
ec_paramgen_curve = secp521r1
db_rel_dir = db.d
db_index_file = index.txt
db_serial_file = serial
key_with_password = yes
key_file = example.org_ca_root_ec_key.pem
csr_cnf_file = example.org_ca_root_ec_csr.cnf
csr_file = example.org_ca_root_ec_csr.pem
cert_cnf_file = example.org_ca_root_ec_cert.cnf
cert_file = example.org_ca_root_ec_cert.pem
crl_cnf_file = example.org_ca_root_ec_crl.cnf
crl_file = example.org_ca_root_ec_crl.pem
# EOF - vim:cc=0:syn=dosiniSome options (e.g. the validity time values) are copied from the global configuration. Therefore, the local configuration depends on the global configuration.
The local configuration file is allowed to be modified as well. As usual: Once the file is created, it is not overwritten, even if necessary.
When you re-enter ./pki -t ca root (which is always
allowed), pki checks, if–assumed that the local
configuration exists–the global configuration is newer than the local
configuration. In this case, pki stops with a related
message. You have to move the local configuration out of the way by
hand.
commonName defines the common name (CN), which is used to identify a certificate in an unambiguous way. Unless changed in the local configuration, the CN is equal to the name of the directory, where the config file resides.
key_with_password is set to yes per default for the root CA, which results in a password-protected private key.
The local configuration also defines the names of the files that will
be built. All files have the CN as “basename”. The file extension
defines the format, e.g. .pem for PEM of a certificate in
PEM format or .cnf for an OpenSSL configuration file (see
below). The type, e.g. certificate signing request or
certificate, is separated from the CN with an underscore. e.g.
example.org_ca_root_rsa_cert.pem for the root CA
certificate in PEM format.
We are still in the directory example.org_ca_root_ec
that we created in the last section. The Makefile defines,
which steps are executed in which order. If you want to know, which
script is called by make, just enter
make -nThis way, the make tool outputs each script call without executing it.
To build the root CA finally, enter
makeThis creates the following files (in that order):
example.org_ca_root_ec_key.pem: the private key file
(pair),example.org_ca_root_ec_csr.cnf: the OpenSSL config file
for the CSR,example.org_ca_root_ec_csr.pem: the CSR file,example.org_ca_root_ec_cert.cnf: the OpenSSL config
file for the certificate,example.org_ca_root_ec_cert.pem: the certificate
file,example.org_ca_root_ec_crl.cnf: the OpenSSL config file
for the CRL,example.org_ca_root_ec_crl.pem: the CRL file.We will be asked for a (new) pass phrase, which we have to re-enter for the CSR, the cert, and the CRL.
As already mentioned, the .cnf files are OpenSSL
configuration files. Instead of using one file like
openssl.cnf, for each file that needs an OpenSSL
configuration there is a related dedicated .cnf file
available.
It is allowed to edit OpenSSL configuration files as well. An already
(maybe modified) .cnf file will not be overwritten, even if
it were necessary.
Try what happens, if you re-enter make.
With our root CA available, we can now setup a server intermediate CA. We go back to our example.org directory:
cd ..There, we enter:
./pki -t ca serverThe X509 type is still ca, but the ID is server now.
After execution, we find the new subdirectory
example.org_ca_server_ec. Let’s go inside:
cd example.org_ca_server_ecdb.d contains the server CA database, which consists of
the files index.txt and serial.
Makefile and pki_tools are symlinks in the
same way as for the root CA.
example.org_ca_server_ec.conf is the local configuration
file for our server CA and looks quite similar to the local root CA
configuration.
Like the local configuration for the root CA, the local configuration for the server intermediate CA has adopted some options from the global configuration, e.g. days and crldays. You may adjust these values (or replace them with their “absolute” counterparts), if you don’t want to have the intermediate CA certificate the same lifetime as the root CA certificate.
The option parent_ca_dir defines the directory path to the parent CA. For the server CA, this is the root CA. (The root CA configuration does not have this entry, because the root CA does not have a parent.)
The option chain_file defines the name of the file that contains the concatenation of the server CA certificate and the root CA certificate.
We are still in the directory example.org_ca_server_ec
that we created in the last section. To build the server CA, enter
makeThis creates the related files in the same way as for the root CA
plus
example.org_ca_server_ec-example.org_ca_root_ec_chain.pem.
With our server intermediate CA available, we can now setup a server EE, named server1 as an example. We go back to our example.org directory:
cd ..There, we enter:
./pki -t server server1Now, the X509 type is server, and the ID is server1.
After execution, we find the new subdirectory
example.org_server_server1_ec. Let’s go inside:
cd example.org_server_server1_ecThe configuration looks a bit different now: We don’t have a
db.d entry, since an EE is not a CA. But we have
definitions for PKCS files instead (see below).
The local configuration for a server EE sets the Subject Alternative Name to DNS:id.domain, e.g. DNS:server1.example.org. Change the line subjectAltName = … accordingly, if you don’t want that.
More than one subjectAltName element can be set as in the following example with an entry for the domain itself and an additional wildcard domain entry:
subjectAltName = DNS:example.org, DNS:*.example.orgWe are still in the directory
example.org_server_server1_ec that we created in the last
section. To build the server EE, enter
makeThis creates the related files in the same way as for the root CA and the server intermediate CA, but of course adapted to the EE needs.
The file ffdhe4096.pem holds the finite field
group values, recommended by RFC 7919 (downloaded from here).
The PKCS#7 file contains the certificates and the CRL. Inspect it as follows:
openssl pkcs7 -in example.org_server_server1_ec_p7b.pem -print_certs -textHave a look at the PKCS#12 file as follows:
openssl pkcs12 -in example.org_server_server1_ec.pfx -nodesWhen you are asked for an Import Password, use the content
of the file example.org_server_server1_ec_pfx.pwd. (Maybe,
it’s a good idea to store this password in a password safe, e.g. pass - the standard unix password
manager.)
There is a tool available, called export, which is not
executed automatically. When you call it this way:
pki_tools/exportit creates the directory export with some subdirectories
and copies the files, created by make, to them. This might
be useful, if you want to setup a server with your brand new certificate
stuff.
export works also for client and user
EEs (but not for CAs). Enter pki_tools/export -h for a
“manual page”.
For a server, the files from the client and the user intermediate CAs
are interesting as well. Thus, since we have not created the client and
the user intermediate CAs yet, export will complain:
export: not all files found, export is incomplete!When we retry export later with all intermediate CAs
available, the complaint will be gone.
With our knowledge, we now can create further intermediate CAs and EEs.
cd ~/repositories/pki/ec/example.org
./pki -t ca client
cd example.org_ca_client_ec
makeAs an alternative, we can combine the configuration and
make to one step:
cd ~/repositories/pki/ec/example.org
./pki -m -t ca client# We are still in '~/repositories/pki/ec/example.org'.
./pki -m -t client client1./pki -m -t ca user./pki -m -t user user1As a default, the local configuration for a user EE sets the Subject Alternative Name to email:id@domain, e.g. email:user1@example.org. Change or comment out the line subjectAltName = … there, if you don’t want that.
Let us revoke the user1 certificate, due to reason superseded:
cd example.org_user_user1_ec
pki_tools/revoke -r supersededNow, the directory example.org_user_user1_ec contains
the file REVOKED. You can use the tool
verify:
pki_tools/verifyYou can use the tool verify also recursively:
cd ..
pki_tools/verify -rThere is a further (hopefully useful) tool:
check-expiry:
pki_tools/check-expiry -rFor our domain example.com, we need (RSA) certificate stuff for a root CA, server / client / user intermediate CAs, and three server EEs, two client EEs, and four user EEs. No big deal:
mkdir -p ~/repositories/pki/rsa/example.com && cd $_
~/repositories/pki_tools/pki -c -d example.com # 'rsa' is default
./pki -m -t ca root server client user
./pki -m -t server server1 server2 server3
./pki -m -t client client1 client2
./pki -m -t user user1 user2 user3 user4Re-check at any time, whether all certificates are (still) okay:
pki_tools/verify -rAre there certificates that are in danger of expiring (or even already expired)? Find out:
pki_tools/check-expiry -rDo you remember when we created our PKI “start directory”
~/repositories/pki/ec/example.org? Let’s go back to this
directory and execute yet another convenience tool:
cd ~/repositories/pki/ec/example.org
~/repositories/gitlab/bash/pki_tools/export-recursivelyNow, you find the new directory EXPORT inside. For each
EE, it contains a subdirectory with the same name as the EE,
e.g. server1 as well as a compressed archive,
e.g. server1.tar.bz2. You may copy the complete directory
structure, e.g. for server1, to its final destination, e.g.
/etc/ssl.
You can call all (script) tools with option -h to get a
“manual page”, by the way.
Bash is available on any Linux system. I like it best for scripting purposes.
Functional Bash allows me to write Bash scripts in a
functional style. I just like stuff like this:
list "${ids[@]}" | lmap hdl_id.
When each script does only what its name implies, it is shorter and
easier to read than one monolithic “monster” script. For example, if you
want to know, how OpenSSL is called to create a CSR, guess, what script
you have to investigate. (It’s gen-csr.)
I need an established mechanism that allows me to define
dependencies. With these dependencies, all files are created in a
well-defined order and only if needed. make -n shows in
advance, what is called in which order.
GNU make does a good job for decades. It is generic, that is, it doesn’t matter how to use it (for C source files, DNS zone files, Postfix configuration files, X509 certificate files, …). It is available on any Linux system. Last, but not least, I know for years, how to use it.
I still think that it is a good idea to have our PKI under (Git) version control. But since Git’s checkout (or cloning) does not preserve file timestamps, make would rebuild everything afterwards.
To avoid this, consider metastore, which does a
good job for me, together with the script
metastore_hook.
If you use pass, then
have a closer look at add-pfx-pwds-to-pass. As usual: Call
the script with option -h to get its “manual page”.
ffdhe4096.pem for?The file ffdhe4096.pem contains predefined DH groups.
For the reason, why to use predefined DH groups, see here.
Apache (since httpd-2.4.51-2) ignores DH parameters provided via
SSLOpenSSLConfCmd (see also here).
Therefore, the content of the file ffdhe4096.pem (with its
recommended FFDHE values) is concatenated to the certificate chain
files, used by a server EE.
export is a convenience tool that copies all files,
needed for an EE, to a dedicated directory. Since the default (which is
export in the current directory) is typically not the end
destination, you will mostly call export with option
-e for defining your destination directory
explicitly. Furthermore, export contains some “derivation
heuristic” for parent CA directories, which might fail under some
circumstances. Call export with option -h for
details.
Okay, in this case, see Separate CA for details.