mkcert is a simple tool for making locally-trusted development certificates

Overview

mkcert

mkcert is a simple tool for making locally-trusted development certificates. It requires no configuration.

$ mkcert -install
Created a new local CA 💥
The local CA is now installed in the system trust store! ⚡️
The local CA is now installed in the Firefox trust store (requires browser restart)! 🦊

$ 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"

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

Chrome and Firefox screenshot

Using certificates from real certificate authorities (CAs) for development can be dangerous or impossible (for hosts like example.test, localhost or 127.0.0.1), but self-signed certificates cause trust errors. Managing your own CA is the best solution, but usually involves arcane commands, specialized knowledge and manual steps.

mkcert automatically creates and installs a local CA in the system root store, and generates locally-trusted certificates. mkcert does not automatically configure servers to use the certificates, though, that's up to you.

Installation

Warning: the rootCA-key.pem file that mkcert automatically generates gives complete power to intercept secure requests from your machine. Do not share it.

macOS

On macOS, use Homebrew

brew install mkcert
brew install nss # if you use Firefox

or MacPorts.

sudo port selfupdate
sudo port install mkcert
sudo port install nss # if you use 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

Then you can install 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 the pre-built binaries.

For Arch Linux users, mkcert is available on the official Arch Linux repository.

sudo pacman -Syu mkcert

Windows

On Windows, use Chocolatey

choco install mkcert

or use Scoop

scoop bucket add extras
scoop install mkcert

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

If you're running into permission problems try running mkcert as an Administrator.

Supported root stores

mkcert supports 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, OpenSUSE, SLES) or
    • trust (Arch)
  • Firefox (macOS and Linux only)
  • Chrome and Chromium
  • Java (when JAVA_HOME is set)

To only install the local root CA into a subset of them, you can set the TRUST_STORES environment variable to a comma-separated list. Options are: "system", "java" and "nss" (includes Firefox).

Advanced topics

Advanced options

	-cert-file FILE, -key-file FILE, -p12-file FILE
	    Customize the output paths.

	-client
	    Generate a certificate for client authentication.

	-ecdsa
	    Generate a certificate with an ECDSA key.

	-pkcs12
	    Generate a ".p12" PKCS #12 file, also know as a ".pfx" file,
	    containing certificate and key for legacy applications.

	-csr CSR
	    Generate a certificate based on the supplied CSR. Conflicts with
	    all other flags and arguments except -install and -cert-file.

Note: You must place these options before the domain names list.

Example

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

S/MIME

mkcert automatically generates an S/MIME certificate if one of the supplied names is an email address.

mkcert [email protected]

Mobile devices

For the certificates to be trusted on mobile devices, you will have to install the root CA. It's the rootCA.pem file in the folder printed by mkcert -CAROOT.

On iOS, you can either use AirDrop, email the CA to yourself, or serve it from an HTTP server. After opening it, you need to install the profile in Settings > Profile Downloaded and then enable full trust in it.

For Android, you will have to install the CA and then enable user roots in the development build of your app. See this StackOverflow answer.

Using the root with Node.js

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

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

Changing the location of the CA files

The CA certificate and its key are stored in an application data folder in the user home. You usually don't have to worry about it, as installation is automated, but the location is printed by mkcert -CAROOT.

If you want to manage separate CAs, you can use the environment variable $CAROOT to set the folder where mkcert will place and look for the local CA files.

Installing the CA on other systems

Installing in the trust store does not require the CA key, so you can export the CA certificate and use mkcert to install it in other machines.

  • Look for the rootCA.pem file in mkcert -CAROOT
  • copy it to a different machine
  • set $CAROOT to its directory
  • run mkcert -install

Remember that mkcert is meant for development purposes, not production, so it should not be used on end users' machines, and that you should not export or share rootCA-key.pem.

Issues
  • Starting from Big Sur 11.3 certificate installation requires user interaction

    Starting from Big Sur 11.3 certificate installation requires user interaction

    First, thank you so much for mkcert! I love it and use it often ⭐

    It seems that some default behavior may have changed in macOS 11, as mkcert isn't working out of the box on GitHub Actions with macos-latest. (Ah yes, I just read an issue I referenced and it said Starting from Big Sur 11.3 certificate installation requires user interaction, however it can be bypassed by using SecItemAdd method.)

    I'm getting the same error as reported in https://github.com/FiloSottile/mkcert/issues/94

    And I was advised that I could compile some swift code to solve my issue, similar to what they did in this PR https://github.com/actions/virtual-environments/pull/3311.

    swiftc add-certificate.swift
    sudo ./add-certificate YourCertName.cer
    

    By the time I was done, however, I wasn't using mkcert anymore. I thought this would be a more appropriate solution to build into mkcert.

    opened by potatoqualitee 3
  • Decrease the certificate expiry date

    Decrease the certificate expiry date

    • The certificate expiry date has been modified from 2 years, 3 months to 13 months (397 days). This allows for passing SSL certificate checks that validate the expiry date of the issued server certificate, such as Google Chrome on the Android 11 platform.

    Note that this change only effects the issuing of server certificates and not the root certificate itself.

    opened by i8degrees 0
  • Consider adding manpage?

    Consider adding manpage?

    Hello there!

    I have packaged mkcert in Debian (currently waiting in NEW queue). Would you consider a PR adding install instructions on Debian when the package made it to unstable?

    Also it could be great to have a manpage for mkcert. (the current one is generated with help2man)

    Cheers,

    opened by creekorful 0
  • Mac - Chrome / Not Secure / Certificate is not valid

    Mac - Chrome / Not Secure / Certificate is not valid

    System

    Mac BigSur 11.2.1 Chrome 95.0.4638.69 (Latest version as of this writing)

    Issue

    I'm seeing the "Not Secure" flag in Chrome and a message that "Certificate is not valid"

    image

    When I click the more info icon for the "Certificate is not valid" message, it shows the following with no further indication as to what the problem might be.

    image

    Steps I followed to set up

    1. Created a new certificate w/ mkcert
    2. Added it to Mac's Keychain Access and made sure it was set to "Always Trust"
    3. Configured my Apache server to use the certificate/key for the site in question.
    opened by susanBuck 4
  • Advanced options aren't working

    Advanced options aren't working

    Some Advanced options don't work, for example, in none of these cases :
    mkcert -pkcs12
    or
    mkcert -pkcs12 localhost.p12
    or
    mkcert -pkcs12 localhost.p12 localhost

    opened by danilobatistaqueiroz 0
  • Change or choose rootCA path for a user directory with accented characters

    Change or choose rootCA path for a user directory with accented characters

    Hello,

    I have a Microsoft account that automatically created my Windows account when I installed it. My first name is François and that's how the User folder is written on my PC. This has never been a problem for me until now, but during the mkcert -install, the rootCA files are not written in the right place. I end up with an extra path that can give this kind of thing: C:\Users\Fran├ö├Â┬úÔö¼Ôòæois\AppData\Local\mkcert instead of C:\Users\François\AppData\Local\mkcert.

    Is it possible to change the path of the generated root certificates without using the user folder (for example in the ProgramData folder) or to allow specifying the path when running this command?

    Just to be precise, I'm not asking for the name of the rootCA files to be changed.

    Thanks

    opened by francois-artwai 0
  • Support Firefox in Flatpak (if possible)

    Support Firefox in Flatpak (if possible)

    opened by NoTuxNoBux 0
  • Add support for dependabot

    Add support for dependabot

    • Adds support for daily-scan of dependencies using dependabot.
    opened by gaby 0
  • Default behavior should be to do nothing

    Default behavior should be to do nothing

    I just ran this tool with no arguments, expecting to just get a help screen. However it seems running without arguments actually does something:

    PS C:\> mkcert-v1.4.3-windows-amd64
    Created a new local CA 💥
    Note: the local CA is not installed in the system trust store.
    Run "mkcert -install" for certificates to be trusted automatically ⚠️
    

    Can someone clarify what exactly the program does, if you run it with no arguments? I didnt see any files created in the local directory, so not sure.

    opened by 89z 2
  • Upload mkcert to winget repository

    Upload mkcert to winget repository

    winget is now in active developing and has more and more packages. It will be more convenient to install on Windows if you can upload mkcert to its repository. Here is tutorial: https://github.com/microsoft/winget-pkgs#submitting-a-package. Thank you in advance.

    opened by zhanghua000 1
Releases(v1.4.3)
Owner
Filippo Valsorda
Cryptogopher. Go security lead. @recursecenter alum. RC F'13, F2'17.
Filippo Valsorda
Tooling to validate HTTPS Certificates and Connections Around Web 🕷️

Cassler - SSL Validator Tool If your read fast, it's sounds like "Cassia Eller" Tooling to validate HTTPS Certificates and Connections Around Web ??️

Matheus Fidelis 47 Jul 26, 2021
gdn is a Go module to get domain name from SSL certificates given an IP address

Get Domain Name gdn is a Go module to get domain name from SSL certificates given an IP address Installation Instructions From Source gdn requires go1

Sai Krishna Kothapalli 11 Oct 16, 2021
Golang Library for automatic LetsEncrypt SSL Certificates

Obtains certificates automatically, and manages renewal and hot reload for your Golang application. It uses the LEGO Library to perform ACME challenges, and the mkcert utility to generate self-signed trusted certificates for local development.

Foomo web framework 142 Dec 1, 2021
Generate and sign TSL certificates with ease.

certctl Manage certificates with ease.

Chen Zhiwei 9 Oct 11, 2021
PKI support for SSH certificates

PKI certificates for SSH Introduction SSH certificates are limited in their usefulness - a certificate can only be signed with a single CA key, so no

Matthew Garrett 39 Nov 4, 2021
For whatever reason you want to transfer TLS certificates in kubernetes to Qiniu CDN

Qiniu Certificate Sync For whatever reason you want to transfer TLS certificates in kubernetes to Qiniu CDN This app will upload provided TLS secrets

null 2 Oct 21, 2021
Package filippo.io/intermediates embeds a bundle of known unexpired, unrevoked intermediate certificates chaining to roots in the Mozilla Root Program

filippo.io/intermediates Package intermediates embeds a list of known unexpired, unrevoked intermediate certificates chaining to roots with Websites t

Filippo Valsorda 37 Nov 30, 2021
The Fabric Smart Client is a new Fabric Client that lets you focus on the business processes and simplifies the development of Fabric-based distributed application.

Fabric Smart Client The Fabric Smart Client (FSC, for short) is a new Fabric client-side component whose objective is twofold. FSC aims to simplify th

null 27 Nov 24, 2021
A smart contract development toolchain for Go

ethgen - A smart contract development toolchain for Go A simple yet powerful toolchain for Go based smart contract development Compile solidity contra

Tally 5 Oct 6, 2021
Akroma GO client - Akroma is an EVM based application development platform (smart-contracts).

Akroma Akroma is an EVM based application development platform (smart-contracts). Akroma will utilize a Masternode system, and build out an Oracle pla

null 0 Nov 19, 2021
A dead simple tool to sign files and verify digital signatures.

minisign minisign is a dead simple tool to sign files and verify signatures. $ minisign -G

Andreas Auernhammer 46 Dec 1, 2021
A simple, modern and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability.

A simple, modern and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability.

Filippo Valsorda 9.2k Nov 28, 2021
hack-browser-data is an open-source tool that could help you decrypt data from the browser.

hack-browser-data is an open-source tool that could help you decrypt data ( password|bookmark|cookie|history|credit card|download

idiotc4t 79 Nov 29, 2021
CLI Tool to remove unwanted connections from your Chia Node based on Geo IP Location.

chia-bouncer Tiny CLI tool to remove unwanted connections from your Chia Node based on the Geo IP Location (Country). The Tool is written in golang an

st3ffn 4 Jun 25, 2021
Sekura is an Encryption tool that's heavily inspired by the Rubberhose file system.

It allows for multiple, independent file systems on a single disk whose existence can only be verified if you posses the correct password.

null 49 Nov 18, 2021
EVM frontrunning tool

CAKE SNIPER FRONTRUNNING BOT =================================================== BEFORE STARTING: This bot require you to run the GETH client + use

Supercycled 803 Dec 2, 2021
ddlcpad, *Doki Doki Literature Club Plus Asset Decrypter*, is a tool to decrypt the encrypted asset file on the Doki Doki Literature Club Plus. Writing in golang.

ddlcpad 简体中文 What is this ddlcpad is short of Doki Doki Literature Club Plus Asset Decrypter You can decrypt the *.cy file from Doki Doki Literature C

Aimer Neige 6 Nov 17, 2021
An easy tool to apply transactions to the current EVM state. Optimized for MEV.

sibyl A more embedded version of fxfactorial/run-evm-code. This tool makes it easy to apply transactions to the current EVM state. Call it a transacti

Dialectic 36 Oct 28, 2021
Red team tool that emulates the SolarWinds CI compromise attack vector.

SolarSploit Sample malicious program that emulates the SolarWinds attack vector. Listen for processes that use the go compiler Wait for a syscall to o

TestifySec 16 Oct 11, 2021