Skip to content

Getting started

This walks you from nothing to a Go server answering trusted HTTPS on https://localhost:8443 — no browser warning, no manual mkcert -install.

Install

go get gitlab.com/phpboyscout/go/localca

Serve trusted HTTPS

package main

import (
    "context"
    "net/http"

    "gitlab.com/phpboyscout/go/localca"
)

func main() {
    cfg := localca.Config{
        DataDir: "/home/me/.myapp", // where the root + leaf live (key files 0600)
        AppName: "myapp",           // seeds the root name: "myapp local CA (me@host)"
    }

    // First run: mint a per-machine root, install it into your trust stores (one OS
    // elevation prompt), and return a servable pair. Later runs are silent no-ops.
    pair, err := localca.EnsureServed(context.Background(), cfg, []string{"localhost", "127.0.0.1"})
    if err != nil {
        panic(err)
    }

    tlsCfg, err := pair.ServerConfig() // go/tls hardened config, leaf loaded
    if err != nil {
        panic(err)
    }

    http.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) {
        _, _ = w.Write([]byte("trusted HTTPS, no warning"))
    })

    srv := &http.Server{Addr: ":8443", TLSConfig: tlsCfg}
    _ = srv.ListenAndServeTLS("", "") // certs already in TLSConfig
}

Run it once. macOS/Windows will prompt for elevation (Keychain / UAC); Linux uses sudo for the system store. That prompt is the consent gate — after it, every browser on the machine trusts your local cert.

What just happened

  1. A per-machine ECDSA-P256 root CA (~10-year validity) was minted and stored under DataDir (rootCA.pem + rootCA-key.pem, key 0600).
  2. It was installed into your system trust store and, when certutil is present, the NSS database (Firefox/Chromium).
  3. A short-lived (90-day) leaf for localhost + 127.0.0.1 was signed by the root, written under DataDir, and returned as a go/tls.Pair.

The second run reuses all of it: an already-trusted root prompts nothing, and the cached leaf is served until it nears expiry or your host list changes.

Removing it

a, _ := localca.New(cfg)
_ = a.Uninstall(context.Background(), localca.Purge()) // remove from trust stores + delete the key

Next