mkcert

Tools for generating self-signed certificates

Example

mkcert is written in GO, a simple zero configuration tool for generating self-signed certificates.

Here is a simple example to generate a self-signed certificate locally and use nc to use the generated certificate.

~ ·············································· ··············································· ····································  10:46:25
❯ mkcert-install
The local CA is already installed in the system trust store! The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! 
~ ·············································· ··············································· ····································  10:46:34
❯ mkcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1

Created a new certificate valid for the following names  - "example.com"
  - "*.example.com"
  - "example.test"
  - "localhost"
  - "127.0.0.1"
  - "::1"

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

The certificate is at "./example.com+5.pem" and the key at "./example.com+5-key.pem" 
It will expire on 30 January 2025 🗓

~ ·············································· ··············································· ····································  10:47:37
❯ls
Public Video Documentation Music aria aria2-downloads Dockerfile example.com+5.pem GOPATH minio-binaries nowip_hosts.txt tech_backend.jar
Template Image Download Desktop aria2-config cv_debug.log example.com+5-key.pem go math navicat_reset src
~ ·············································· ··············································· ····································  10:47:55
❯ ncat -lvp 1589 --ssl-key example.com+5-key.pem --ssl-cert example.com+5.pem
Ncat: Version 7.92 (https://nmap.org/ncat)
Ncat: Listening on :::1589
Ncat: Listening on 0.0.0.0:1589
Ncat: Connection from 127.0.0.1.
Ncat: Connection from 127.0.0.1:39156.
Ncat: Failed SSL connection from 127.0.0.1: error:00000000:lib(0):func(0):reason(0)

mkcert automatically generates and installs a local CA into root stores and generates locally-trusted certificates. mkcert will not automatically configure the server with the certificate, however, this is up to you.

Install

Warning: The rootCA-key.pem file automatically generated by mkcert provides complete capabilities to intercept security requests on your machine. Please don't share it.

macOS

$ brew install mkcert
$ brew install nss # If using Firefox

Linux

On Linux, first install certutil

$ sudo apt install libnss3-tools
# -or-
$ sudo yum install nss-tools
# -or-
$ sudo pacman -S nss
# -or-
$ sudo zypper install mozilla-nss-tools

You can then install it using Homebrew on Linux.

$ brew install mkcert

Or build from source (requires Go 1.13+)

git clone https://github.com/FiloSottile/mkcert && cd mkcert
go build -ldflags "-X main.Version=$(git describe --tags)"

Or use pre-built binaries.

$ curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
$ chmod +x mkcert-v*-linux-amd64
$ sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert

For Arch Linux users (like me), mkcert is available in the official Arch Linux repository.

$ sudo pacman -S mkcert

Windows

Use Chocolatey

$ choco install mkcert

Or use Scoop

$ scoop bucket add extras
$ scoop install mkcert

Either build from source (requires Go 1.10+) or use pre-built binaries.

If you encounter permission issues, run mkcert as administrator

Supported root stores

mkcert supports the following root stores:

To install the local root CA into these root stores, you can set the TRUST_STORES environment variable to a comma-separated list. There are these options: "system", "java" and "nss" (including Firefox).

Advanced topics

advanced options

-cert-file FILE, -key-file FILE, -p12-file FILE
     # Customize the output path.
-client # Generate a certificate for client authentication.
-ecdsa # Generate a certificate using an ECDSA (an elliptic curve signature algorithm) key.
-pkcs12 # Generate a ".p12" PKCS #12 file, which can also be recognized as a ".pfx" file,
         # Contains cert and key for legacy applications.
-csr CSR # Generate a certificate for a CSR (Certificate Signing Request).
          # Conflicts with all flags and parameters except -install and -cert-file!

SSL Certificate What is CSR? -FAQ-Document Center-Tencent Cloud

**Please note! ** You must put these options before the domain name list.

For example

mkcert -key-file key.pem -cert-file cert.pem example.com *.example.com

S/MIME (Mail Security Certificate)

Using mkcert will generate an S/MIME certificate in the following way:

mkcert filippo@example.com

mobile device

For mobile devices to trust the certificate, you will need to install a root CA. It is the file rootCA.pem. You can print out the directory where this file is located through mkcert -CAROOT.

On iOS, you can also use AirDrop to send the CA email to yourself, or serve it through an HTTP server. After opening it, you need to install the profile in Settings > Profile Downloaded and then [enable full trust in it](https: //support.apple.com/en-nz/HT204477).

For Android, you have to install this CA and enable user roots in the development version of your application. You can take a look at this StackOverflow answer.

Use this root with Node.js

Node does not use system root store, so it will not automatically accept mkcert certificates. Instead, you set the NODE_EXTRA_CA_CERTS environment variable.

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

Change the location of the CA file

The CA certificate and its key are stored in a folder in the user's home directory. Generally you don't want to pay attention to its location because it will be automatically loaded. But you can print the directory location via mkcert -CAROOT.

If you want to manage individual CAs, you can use the \$CAROOT environment variable to set the path where mkcert places and looks for CA files.

Install CA on other systems

Installing the trust store does not require a CA key (just the CA), so you can export the CA and install it on other machines using mkcert.

Please remember that mkcert is for development purposes and not recommended for production use, so it should not be used on user terminals, and you should not export or share rootCA-key.pem.