tls_certificate_loader

README

Utility library to load TLS certificate and key (Go)

This is an utility library to load TLS certificate chain and private key from files. It will check for changes in the files periodically and update them, allowing you to set up an auto-renewal process without worrying about restarting the server process.

Documentation

Installation

To install the library in your project, run:

go get github.com/AgustinSRG/go-tls-certificate-loader

Usage

To use the library, create a loader calling NewTlsCertificateLoader. Then, use its GetCertificate function in the TLS configuration of your server.

Here is en example usage

package main

import (
    "fmt"
    "crypto/tls"
    "net/http"
    "time"
    // Import the module
    tls_certificate_loader "github.com/AgustinSRG/go-tls-certificate-loader"
)

func main() {
	// Create the loader
	loader, err := NewTlsCertificateLoader(TlsCertificateLoaderConfig{
		// Path to the certificate and the key
		CertificatePath: "/path/to/certificate.pem",
		KeyPath:         "/path/to/key.pem",

		// Interval to check for changes
		CheckReloadPeriod: 5 * time.Minute,

		// Event functions
		OnReload: func() {
			fmt.Println("Certificate was reloaded!")
		},
		OnError: func(err error) {
			fmt.Printf("Error loading certificate: %v \n", err)
		},
	})

	if err != nil {
		fmt.Printf("Error loading certificate: %v \n", err)
		return
	}

	defer loader.Close() // Stop the loader after the main process is finished

	// Create TLS server

	tlsServer := http.Server{
		Addr: ":443",
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			w.WriteHeader(200)
			fmt.Fprint(w, "Hello world!")
		}),
		TLSConfig: &tls.Config{
			// Provide the GetCertificate function of the loader
			GetCertificate: loader.GetCertificate,
		},
	}

	fmt.Println("Server listening on port 443!")

	// Listen and serve requests

	err = tlsServer.ListenAndServeTLS("", "")

	if err != nil {
		fmt.Printf("Server error: %v \n", err)
	}
}

Build the library

To install dependencies, run:

go get .

To build the code, run:

go build .

Run linter

To run the code linter, run:

golangci-lint run

Run tests

In order to run the tests for this library, run:

go test -v

Documentation

Index

• type TlsCertificateLoader
  • func NewTlsCertificateLoader(config TlsCertificateLoaderConfig) (*TlsCertificateLoader, error)
  • func (loader *TlsCertificateLoader) Close()
  • func (loader *TlsCertificateLoader) GetCertificate(_ *tls.ClientHelloInfo) (*tls.Certificate, error)
  • func (loader *TlsCertificateLoader) IsClosed() bool
• type TlsCertificateLoaderConfig

Types

type TlsCertificateLoader

type TlsCertificateLoader struct {
	// contains filtered or unexported fields
}

TLS certificate loader

func NewTlsCertificateLoader

func NewTlsCertificateLoader(config TlsCertificateLoaderConfig) (*TlsCertificateLoader, error)

Creates a new instance of TlsCertificateLoader Also loads the key pair for the first time

Takes the configuration as the only parameter

Returns an error as the seconds return value if an error occurs loading the key pair for the first time In this case, no instance is created, and nil is returned instead as the first return value.

Important: If succeeded, this function starts a new co-routine to periodically reload the key pair. If you stop that co-routine, call the Close() function

func (*TlsCertificateLoader) Close

func (loader *TlsCertificateLoader) Close()

Closes the loader, stopping its co-routine

func (*TlsCertificateLoader) GetCertificate

func (loader *TlsCertificateLoader) GetCertificate(_ *tls.ClientHelloInfo) (*tls.Certificate, error)

Obtains the current loaded TLS key pair The client info parameter is ignored This function will never return an error

func (*TlsCertificateLoader) IsClosed

func (loader *TlsCertificateLoader) IsClosed() bool

Checks if the loader is closed A closed loader is not checking for changes anymore

type TlsCertificateLoaderConfig

type TlsCertificateLoaderConfig struct {
	// Path to the X.509 certificate chain file
	CertificatePath string

	// Path to the private key file
	KeyPath string

	// Period to check to reload the certificate and key
	CheckReloadPeriod time.Duration

	// Function to call when key pair is reloaded
	OnReload func()

	// Function to call when an error happens reloading the key pair
	OnError func(err error)
}

Configuration for TLS certificate loader