gtestcert

gtestcert is a simple tool based on mkcert for making development certificates trusted by GTestCA. It requires no configuration.

GTestCA stands for Government Test CA (政府測試憑證管理中心), a Certificate Authority for test, development purposes, operated by National Development Council (國家發展委員會) (Taiwan). You can submit a CSR from their website https://gtestca.nat.gov.tw/ and get a signed certificate immediately free of charge.

By trusting such a CA operated by the government reduces the operational burden for developers. And gtestcert make the certificate signing process as easy as mkcert.

You can see the full EULA about GTestCA here: https://gtestca.nat.gov.tw/download/GTESTCA_EULA.pdf

$ gtestcert -install
Installed the GTestRCA 💥
The GTestRCA is now installed in the system trust store! ⚡️
The GTestRCA is now installed in the Firefox trust store (requires browser restart)! 🦊

$ gtestcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1

Created a new certificate valid for the following names 📜
 - "example.com"
 - "*.example.com"
 - "example.test"
 - "localhost"
 - "127.0.0.1"
 - "::1"

The certificate is at "./example.com+5.pem" and the key at "./example.com+5-key.pem" ✅

Using certificates from real certificate authorities (CAs) for development can be dangerous or impossible (for hosts like example.test, localhost or 127.0.0.1), but self-signed certificates cause trust errors. Managing your own CA is the best solution, but usually involves arcane commands, specialized knowledge and manual steps.

gtestcert automatically installs the GTestRCA in the system root store, and generates GTestCA trusted certificates. gtestcert does not automatically configure servers to use the certificates, though, that's up to you.

Installation

Follow the installation instruction from mkcert to install prerequisites for your operating system.

Use the pre-built binaries.

If you're running into permission problems try running gtestcert as an Administrator.

Supported root stores

gtestcert supports the following root stores:

macOS system store
Windows system store
Linux variants that provide either
- update-ca-trust (Fedora, RHEL, CentOS) or
- update-ca-certificates (Ubuntu, Debian, OpenSUSE, SLES) or
- trust (Arch)
Firefox (macOS and Linux only)
Chrome and Chromium
Java (when JAVA_HOME is set)

To only install the local root CA into a subset of them, you can set the TRUST_STORES environment variable to a comma-separated list. Options are: "system", "java" and "nss" (includes Firefox).

Advanced topics

Advanced options

	-cert-file FILE, -key-file FILE, -p12-file FILE
	    Customize the output paths.

	-client
	    Generate a certificate for client authentication.

	-ecdsa
	    Generate a certificate with an ECDSA key.

	-pkcs12
	    Generate a ".p12" PKCS #12 file, also know as a ".pfx" file,
	    containing certificate and key for legacy applications.

	-csr CSR
	    Generate a certificate based on the supplied CSR. Conflicts with
	    all other flags and arguments except -install and -cert-file.

Note: You must place these options before the domain names list.

Example

gtestcert -key-file key.pem -cert-file cert.pem example.com *.example.com

Mobile devices

For the certificates to be trusted on mobile devices, you will have to install the root CA. It's the rootCA.pem file in the folder printed by gtestcert -CAROOT.

On iOS, you can either use AirDrop, email the CA to yourself, or serve it from an HTTP server. After opening it, you need to install the profile in Settings > Profile Downloaded and then enable full trust in it.

For Android, you will have to install the CA and then enable user roots in the development build of your app. See this StackOverflow answer.

Using the root with Node.js

Node does not use the system root store, so it won't accept gtestcert certificates automatically. Instead, you will have to set the NODE_EXTRA_CA_CERTS environment variable.

export NODE_EXTRA_CA_CERTS="$(gtestcert -CAROOT)/rootCA.pem"

tan9 / gtestcert