Self-signed certificates

Modern web-browsers are making it more and more difficult to use non-secured HTTP even when debugging on a local machine where trust is inherent. Therefore, web-developers must set up self-signed certificates on their development machines for the most basic operations.

This guide shows how to set up a local development machine with self-signed certificates for SSL secure HTTP debugging.

Local development certificate authority and SSL certificate USING mkcert()

Create a local certificate authority

Certificate authorities are holders of private/public keys that are known to be trusted.

The mkcert() utility was created to perform the tedious tasks of creating a root Certificate Authority public and private key-pair. It also adds the Certificate Authority to the local machine's general list of Certificate Authorities.

With mkcert() a Certificate Authority (CA) is generated simply by typing mkcert --install

In Ubuntu Linux, this CA key-pair is stored in your ~/.local/share/mkcert/ directory as rootCA.pem and rootCA-key.pem

It also gets added to the /usr/local/share/ca-certificates/ directory as mkcert_development_CA_[longnumber].crt

After this, mkcert() runs the update-ca-certificates utility that coalesces all of the certificates in /etc/ssl/certs/ and /usr/local/share/ca-certificates/ into one big file called /etc/ssl/certs/ca-certificates.crt

Import your new certificate authority into your browser

The new certificate authority may still not be trusted by your browser. To get past this barrier, go to Settings|Privacy and security|Security|Manage certificates|Authorities|Import and select the certificate (not the key) to import into your browser. It may be useful to check the imported certificate's trust settings to ensure that it is trusted for websites. You will probably find it under org-mkcert development CA

Generate a certificate for a local development domain-name

After generating your root Certificate Authority with mkcert(), you can generate local server certificates by typing mkcert localdevname [localname2 ...]

This will generate a local key and certificate which can then be used by your HTTP server (such as NGINX) by adding these lines to your local server configuration block.

ssl_certificate /pathtocert/localdevname.pem;
ssl_certificate_key /pathtocert/localdevname-key.pem;


1 / 2023
Create a local development certificate authority and SSL certificate WITHOUT mkcert()

Become your own Certificate Authority (CA)

It all boils down to trust.

Certificate authorities are holders of private/public keys that are known to be trusted. How do they get on The List? We don't care. They are there and we are not. So, we have to establish ourselves as our own trusted certificate authorities, and add ourselves to the trusted authorities list.

This is probably a good time to brush up on modern security concepts like private keys, public keys, and what is a "certificate".

Here are the steps to setting up your own local certificate authority:

Generate a key: eg. CA-local.key
openssl genrsa -des3 -out CA-local.key 2048
Generate a root certificate: eg. CA-local.crt
openssl req -x509 -new -nodes -key CA-local.key -sha256 -days 3653 -out CA-local.pem
Add the root certificate to your Linux development machine.
sudo ln -s CA-local.pem /usr/local/share/ca-certificates/CA-local.crt
sudo update-ca-certificates
Add the root certificate to your browser.
Import the certificate into your Certificate authorities in Settings|Privacy and security|Security|Manage certificates|Authorities|Import
After importing the certificate, your selections to trust the certificate may not have gotten saved. If this is the case, then go to the certificate and edit it to check the boxes of trusting the certificate. If you used the default organization in setting up your certificate, it will be under org-Internet Widgits Pty Ltd
Add the certificate to Chrome-Project-based browsers.
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n CA-local -i CA-local.pem

Create a local development SSL certificate

After you set up your local development computer as a trusted certificate authority, you then need to create a certificate for your local site or sites.

To create a certificate for a local site:

Generate a new key for the local site
openssl genrsa -des3 -out CA-local-example.key 2048
Make a certificate signing request (CSR)
openssl req -new -key local-example.key -out local-example.csr
Create an X509 V3 certificate extension configuration file
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

DNS.1 =
DNS.2 = localhost
DNS.3 =
DNS.4 = local-example.stage
Generate the local development certificate using the key, CSR, and extension
openssl x509 -req -in example-dev.csr -CA CA-local.pem -CAkey CA-local.key \
-CAcreateserial -out local-dev.crt -days 3650 -sha256 -extfile local-dev.ext


3 / 2023