Skip to content

Generate self-signed, trusted certificates for local development.

License

Notifications You must be signed in to change notification settings

primalskill/devcert

Repository files navigation

Development Certificates Generator

devcert takes away the pain of manually creating self-signed certificates for development.

devcert-photo


Note

⚠️ These certificates are NOT meant to be used on any server other than your local development machine. These certificates are NOT secure and the generated certificate authority by this tool is NOT trusted by browser vendors.

Installation

Grab a pre-built binary.

OR

Clone this repo and compile from source using Go.


Install a pre-built binary

  1. Download the binary for your platform, for example macOS ARM: curl --location https://github.com/primalskill/devcert/releases/download/v1.3.0/devcert_darwin_arm64 --output /usr/local/bin/devcert
  2. Make it an executable: chmod u+x /usr/local/bin/devcert
  3. Generate a certificate for a local domain (see the detailed usage below): devcert example.test

Compile from Source

Prerequisites:

  • Go
  • Make

Execute make release-<desired platform and architecture>. Make will create the binary in ./.bin directory.

Available make commands:

  • make release-win-amd64
  • make release-darwin-amd64
  • make release-darwin-arm64
  • make release-linux-amd64
  • make release-linux-arm64

Supported Platforms

  • macOS
  • Windows
  • Linux (Debian, Ubuntu, OpenSUSE, RHEL, Fedora, Arch Linux)

Usage

$ devcert my-project.local api.my-project.local my-other-project.test

Generating certificate...
Generated at:
  Certificate: ~/.devcert/devcert_my-project.local_multi.crt
  Private Key: ~/.devcert/devcert_my-project.local_multi.key

Valid for:
  1. my-project.local
  2. api.my-project.local
  3. my-other-project.test

You can move the .crt and .key files to your desired location. It will be signed with the CA, no need to trust this certificate separately.

Certificate Info

You can get information on a crt file by executing the following command.

$ devcert info path/to/crt/file.crt

Certificate Info:
  - Is CA: No
  - Generated by devcert: Yes
  - Issuer: Devcert Certificate Authority (CA)
  - Domain(s): example.test, api.example.test
  - Signature Algorithm: SHA256-RSA
  - Version: 3
  - Valid Until: 2024-06-16 11:08:30 +0000 UTC

On First Run

When running the program for the first time, it will ask to run the setup process which creates the necessary directory, generate the CA, and mark it as trusted.

This is a one-time process that needs to be executed before generating domain-specific certificates.

It will execute the following:

  1. Create the ~/.devcert directory
  2. Create a local certificate authority (CA) used to sign other domain-specific certificates.
  3. It will mark the CA as trusted automatically.

Note: The certificate authority (CA) .crt and .key files should be left in the ~/.devcert directory as these files will be loaded when generating a domain-specific certificate.

Example:

$ devcert myapp.local

devcert needs to execute the setup process first.
  - It will create ~/.devcert/ directory.
  - It will create a local certificate authority (CA) to sign future certificates.
  - It will mark the CA as trusted locally.
Do you want to continue? [Y/n]: Y

Creating directory...
Directory ~/.devcert/ created.
Creating certificate authority (CA) files...
Certificate authority (CA) created at
  Certificate: ~/.devcert/devcert_ca.crt
  Private Key: ~/.devcert/devcert_ca.key
Trusting certificate authority...
Certificate authority (CA) marked trusted.

How It Works

All the certificates created by devcert will be placed in the ~/.devcert directory.

Running devcert for the first time will execute the setup process. Once the setup process is completed it will generate the domain-specific certificate.

You can generate as many self-signed, trusted, local certificates for development as you like, the .crt and .key files will be placed in the ~/.devcert directory.

Uninstall

$ devcert uninstall

The uninstall command will:
  - Remove the ~/.devcert/ directory and all the files in it.
  - Remove the /usr/local/bin/devcert executable.
  - Remove the local devcert Certificate Authority (CA).
  
Do you want to continue? [Y/n]: Y

Removing certificate authority configuration...
Certificate authority (CA) is uninstalled.

Known Issues

Fixing SEC_ERROR_REUSED_ISSUER_AND_SERIAL in Firefox

If you are getting this error, it's most likely Firefox preloaded a previously generated certificate authority (CA) in the default browser profile. This happens if the devcert CA files are manually removed and generated again.

To fix it:

  1. Close all instances of Firefox
  2. Go in the profile folder
  • Windows: C:\Users\%userprofile%\AppData\Roaming\Mozilla\Firefox\Profiles\%profile.default%
  • MacOS: ~/Library/Application Support/Firefox/Profiles/<profile folder>
  1. Remove the files cert8.db, cert9.db, cert_override.txt (Note: some of these files may not exist).

Self-signed certificate is not trusted in Xcode Simulator

The self-signed certificate is not trusted in Safari on the Xcode iOS Simulator, this is because, well, it's for local development.

To fix it:

  1. Find the root CA in your home directory: ~/.devcert/devcert_ca.crt
  2. Drag the file onto the iOS Simulator window, this will kick-off the signing process in the background.

Reference

image

https://developer.apple.com/library/archive/qa/qa1948/_index.html