Create Locally Trusted SSL Certificates on Linux|macOS using mkcert

Are you tired of using non-trusted SSL certificates for your Local development projects?. For sure it is pain in the neck to maintain your own Certificate Authority(CA), with arcane procedures and commands. In this guide, I’ll show you a simple way to use trusted SSL certificates on your Local development machine without having CA.

mkcert is a simple zero-config tool written by Filippo Valsorda in Go for making locally trusted development certificates with any names you’d like without any configuration. This will help you since it is impossible to get certificates from trusted Certificate Authorities for local names that don’t have a valid DNS record. So let’s dive in to install and use mkcert.

Install mkcert on Ubuntu / Debian

To install mkcert on any Ubuntu or Debian system, first, install certutil dependencies:

sudo apt-get update
sudo apt install wget libnss3-tools

Once this has been installed, download mkcert binary package from Github. Check mkcert releases page for the latest version.

curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest| grep browser_download_url  | grep linux-amd64 | cut -d '"' -f 4 | wget -qi -

Once the file has been downloaded, make the file executable and place the binary under /usr/loa/bin

mv mkcert-v*-linux-amd64 mkcert
chmod a+x mkcert
sudo mv mkcert /usr/local/bin/

Install mkcert on CentOS / Fedora System

Installation of mkcert on CentOS and Fedora is similar to Ubuntu/Debian installation. You only need to install nss-tools tools first.

sudo yum install nss-tools

Once installed, download the binary package like for Ubuntu installation.

curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest| grep browser_download_url  | grep linux-amd64 | cut -d '"' -f 4 | wget -qi -

Once the file has been downloaded, make the file executable and place the binary under /usr/local/bin

mv mkcert-v*-linux-amd64 mkcert
chmod a+x mkcert
sudo mv mkcert /usr/local/bin/

Install mkcert on Arch Linux | Manjaro | Garuda

For Arch Linux, you can install mkcert using the above procedure or using AUR. For installation, you need to use an AUR helper, I recommend yay for this: yay – Best AUR Helper for Arch Linux / Manjaro

Once you install yay, install mkcert from it using:

yay -S --noconfirm --needed go
yay -S --noconfirm --needed mkcert

How to Install mkcert on macOS

For macOS users, you can download the binary package or install mkcert from.brew

brew install mkcert
brew install nss # if you use Firefox

For binary install:

curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest| grep browser_download_url  | grep darwin-amd64 | cut -d '"' -f 4 | wget -qi -

Once the file has been downloaded, make the file executable and place the binary under /usr/local/bin

mv mkcert-v*-darwin-amd64 mkcert
chmod a+x mkcert
sudo mv mkcert /usr/local/bin/

Confirm successful installation by checking the version:

$ mkcert --version
v1.4.3

Use mkcert to generate locally trusted SSL certificates

mkcert has support for the following root stores:

• macOS system store
• Windows system store
• Linux variants that provide either
  • update-ca-trust (Fedora, RHEL, CentOS) or
  • update-ca-certificates (Ubuntu, Debian)
• Firefox (macOS and Linux only)
• Chrome and Chromium
• Java (when JAVA_HOME is set)

To get the help page for mkcert, pass the option--help.

Usage of mkcert:

$ mkcert -install
Install the local CA in the system trust store.

$ mkcert example.org
Generate "example.org.pem" and "example.org-key.pem".

$ mkcert example.com myapp.dev localhost 127.0.0.1 ::1
Generate "example.com+4.pem" and "example.com+4-key.pem".

$ mkcert '*.example.com'
Generate "_wildcard.example.com.pem" and "_wildcard.example.com-key.pem".

$ mkcert -pkcs12 example.com
Generate "example.com.p12" instead of a PEM file.

$ mkcert -uninstall
Uninstall the local CA (but do not delete it).

Change the CA certificate and key storage location by setting $CAROOT,
print it with "mkcert -CAROOT".

You can get your CA root directory using:

$ mkcert -CAROOT
/root/.local/share/mkcert

You need to start by installing the local CA in your system trust store.

# mkcert -install
The local CA is now installed in the system trust store! ⚡️
The local CA is now installed in the Firefox and/or Chrome/Chromium trust store (requires browser restart)! 🦊

Once done, you can start generating SSL certificates for your domains. As an example, I’ll generate a new certificate valid for the following names:

- "mydomain.com"
- "*.mydomain.co"
- "myapp.net"
- "localhost"
- "127.0.0.1"
- "::1"

The output will be like below:

# mkcert mydomain.com '*.mydomain.co' myapp.net localhost 127.0.0.1 ::1
Created a new certificate valid for the following names 📜
 - "mydomain.com"
 - "*.mydomain.co"
 - "myapp.net"
 - "localhost"
 - "127.0.0.1"
 - "::1"

Reminder: X.509 wildcards only go one level deep, so this won't match a.b.mydomain.co ℹ️

The certificate is at "./mydomain.com+5.pem" and the key at "./mydomain.com+5-key.pem" ✅

It will expire on 11 January 2024 🗓

You should be able to view the contents of the certificate:

# cat ./mydomain.com+5.pem
-----BEGIN CERTIFICATE----- MIIEVDCCArygAwIBAgIRAL2vyvexRiXjWMWF688t9RswDQYJKoZIhvcNAQELBQAw WTEeMBwGA1UEChMVbWtjZXJ0IGRldmVsb3BtZW50IENBMRcwFQYDVQQLDA5yb290 QHVidW50dS0wMTEeMBwGA1UEAwwVbWtjZXJ0IHJvb3RAdWJ1bnR1LTAxMB4XDTE4 MDgxNTA2MjIzMFoXDTI4MDgxNTA2MjIzMFowQjEnMCUGA1UEChMebWtjZXJ0IGRl dmVsb3BtZW50IGNlcnRpZmljYXRlMRcwFQYDVQQLDA5yb290QHVidW50dS0wMTCC ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMg6ByQe5vjX65HYoOe/QyRo yotQOvBX8k8RJxQSXmTYsTGeYjTtlfLlubJ/AmGovzfPK6CmSWkTK6czENsR2DBH mAHyyu1PdeJihnBZSNAlkEIGNPZvxqKlNZvqe1gxMntHG569YKBl52EaiMiDu3D0 yk+dvIHuCtvGseFUxRwnc4gq4B6yhyGR6y1dmL7eZkrIAgMHxdktavThscvJ3N7A N4dY7iackLiajqjRzT6/iVR0NRRbqxDlgsfrq6MGkAnri56LuZBZmyF85c+kpvuN bHEAAUvxziHORX0+NmBedcajr16rYV4+/IJXbY2llLkprRG2Ar8CqrblH2uBX+8C AwEAAaOBrTCBqjAOBgNVHQ8BAf8EBAMCBaAwEwYDVR0lBAwwCgYIKwYBBQUHAwEw DAYDVR0TAQH/BAIwADAfBgNVHSMEGDAWgBRLV1qAcMY0/atqn4AS3sWCOoo4OTBU BgNVHREETTBLggxteWRvbWFpbi5jb22CDSoubXlkb21haW4uY2+CCW15YXBwLm5l dIIJbG9jYWxob3N0hwR/AAABhxAAAAAAAAAAAAAAAAAAAAABMA0GCSqGSIb3DQEB CwUAA4IBgQBaQcM7oe4TNQfdwvkZk0rTK1aoXteBF7JqxdhFqL1wWNAO+HTsRuzO My19o3mL+9SVjuv1NCEUCVGXQ5FK+HFdBdWm1cAKzHM/j6pwo0k60K9kIfyQZfsh GjDDtrE+86T16JwWTozFyyZHDAhskQuudwha4pZWgrwZudAdqaAOQW59+8s3gYaj Wd10hiptLbAnhd3DKPgnhjgpIT6zvtJ7gvm8fXVwOyoPfbIm3kl94rIa0BVrhmeA ma227ehRK0iUwA1oclZ4dbRfcjNgL79ryVgffOgTD1O3mWzwvGenD7/oG9FZQ2fK WPdh4gdV+f5fZ+GiLA2KPIShrReFlt70pUJDkDHT0AEuSiFZQ5vVc3KV/3k3HUTJ tmkiePMoMGB/kEVyo1is3NDUBkofMTYSFjVdSgZ9rrefoUe/tfqBeh5IV+ZRUv3p kSsXe0sBnqtSa5ExQ+Uv2X6/jEBBEAoYN6GmL+poV06Ra6/nnXPnaRLkQ/8CT8sp xKtvdnyDa6Y= -----END CERTIFICATE-----

The private key is:

ls mydomain.com+5-key.pem

Testing mkcert certificate

Let’s now test mkcert certificate using a simple Nginx configuration file. Forgive me this example is done on Ubuntu 18.04 system.

### Ubuntu / Debian ###
sudo apt update
sudo apt install nginx

### CentOS / Fedora ###
sudo yum install nginx
sudo systemctl enable --now nginx

Create a simple web page

# vim /etc/nginx/conf.d/test.conf 
server {
   listen 80;
   server_name mydomain.com myapp.net;
   root /var/www/test;
}

server {
   listen *:443 ssl http2;
   root /var/www/test;
   server_name mydomain.com myapp.net;
   ssl_certificate /root/mydomain.com+5.pem; 
   ssl_certificate_key /root/mydomain.com+5-key.pem;
}

Make sure your /etc/hosts file has a record for used domains.

127.0.0.1 myapp.net
127.0.0.1 mydomain.com

Open your browser and use domain provided, you should get a green bar.

Also, read:

Generating Letsencrypt Wildcard SSL certificate

Configure Jenkins behind Nginx reverse proxy and Let’s Encrypt SSL

How to Configure Nginx Proxy for Semaphore Ansible Web UI

Secure LDAP Server with SSL/TLS on Ubuntu 18.04/16.04