# How to Integrate mkcert CA with macOS Keychain: Complete Developer Guide

> Integrate mkcert CA with macOS Keychain to automatically trust local certificates. Follow our developer guide and run mkcert -install for seamless integration.

- Repository: [Filippo Valsorda/mkcert](https://github.com/FiloSottile/mkcert)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Run `mkcert -install` to automatically register the local Certificate Authority with the macOS System keychain, enabling trust for all certificates generated by mkcert.**

The `mkcert` tool by FiloSottile creates a local Certificate Authority (CA) that generates trusted development certificates. When you integrate mkcert CA with macOS Keychain, browsers and TLS clients automatically trust certificates signed by this local authority without security warnings. This integration works through platform-specific code in the mkcert repository that interacts directly with the macOS `security` framework and System keychain.

## How mkcert Installs the CA into macOS Keychain

The integration process involves three distinct phases handled by specific source files in the repository: CA generation, CLI command parsing, and macOS-specific trust store manipulation.

### CA Generation in cert.go

When you run mkcert for the first time, the `newCA()` function in **[`cert.go`](https://github.com/FiloSottile/mkcert/blob/main/cert.go)** generates a self-signed root certificate and private key. These files (`rootCA.pem` and `rootCA-key.pem`) are stored in `~/Library/Application Support/mkcert` on macOS. The function creates a standard X.509 certificate with basic constraints set to act as a certificate authority.

### The Installation Command Flow

When you execute `mkcert -install`, the entry point in **[`main.go`](https://github.com/FiloSottile/mkcert/blob/main/main.go)** parses the flag and invokes the `mkcert.install()` method. This method checks that the system trust store is enabled before calling `installPlatform()`, which routes to platform-specific implementations based on the operating system.

### macOS-Specific Trust Store Integration

The **[`truststore_darwin.go`](https://github.com/FiloSottile/mkcert/blob/main/truststore_darwin.go)** file contains the critical integration logic for macOS Keychain. The `installPlatform()` function performs two essential operations:

1. **Certificate Installation**: It executes `security add-trusted-cert -d -k /Library/Keychains/System.keychain <root-cert>` to add the mkcert CA to the system keychain with default trust settings.

2. **Trust Settings Configuration**: Because older Go versions omit default trust parameters, the code explicitly manages trust settings by:
   - Exporting current trust settings via `security trust-settings-export`
   - Modifying the plist in-memory to set trust levels for `sslServer` and `basicX509` policies
   - Re-importing the modified settings via `security trust-settings-import`

After installation, mkcert verifies the integration by attempting to validate the root certificate against the system pool using `x509.Certificate.Verify` in the `checkPlatform()` method.

## Step-by-Step Integration Guide

Follow these commands to integrate mkcert with your macOS Keychain and generate trusted local certificates:

```bash

# Install mkcert via Homebrew

brew install mkcert

# Install the mkcert root CA into the macOS System keychain

mkcert -install

```

The `-install` flag triggers the full installation sequence described above, requiring administrative privileges to modify the System keychain.

After installation, generate certificates for your local development domains:

```bash

# Create a certificate valid for localhost and common local addresses

mkcert localhost 127.0.0.1 ::1

# This creates localhost.pem and localhost-key.pem in the current directory

```

Use these files with your local development server:

```bash

# Example: Python HTTPS server with mkcert certificates

python3 -m http.server 8443 \
  --bind 127.0.0.1 \
  --directory . \
  --certfile localhost.pem \
  --keyfile localhost-key.pem

```

## Verifying the CA Installation

Confirm that mkcert successfully integrated with the macOS Keychain by listing the installed certificate:

```bash
security find-certificate -c "mkcert" -a -Z /Library/Keychains/System.keychain

```

This command searches the System keychain for certificates with "mkcert" in the common name and displays SHA-256 hashes. You should see your local CA certificate listed with trust settings applied for SSL.

## Removing the mkcert CA from macOS Keychain

When you need to remove the CA (for example, when uninstalling mkcert), use the `-uninstall` flag:

```bash
mkcert -uninstall

```

This invokes `uninstallPlatform()` in [`truststore_darwin.go`](https://github.com/FiloSottile/mkcert/blob/main/truststore_darwin.go), which executes `security remove-trusted-cert -d <root-cert>` to delete the entry from the System keychain and removes associated trust settings.

## Summary

- **[`cert.go`](https://github.com/FiloSottile/mkcert/blob/main/cert.go)** generates the root CA using `newCA()` and stores it in `~/Library/Application Support/mkcert`
- **[`main.go`](https://github.com/FiloSottile/mkcert/blob/main/main.go)** handles the `-install` flag and orchestrates the installation process through `mkcert.install()`
- **[`truststore_darwin.go`](https://github.com/FiloSottile/mkcert/blob/main/truststore_darwin.go)** contains macOS-specific code that uses the `security` command to add the CA to `/Library/Keychains/System.keychain` and configures explicit trust settings for SSL and X.509
- The installation requires administrative privileges to modify the System keychain
- Use `mkcert -uninstall` to remove the CA using the `uninstallPlatform()` method

## Frequently Asked Questions

### Does mkcert require sudo to install the CA on macOS?

Yes, integrating mkcert CA with macOS Keychain requires administrative privileges. The `security add-trusted-cert` command modifies the System keychain located at `/Library/Keychains/System.keychain`, which is protected by macOS. The mkcert tool will prompt for your password when running `mkcert -install` to execute these privileged operations.

### Where does mkcert store the root CA files on macOS?

mkcert stores the root CA certificate and private key in `~/Library/Application Support/mkcert` (or the directory specified by the `CAROOT` environment variable). The files are named `rootCA.pem` and `rootCA-key.pem`. While the certificate is safe to share, you must protect the `rootCA-key.pem` file as it represents the private key of your local Certificate Authority.

### Why does mkcert modify trust settings explicitly instead of relying on default trust?

According to the source code in [`truststore_darwin.go`](https://github.com/FiloSottile/mkcert/blob/main/truststore_darwin.go), older versions of the Go standard library omitted default trust settings when adding certificates via the Security framework. To ensure the CA is trusted for SSL/TLS connections (`sslServer`) and general X.509 validation (`basicX509`), mkcert exports the current trust settings, modifies the plist to add explicit trust policies, and re-imports the configuration using `security trust-settings-import`.

### Can I use mkcert certificates in Safari without manual configuration?

Yes, once you run `mkcert -install`, certificates generated by mkcert are automatically trusted by Safari, Chrome, and other macOS applications that use the system certificate store. The integration modifies the macOS System keychain directly, so no manual certificate import is required in individual browsers or trust stores.