7.6 KiB
| layout | slug | status | sitemap | title | category | tags | |
|---|---|---|---|---|---|---|---|
| post | dev-with-tls | published | true | Develop with TLS | developpement |
|
In this article we focus on openssl as it is generally available and, hopefully, it is versatile enough to adapt all our uses cases. Note that most straightforward tools exist, such as mkcert, that simplify many steps presented here.
This article is not exhaustive to keep it readable but do not hesitate to complete it with
the corresponding openssl manpage, and you can start with man openssl but keep in mind that openssl
works with subcommands that have dedicated manpages (eg. the manpage for openssl x509 is man x509 on my Fedora).
In this guide, our target is to create a simple CA for local development purposes only. Do not reproduce this practises in production or you will put yourself, your organization and your users at risk.
In our commands, we do not specify an output format while multiple formats exist such as PEM or DER often denoted by various extensions.
By default, openssl always use PEM encoding, which stands for Privacy-Enhanced Mail and is defined in RFC 7468. In my experience, this format is supported in many places and produce base64 encoded text files. Often we use the .pem extension to denote a PEM encoded file but in practise, like in this article, we also create files with the .crt or .key extension while storing PEM encoded content inside the file.
After this preamble, let's start generating our certificates by choosing a working folder:
export D=$HOME/.certs/localhost/
mkdir -p $D
The Certificate Authority
It is mandatory to create a CA certificate that is independant from our End-entity Certificate:
otherwise you will have an error such as CA_CERT_USED_AS_END_ENTITY in Firefox.
For this article, I arbitrarily chose to generate an Elliptic Curve Key (and not a RSA one) that will be our CA private key.
openssl ecparam \
-genkey \
-name prime256v1 \
-out $D/ca.key
For more information about this command, run man ecparam, read Bortzmeyer post (FR) or directly the RFC 8422.
Now, we want to generate a self-signed X.509 certificate for our Certificate Authority from the previously generated private key. An expiration date is mandatory for a certificate. We set it to 10 years (3650 days) to not be annoyed in the near future by the expiration of our certificate but be sure to set it to a shorter time in production.
openssl req \
-x509 \
-new \
-key $D/ca.key \
-days 3650 \
-out $D/ca.pem \
-subj "/C=XX/ST=XX/L=XX/O=XX/OU=XX/CN=LOCAL_CA/emailAddress=X@X.XX"
For more information on this command, run man req.
Now that our CA is ready, we can add it in the CA store of our system and/or applications. Each software, OS and distribution as its own procedure, in this guide I only cover Fedora.
sudo cp $D/ca.pem /etc/pki/ca-trust/source/anchors/localhost.crt
sudo update-ca-trust
For Windows, Mac OS, Debian/Ubuntu, Firefox or Chrome, you can refer to BounCA's guide.
And that's all, we have our certificate authority in our system!
End-entity Certificate
Now, we will generate a private key for our future application certificate and sign it with our CA. We start with the private key:
openssl ecparam \
-genkey \
-name prime256v1 \
-out $D/localhost.key
Then we generate a Certificate Signing Request.
The CN field is important as it will be checked against your domain name in many cases.
Here, we want a certificate for our development needs so we set it to localhost.
But we also want a valid certificate when we access our service through IP address.
Additionnaly, we want to support an infinite number of subdomains to test multiple services at the same time.
At this point, we need to use an extension to set the subjectAltName key.
Before going further, let digress a little bit on how to choose a domain for development that will not overlap with a (possibly) existing internet service. Know that RFC 6761 says that .localhost is a reserved TLD, so we are sure it will never be advertised by root DNS servers and limited to our machine.
To summarize, we want a single certificate that is valid for (1) localhost, (2) all subdomains of localhost and (3) for the IP address 127.0.0.1 (and we could add a (4) for ::1, the IPv6 loopback address). We simply must set the subjectAltName key to DNS:localhost, DNS:*.localhost, IP:127.0.0.1.
The full command to generate a certificate signature request looks like this:
openssl req \
-new \
-key $D/localhost.key \
-out $D/localhost.csr \
-subj "/C=XX/ST=XX/L=XX/O=XX/OU=XX/CN=localhost/emailAddress=X@X.XX" \
-addext "subjectAltName = DNS:localhost, DNS:*.localhost, IP:127.0.0.1"
And finally we sign the request (CSR) with our own authority (CA).
This command is a bit more tricky as we have to set again some fields.
It seems to be for security reasons: as this operation is thought to be done by a third party,
it should not trust your parameters and set its own. In our case, we need to re-specify the number of days and our subjectAltName.
openssl has a more advanced/high level tool, openssl ca (doc: man ca), that is able to copy some or all fields of a signing request but this tool has some other caveats. If you are interested, please read its WARNINGS section in the manual.
Our final command is:
openssl x509 \
-req \
-in $D/localhost.csr \
-CA $D/ca.pem \
-CAkey $D/ca.key \
-CAcreateserial \
-out $D/localhost.crt \
-days 3650 \
-extensions v3_ext \
-extfile <(printf "[ v3_ext ]\nsubjectAltName = DNS:localhost, DNS:*.localhost, IP:127.0.0.1\n")
You can run man x509 to know more about this command.
With socat
socat is a swiss army knife for your network needs. In this example, we will use it as a simple TLS proxy in front of a plain text application.
First, we need to concatenate our certificate in a bundle for socat. The key must comes first, then its X.509 certificats, and the whole chain of X.509 certificates up your root certificates.
For us:
cat \
$D/localhost.key \
$D/localhost.crt \
$D/ca.pem \
> $D/localhost-bundle.pem
For nginx, you need to concatenate X.509 certificates in the same order but you must not put the private key file. Instead, the private key file is specified independently in your configuration.
To run socat on port 4443 with TLS and forward requests in plain text to localhost:3900, run:
socat \
"openssl-listen:4443,\
reuseaddr,\
fork,\
verify=0,\
cert=$D/localhost-bundle.pem" \
tcp4-connect:localhost:3900
reuseaddr enables to not wait for an internal timeout in the kernel after shutdowning a process using the same port, the article Bind: Address already in use explains on details why. fork allows us to handle multiple connections in parallel. verify allows us to activate or deactivate mutual authentication, here we do not want to authenticate the client so we set it to zero.
Other resources
Some other resources that could help you with TLS/X.509 certificates: