localcert: SSL Certificate Generation and Trust

Generates and trusts self-signed SSL certificates for local development. Based off the popular mkcert library for GoLang.

Requirements

In order to install certificates in NSS browsers such as Firefox, the Mozilla certutil is required. You can install it with the following:

Mac

brew install certutil

Linux

sudo apt install libnss3-tools
    -or-
sudo yum install nss-tools
    -or-
sudo pacman -S nss
    -or-
sudo zypper install mozilla-nss-tools

Windows

Installation to Firefox is not yet supported on Windows. Localcert will only install the certificate to the system store.

Usage

Import and instantiate the the localcert module:

var localcert = require('localcert')

var certgen = new localcert()

Generate the certificate:

certgen.generate(['test.local'], 'US', 'FL', 'Sarasota', 'Acme Inc', '')

const certPaths = await certgen.saveCertificate();

Note, you can pass a "certPath" to the saveCertificate method. Without it, localcert will save certificates to ~/.localcert

You can also load an existing certificate with the following:

const certPaths = certgen.loadCertificate(certPath,privateKeyPath);

Next, trust the certificate either in the system store, NSS browsers such as Firefox and Chrome, or both:

certgen.trustCertificatePlatform();
certgen.trustCertificateNSS();

To remove the certificate trusts, locate the certificate to remove and run the following:

certgen.removeCertificateTrustPlatform();
certgen.removeCertificateTrustNSS();

For the following functions, you can pass a second, optional, parameter of execute (bool) which defaults to true. If false, the command called will simply return the command parameters and not execute. Hopefully this will be handy in applications that may have wrapped sudo and/or other system calls.

Some utility functions

Determine if the user has certutil installed:

certgen.hasCertUtil();

Determine if the user has any NSS browsers that need to be trusted:

certgen.hasNSS();

Verify if the current certificate has been trusted in the system store

await verifyPlatformTrust();

Changelog

1.4.3

• Added serialNumber prop to certificate object upon verification
• Updated trust verification on windows to use serialNumber and commonName
• Removed meaningless verification check

1.4.2

• Resolved missing 'certutil' command in windows truststore

1.4.0

• Update sha1 to sha256
• Have self-signed certs also be Certificate Authorities

1.3.0

• Fix issue with duplicate DNS names

1.2.8

• Fix inconsistencies with package-lock

1.2.7

• Move to getflywheel organization

1.2.6

• Remove dependencies on native node modules

1.2.5

• Ensure we're properly verifying the certificate to build NSS commands

1.2.4

• Fix default certPath when removing NSS trusts

1.2.3

• Improve readme documentation
• Fix bug where commands weren't returned from nss de-trust
• Make certPath optional on most functions

1.2.2

• Setup testing
• Use npm instead of yarn

1.2.1

• Fix filename when generating new key

1.2.0

• Minor refactor

1.1.6

• Savecertificate method is now properly async.

1.1.5

• Use which package to avoid errors.

1.1.4

• Add ability to verify system store on host machine has been trusted.

1.1.3

• We need to escape paths for the child_process.exec execution

1.1.2

• Send the correct database string to the NSS insert method.

1.1.1

• export NSS command paths without normalized paths

1.1.0

• Add helper function to retrieve NSS operations
• Add ability to not execute NSS trust commands

1.0.7

• Generated cert should not be listed as a CA.

1.0.6

• Properly escape spaces in all paths for NSS browser trust

1.0.5

• Don't escape Mac and Linux paths unless we have to

1.0.4

• Add ability to avoid direct execution of sudo commands with optional "execute" parameter.

1.0.3

• Ensure spaces are accounted for in Linux and Mac paths

1.0.2

• Ensure certutil path is populated in Linux
• Cleanout some unused variables after the port from mkcert

1.0.1

• Add ability to load an existing certificate for trusting

1.0.0

• Initial release