cert

Documentation

Overview

Package cert provides helper functions for working with TLS certificates.

Index

• func LoadCertificate(filename string) (*tls.Certificate, error)
• type GetCertificateFunc
  • func GetCertificateAutomatically(hostnames []string) GetCertificateFunc
  • func GetCertificateDefaultServerName(defaultServerName string, getCertificate GetCertificateFunc) GetCertificateFunc
  • func GetCertificateFromDirectory(path string) GetCertificateFunc
  • func GetCertificateFromFile(path string) GetCertificateFunc

Functions

func LoadCertificate

func LoadCertificate(filename string) (*tls.Certificate, error)

Load a tls.Certificate from the given PEM-encoded file. The file must contain the following blocks:

• Exactly one PRIVATE KEY, containing the private key in PKCS#8 format.
• At least one CERTIFICATE, comprising the certificate chain, leaf certificate first and root certificate omitted.
• Up to one OCSP RESPONSE, containing a stapled OCSP response.
• Any number of SIGNED CERTIFICATE TIMESTAMP, containing stapled SCTs.

Types

type GetCertificateFunc

type GetCertificateFunc func(*tls.ClientHelloInfo) (*tls.Certificate, error)

A function that returns a tls.Certificate based on the given tls.ClientHelloInfo

func GetCertificateAutomatically

func GetCertificateAutomatically(hostnames []string) GetCertificateFunc

Returns a GetCertificateFunc that automatically obtains certificates using ACME for the given hostnames. Various environment variables can be used to customize the ACME client. See the go-listener README for details.

func GetCertificateDefaultServerName

func GetCertificateDefaultServerName(defaultServerName string, getCertificate GetCertificateFunc) GetCertificateFunc

Wraps a GetCertificateFunc with logic that sets tls.ClientHelloInfo.ServerName to defaultServerName if it is empty (e.g. because the client does not support SNI).

func GetCertificateFromDirectory

func GetCertificateFromDirectory(path string) GetCertificateFunc

Return a GetCertificateFunc that gets the certificate from a file in the given directory. The function searches for files in the following order:

1. SERVER_NAME.pem.ecdsa (only if client supports ECDSA certificates)
2. WILDCARD_NAME.pem.ecdsa (only if client supports ECDSA certificates)
3. SERVER_NAME.pem.rsa (only if client supports RSA certificates)
4. WILDCARD_NAME.pem.rsa (only if client supports RSA certificates)
5. SERVER_NAME.pem
6. WILDCARD_NAME.pem

SERVER_NAME is the SNI hostname provided by the client, and WILDCARD_NAME is the SNI hostname with the first label replaced with an underscore (e.g. the wildcard name for www.example.com is _.example.com)

Certificate files are cached in memory, and reloaded automatically when they change, allowing zero-downtime certificate rotation. See the documentation of LoadCertificate for the required format of the files.

If no certificate file is found, or if the client does not provide an SNI hostname, then the GetCertificateFunc returns an error, causing the TLS connection to be terminated. If you need to support clients that don't provide SNI, wrap the GetCertificateFunc with GetCertificateDefaultServerName to specify a default SNI hostname.

func GetCertificateFromFile

func GetCertificateFromFile(path string) GetCertificateFunc

Return a GetCertificateFunc that gets the certificate from the given file. The file is reloaded automatically when it changes, allowing zero-downtime certificate rotation. See the documentation of LoadCertificate for the required format of the file.