zcert

README

zcert is a library and commandline tool to manage development certificates.

It's a refactor from mkcert, with a slightly nicer CLI (IMHO anyway) and can be used as a Go library.

Install from source with go get zgo.at/zcert/cmd/zcert. The Go API is documented at https://godocs.io/zgo.at/zcert

Concepts

1. zcert creates a new root signing certificate; all certificates creates are signed with this certificate.

2. You can install the root certificate in your system's truststore (either manually or automatically), so browsers and tools recognize it.

CLI usage

The root cerificate can be managed with:

zcert root create          Create a new root certificate
zcert root install         Install it in the trust store.
zcert root uninstall       Remove it from the trust store.
zcert root remove          Remove the root certificate.
zcert root info            Show information about the root certificate.

Usually, just zcert root install is enough; this will create a root certificate if it exists and installs it to the truststores it can find.

Use zcert mame host to create new certificates for your application:

zcert make new.example.com

Can add multiple hostnames, wildcards, etc:

zcert make example.com '*.example.com'

See zcert for an overview of the help, and zcert help for more detailed help.

Library usage

zcert can function as a Go library; this is pretty useful to automatically generate development certificates with minimal user intervention. The main reason for this (and also the main reason I worked on this in the first place) is to always serve your local dev server over https without too much mucking about:

ca, _, err := zcert.New()
if err != nil {
    log.Fatal(err)
}

serve := http.Server{Addr: listen, TLSconfig: ca.TLSConfig()}
serve.ListenAndServeTLS("", "")

See cmd/serve for an example of this.

The truststore subpackage can be used to install your own keys in the trust store, if you want.

Documentation

Index

• type CARoot
  • func New() (ca CARoot, created bool, err error)
  • func (ca CARoot) Certificate() *x509.Certificate
  • func (ca *CARoot) Create() error
  • func (ca CARoot) Delete() error
  • func (ca CARoot) Exists() bool
  • func (ca CARoot) Install() error
  • func (ca *CARoot) Load() error
  • func (ca CARoot) MakeCert(out io.Writer, clientCert bool, hosts ...string) error
  • func (ca CARoot) MakeTLSCert(clientCert bool, hosts ...string) (*tls.Certificate, error)
  • func (CARoot) StorePath() (string, string)
  • func (ca CARoot) TLSConfig() *tls.Config
  • func (ca CARoot) Uninstall() error
• type Group
  • func NewGroup(maxSize int) *Group
  • func (g *Group) Append(err error) bool
  • func (g Group) Error() string
  • func (g *Group) ErrorOrNil() error
  • func (g Group) Len() int

Types

type CARoot

type CARoot struct {
	Verbose bool // Print verbose output to stderr.
	// contains filtered or unexported fields
}

CARoot is a root certificate that's used to sign certificates with.

func New

func New() (ca CARoot, created bool, err error)

New creates a new instance of CARoot. It will load an existing root certificate if it exists, or creates a new one if it doesn't.

func (CARoot) Certificate

func (ca CARoot) Certificate() *x509.Certificate

Certificate gets the loaded root certificate; may return nil if Load() isn't called yet.

func (*CARoot) Create

func (ca *CARoot) Create() error

Create a new root certificate; this will return an error if a root CA already exist.

func (CARoot) Delete

func (ca CARoot) Delete() error

Delete the root certificate.

func (CARoot) Exists

func (ca CARoot) Exists() bool

Exists reports if the root certificate exits.

func (CARoot) Install

func (ca CARoot) Install() error

Install the root certificate to all truststores we can find.

func (*CARoot) Load

func (ca *CARoot) Load() error

Load the root certificate from disk.

func (CARoot) MakeCert

func (ca CARoot) MakeCert(out io.Writer, clientCert bool, hosts ...string) error

MakeCert creates a new certificate signed with the root certificate and writes the PEM-encoded data to out.

func (CARoot) MakeTLSCert

func (ca CARoot) MakeTLSCert(clientCert bool, hosts ...string) (*tls.Certificate, error)

MakeTLS creates a new TLS certificate signed with the root certificate.

func (CARoot) StorePath

func (CARoot) StorePath() (string, string)

StorePaths gets the full path name to the root certificate. Returns certificate and key.

func (CARoot) TLSConfig

func (ca CARoot) TLSConfig() *tls.Config

TLSConfig returns a new tls.Config which creates certificates for any hostname.

func (CARoot) Uninstall

func (ca CARoot) Uninstall() error

Uninstall the root certificate from all truststores we can find.

type Group

type Group struct {
	// Maximum number of errors; calls to Append() won't do anything if the number of errors is larger than this.
	MaxSize int
	// contains filtered or unexported fields
}

Group multiple errors.

func NewGroup

func NewGroup(maxSize int) *Group

NewGroup create a new Group instance. It will record a maximum of maxSize errors. Set to 0 for no limit.

func (*Group) Append

func (g *Group) Append(err error) bool

Append a new error to the list; this is thread-safe.

It won't do anything if the error is nil, in which case it will return false. This makes appending errors in a loop slightly nicer:

for {
    err := do()
    if errors.Append(err) {
        continue
    }
}

func (Group) Error

func (g Group) Error() string

func (*Group) ErrorOrNil

func (g *Group) ErrorOrNil() error

ErrorOrNil returns itself if there are errors, or nil otherwise.

It avoids an if-check at the end:

return errs.ErrorOrNil()

func (Group) Len

func (g Group) Len() int

Len returns the number of errors.