mkcert

# mkcert

mkcert is a simple tool for making locally-trusted development certificates. It creates a local certificate authority (CA) and installs it into your system trust store.

## Check if installed

```bash
which mkcert
mkcert --version
```

## Install mkcert

```bash
# macOS
brew install mkcert

# macOS/Linux (NSS support for Firefox)
brew install nss  # optional, for Firefox support

# Windows
choco install mkcert

# Direct download
# https://github.com/FiloSottile/mkcert/releases
```

## Install the root CA

Run once per machine. Installs a root CA into your system keychain so all mkcert-generated certs are trusted.

```bash
mkcert -install
```

This requires admin access (macOS Keychain password or sudo on Linux).

## Generate a certificate

```bash
# For localhost only
mkcert localhost

# For localhost + 127.0.0.1 + ::1 (recommended)
mkcert localhost 127.0.0.1 ::1

# For a custom domain
mkcert myapp.test localhost 127.0.0.1 ::1

# Specify output directory
mkcert -cert-file /path/to/cert.pem -key-file /path/to/key.pem localhost
```

Output:
- `localhost.pem` - the certificate
- `localhost-key.pem` - the private key (keep this secret, 0600 permissions)

## View CA location

```bash
mkcert -CAROOT
# e.g. /Users/you/Library/Application Support/mkcert
```

The CA files are at this path:
- `rootCA.pem` - the CA certificate (safe to share/copy)
- `rootCA-key.pem` - the CA private key (never share this, 0600 permissions)

## Uninstall CA

```bash
mkcert -uninstall
```

Removes the CA from your system trust store. Existing certificates generated from this CA will no longer be trusted.

## How it works

1. `mkcert -install` generates a root CA (`rootCA.pem` + `rootCA-key.pem`) and adds `rootCA.pem` to your system trust store
2. `mkcert localhost` uses the root CA to sign a new certificate for `localhost`
3. Because your system trusts the root CA, it also trusts all certs signed by it
4. Browsers trust whatever the OS trust store says, so no security warnings

## Key paths by platform

| Platform | CA root directory |
|---|---|
| macOS | `~/Library/Application Support/mkcert` |
| Linux | `~/.local/share/mkcert` |
| Windows | `%LOCALAPPDATA%\mkcert` |

## Security notes

- The root CA private key (`rootCA-key.pem`) must stay on your machine. Never commit it or share it.
- File permissions on `rootCA-key.pem` should be `0600`.
- mkcert-generated certs are only valid for your local machine because only your machine has the CA in its trust store.
- The CA is NOT trusted by other machines - this is by design.

## Troubleshooting

### Firefox still shows warning

Install NSS support: `brew install nss`, then re-run `mkcert -install`.

### "permission denied" when running -install

On Linux, you need sudo: `sudo mkcert -install`. On macOS, you need your Keychain password.

### Certificate not trusted in Chrome on Linux

Chrome on Linux uses the NSS database. Install NSS tools: `sudo apt install libnss3-tools`, then `mkcert -install` again.