orndorffgrant/devca

Easily generate certificates for developing services locally over TLS.

DevCA

devca is a command to easily generate certificates for local TLS services during development. Client applications, particularly browsers, behave differently when connecting to plaintext services (like HTTP) compared to secure services (like HTTPS). By creating certificates for your local in-development services, you can develop your services in a more similar environment to a real deployment.

How it works

devca first generates a self-signed certificate authority (CA). It uses that CA to generate certificates for any name that you'd like. In order to get your web browser (or other application) to trust the certificates generated by devca, you need to configure it to trust the CA. Example instructions for Firefox are here. Then you need to configure your in-development service to use the certificate that was signed by the CA for TLS/SSL.

Disclaimer

devca is not designed to be used as anything other than a development certificate authority. It should not be used for managing a real certificate authority. All certificates generated using this tool should be kept private. Most importantly, DO NOT share the CA certificate that you install in your browser with anyone. If an attacker got hold of your development CA, they would be able to impersonate any website to you over HTTPS.

Installation

Pre-built WebAssembly Binary

WebAssembly builds are included in each release.

WebAssembly binaries require a runtime like wasmtime or wasmer. The instructions here assume you have wasmtime installed, but can be adapted to any WebAssembly runtime that supports WASI.

wasmtime and other runtimes run wasm in a sandbox, so you need to explicitly allow access to environment variables and directories. It's recommended that you set up an alias to do this for you as shown below.

First, download the devca.wasm binary from the latest release.

Move the binary to a sensible location and create a directory for devca to put certs in (this will become $DEVCA_HOME in the next step)

mkdir ~/.wasm_bin
mv ~/Downloads/devca.wasm ~/.wasm_bin/devca

mkdir ~/.devca

In your shell startup script, set the $DEVCA_HOME environment variable and set up an alias for devca. If you use bash, add the following to your ~/.bashrc.

export DEVCA_HOME=$HOME/.devca
alias devca="wasmtime run --env DEVCA_HOME=$DEVCA_HOME --dir $DEVCA_HOME $HOME/.wasm_bin/devca --"

Restart your shell and you'll have access to the devca command!

exec bash
devca --version

Build from Source

If you don't trust the sandboxed pre-built WebAssembly binary, or if you need native performance, you can build devca from source.

First, if you don't already have it, install stable rust using the recommended instructions on the rust website: https://www.rust-lang.org/tools/install. This should install cargo as well.

Next, clone the repository and enter the directory in your shell.

git clone https://github.com/orndorffgrant/devca.git
cd devca

Build and install devca using cargo.

cargo install --path .

Make sure $HOME/.cargo/bin is in your $PATH and you should be able to use devca from your shell.

Usage

new command

devca new creates a new certificate for your service to use.

Usage

devca new <name>

Examples

$ devca new localhost
Created certificate authority private key: /home/grant/.local/share/devca/ca/key.pem
Created certificate authority certificate: /home/grant/.local/share/devca/ca/cert.pem
Created private key for "localhost": /home/grant/.local/share/devca/certs/localhost/key.pem
Created certificate for "localhost": /home/grant/.local/share/devca/certs/localhost/cert.pem

The above is an example of what to expect when creating a certificate for the first time. devca will notice that it hasn't created a CA yet and generate it. It will then use the new CA to sign a new certificate for the name requested.

Subsequent runs will not require generating the CA, but will reuse the one it has already created.

$ devca new mydevwebsite.local
Created private key for "mydevwebsite.local": /home/grant/.local/share/devca/certs/mydevwebsite.local/key.pem
Created certificate for "mydevwebsite.local": /home/grant/.local/share/devca/certs/mydevwebsite.local/cert.pem

Requesting a cert for a name that already has a cert will require confirming your action, and then it will overwrite the existing cert with a new one.

$ devca new localhost
**** A certificate for "localhost" already exists. Would you like to overwrite it? y/N: y
Created private key for "localhost": /home/grant/.local/share/devca/certs/localhost/key.pem
Created certificate for "localhost": /home/grant/.local/share/devca/certs/localhost/cert.pem

ls command

devca ls lists all of your generated certs by name.

Usage

devca ls

Example

$ devca ls
localhost
mydevwebsite.local

path-to command

devca path-to outputs the directory of a particular certificate/key or the absolute path of the certificate/key itself.

Usage

devca path-to <name> [--cert|--key]

Examples

$ devca path-to localhost
/home/grant/.local/share/devca/certs/localhost

$ devca path-to localhost --cert
/home/grant/.local/share/devca/certs/localhost/cert.pem

$ devca path-to localhost --key
/home/grant/.local/share/devca/certs/localhost/key.pem

If the cert doesn't exist, nothing will be printed to stdout and devca will exit with a non-zero exit code.

You can use this instead of memorizing the location of the certs and keys themselves. For example, when using npx serve:

npx serve --ssl-cert $(devca path-to localhost --cert) --ssl-key $(devca path-to localhost --key) ./website

ca is a special value for this command and can be used to output location of the CA cert.

$ devca path-to ca --cert
/home/grant/.local/share/devca/ca/cert.pem

delete command

devca delete deletes a previously generated certificate/key pair.

Usage

devca delete <name>

Examples

This command is destructive, so it will present the directory it needs to delete and ask before completion. To cancel, type n and press Enter, or hit Ctrl-C.

$ devca delete localhost
**** This will delete all contents of /home/grant/.local/share/devca/certs/localhost
**** Would you like to proceed? Y/n:
Deleted "localhost": /home/grant/.local/share/devca/certs/localhost

$ devca delete localhost
**** This will delete all contents of /home/grant/.local/share/devca/certs/localhost
**** Would you like to proceed? Y/n: n
Aborting. Nothing was deleted.

regen command

devca regen regenerates your CA and all of your certificates/keys.

Usage

devca regen

Examples

This command is destructive, so it will confirm before continuing. To cancel, type n and press Enter, or hit Ctrl-C.

$ devca regen
**** This will regenerate the CA and all certificates.
**** Would you like to proceed? Y/n:
Created CA private key: /home/grant/.local/share/devca/ca/key.pem
Created CA certificate: /home/grant/.local/share/devca/ca/cert.pem
Created private key for "mydevwebsite.local": /home/grant/.local/share/devca/certs/mydevwebsite.local/key.pem
Created certificate for "mydevwebsite.local": /home/grant/.local/share/devca/certs/mydevwebsite.local/cert.pem
Created private key for "localhost": /home/grant/.local/share/devca/certs/localhost/key.pem
Created certificate for "localhost": /home/grant/.local/share/devca/certs/localhost/cert.pem

$ devca regen
**** This will regenerate the CA and all certificates.
**** Would you like to proceed? Y/n: n
Aborting. Nothing was deleted or created.

Prior Art

devca was inspired by minica

Licensing

DevCA is licensed under the MIT License.