tlscert

tlscert

This is a simple tool to generate self-signed certificates for testing purposes.

Motivation

This package is intended to be used in tests that require a self-signed certificate. It is not intended to be used in production code.

I many times found myself needing to generate a self-signed certificate for testing purposes, and I always had to look up how to do it. This package is an attempt to make this process easier, providing a simple API to generate self-signed certificates and save them to disk, if needed.

Features

The package exposes two functions and two types: SelfSigned and SelfSignedFromRequest, and Request and Certificate.

• The Request type is used to specify the parameters for the certificate generation.
• The Certificate type is used to store the generated certificate and key, including the paths to the files on disk.
• The SelfSigned function generates a self-signed certificate and returns it as a Certificate value. This function only receives the host name for the certificate.
• The SelfSignedFromRequest function generates a self-signed certificate based on the parameters in a Request value.

Therefore, it's possible to issue a self-signed certificate with a custom host name, and save it to disk, if needed, or to issue a certificate based on a parent certificate, which is useful for generating client certificates.

The Request struct also provides a ParentDir option that can be used to save the generated certificate to disk as a PEM file.

The Certificate struct provides a Transport method, which returns a pointer to a http.Transport that can be used to perform HTTP requests using the generated certificate; and a TLSConfig method, which returns a pointer to a tls.Config. The Transport method internally uses the TLSConfig method.

Example

You can find a simple example in the example_test.go file:

package tlscert_test

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"

	"github.com/mdelapenya/tlscert"
)

func ExampleSelfSigned() {
	tmp := os.TempDir()
	certsDir := tmp + "/certs"
	defer os.RemoveAll(certsDir)

	if err := os.MkdirAll(certsDir, 0o755); err != nil {
		log.Fatal(err) // nolint: gocritic
	}

	// Generate a certificate for localhost and save it to disk.
	caCert := tlscert.SelfSignedFromRequest(tlscert.Request{
		Host:      "localhost",
		Name:      "ca-cert",
		ParentDir: certsDir,
	})
	if caCert == nil {
		log.Fatal("Failed to generate CA certificate")
	}

	cert := tlscert.SelfSignedFromRequest(tlscert.Request{
		Host:      "localhost",
		Name:      "client-cert",
		Parent:    caCert,
		ParentDir: certsDir,
	})
	if cert == nil {
		log.Fatal("Failed to generate certificate")
	}

	// create an http server that uses the generated certificate
	// and private key to serve requests over HTTPS

	server := &http.Server{
		Addr: ":8443",
	}

	server.Handler = http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
		w.Header().Set("Content-Type", "text/plain")
		_, err := w.Write([]byte("TLS works!\n"))
		if err != nil {
			log.Printf("Failed to write response: %v", err)
		}
	})

	go func() {
		_ = server.ListenAndServeTLS(cert.CertPath, cert.KeyPath)
	}()
	defer server.Close()

	// perform an HTTP request to the server, using the generated certificate

	const url = "https://localhost:8443/hello"

	client := &http.Client{Transport: cert.Transport()}
	resp, err := client.Get(url)
	if err != nil {
		log.Fatalf("Failed to get response: %v", err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatalf("Failed to read response body: %v", err)
	}

	fmt.Println(string(body))

	// Output:
	// TLS works!
}