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.

Comments
  • Add FreeBSD support

    Add FreeBSD support

    This PR adds FreeBSD (plain and simple systemstore) support.

    With this commit:

    • Mkcert finally compiles on FreeBSD
    • build & use cases tested on hw arm32/arm64/amd64
    • detects if the fbsd caroot base pkg or compatible is installed.
    • If true, it installs the cert into the system store.

    Optional Background Info Notes:

    • FreeBSD does by default not enforce the use of su, sudo or doas.
    • There is a dedicated 'tool' (script) certctl https://cgit.freebsd.org/src/tree/usr.sbin/certctl/certctl.sh
    • It manages by default the usual nss trust dumpster via hash-id symlinks within /usr/share/...
    • Hiding a mitm abuseable cert in the dumpsters via hash-id might be not a good idea, so i skiped the link part.

    Greetings, Michael

    opened by paepckehh 0
  • Installing in Firefox and/or Chrome/Chromium failed

    Installing in Firefox and/or Chrome/Chromium failed

    Environment

    • Operating system (including version): Ubuntu 22.04
    • mkcert version (from mkcert -version): 1.4.4
    • Server (where the certificate is loaded): localhost
    • Client (e.g. browser, CLI tool, or script): browser (chrome/chromium)

    What you did

    • installed the binaries as instructed
    • mkcert -install

    What went wrong

    The local CA is already installed in the system trust store! 👍
    Installing in Firefox and/or Chrome/Chromium failed. Please report the issue with details about your environment at https://github.com/FiloSottile/mkcert/issues/new 👎
    Note that if you never started Firefox and/or Chrome/Chromium, you need to do that at least once.
    
    opened by harvey56 2
  • feat: allow setting max pathlen constraint

    feat: allow setting max pathlen constraint

    This PR allows customizing the pathLenConstraint. This can be useful, if you want to create intermediate certificate CAs.

    It also replaces usages of io/ioutil with os, which is deprecated in Go 1.16

    opened by Trojan295 0
  • Firefox 107 - SEC_ERROR_BAD_SIGNATURE

    Firefox 107 - SEC_ERROR_BAD_SIGNATURE

    Environment

    • Operating system (including version): Windows 10 Home 22H Build 19045.2251
    • mkcert version (from mkcert -version): v1.4.4
    • Server (where the certificate is loaded): XAMPP 8.6.1 localhost
    • Client (e.g. browser, CLI tool, or script): Firefox 107

    What went wrong

    Prior to Firefox 107, self sign certs generated by mkcert worked fine on my localhost installation.

    After Firefox updated to 107, I get the following error:

    Secure Connection Failed

    An error occurred during a connection to localhost. Peer’s certificate has an invalid signature.

    Error code: SEC_ERROR_BAD_SIGNATURE

    The page you are trying to view cannot be shown because the authenticity of the received data could not be verified.
    Please contact the website owners to inform them of this problem.
    

    Not sure if the updated Firefox changed something, but if anyone has any ideas, please let me know.

    opened by lumin888 1
  • Fatal error when `JAVA_HOME` is set incorrectly

    Fatal error when `JAVA_HOME` is set incorrectly

    Environment

    • Operating system (including version): macOS 12.4 (21F79)
    • mkcert version (from mkcert -version): v1.4.4
    • Server (where the certificate is loaded): N/A
    • Client (e.g. browser, CLI tool, or script): N/A

    What you did

    Ran mkcert -install

    What went wrong

    Error for reference

    $ mkcert -install
    The local CA is now installed in the system trust store! ⚡️
    ERROR: failed to execute "keytool -list": exit status 1
    
    keytool error: java.lang.Exception: Keystore file does not exist:
    

    I have my JAVA_HOME ($HOME/homebrew/opt/openjdk) set to a user based homebrew location but it seems that neither of the following files exists causing the util to fatally abort.

    • $JAVA_HOME/lib/security/cacerts https://github.com/FiloSottile/mkcert/blob/2a46726cebac0ff4e1f133d90b4e4c42f1edf44a/truststore_java.go#L47
    • $JAVA_HOME/jre/lib/security/cacerts https://github.com/FiloSottile/mkcert/blob/2a46726cebac0ff4e1f133d90b4e4c42f1edf44a/truststore_java.go#L51

    This forces the util to execute an invalid command with a missing param passed to -keystore.

    $HOME/homebrew/opt/openjdk/bin/keytool -list -keystore  -storepass changeit
    

    tl;dr when using a java install via homebrew set your JAVA_HOME to somewhere that has the file mkcert is looking for 😅.

    This is ultimately what worked for me 🥳.

    JAVA_HOME=<homebrewDir>/Cellar/openjdk/19/libexec/openjdk.jdk/Contents/Home"
    

    Hope this helps anyone else who runs into a similar issue.

    opened by Hacksore 4
Releases(v1.4.4)
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 55 Sep 14, 2022
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 16 Nov 9, 2022
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 183 Dec 23, 2022
Generate and sign TSL certificates with ease.

certctl Manage certificates with ease.

Chen Zhiwei 9 Oct 20, 2022
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 43 Nov 1, 2022
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 50 Nov 7, 2022
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 43 Dec 14, 2022
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 34 Sep 14, 2022
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 3 Dec 11, 2022
⚡️Curated list of resources for the development and applications of blockchain.

Awesome Blockchain Curated list of resources for the development and applications of block chain. The blockchain is an incorruptible digital ledger of

null 2.7k Jan 9, 2023
OpenZeppelin Contracts is a library for secure smart contract development.

A library for secure smart contract development. Build on a solid foundation of community-vetted code. Implementations of standards like ERC20 and ERC

OpenZeppelin 21k Jan 5, 2023
Curated list of resources for the development and applications of block chain

Awesome Blockchain Curated list of resources for the development and applications of block chain. The blockchain is an incorruptible digital ledger of

Rieser Stern 0 Dec 28, 2021
Minlib - Multi-Identifier Network Development Library

minlib 1. Install git clone https://gitea.qjm253.cn/PKUSZ-future-network-lab/min

null 9 Jan 7, 2022
Greenhouse - Integrated Solidity development platform

Greenhouse Integrated solidity environment. Tutorial Start an empty folder and i

null 5 Nov 29, 2022
Running chaincode in development mode: Smart contract developers that want to iteratively develop and test their chaincode packages without the overhead of the smart contract lifecycle process for every update.

Fabric DEVMODE - Nano bash 1 ORG + 1 PEER + 1 ORDERER Based on fabric-samples/test-network-nano-bash, but using devmode fabric peer Prereqs Follow the

Kmilo Denis González 3 May 14, 2022
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 74 Dec 16, 2022
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 12.6k Jan 7, 2023
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 117 Dec 23, 2022