certificate

Documentation

Overview

Package certificate provides functions for creating and storing TLS certificates.

Index

• func Create(options CreateOptions) (tls.Certificate, error)
• func Write(cert tls.Certificate, certPath, keyPath string) error
• type CreateOptions
• type Store
  • func (s *Store) Add(scope string, cert tls.Certificate) error
  • func (s *Store) Entries() map[string]tls.Certificate
  • func (s *Store) Get(hostname string) (*tls.Certificate, error)
  • func (s *Store) Load(path string) error
  • func (s *Store) Lookup(scope string) (tls.Certificate, bool)
  • func (s *Store) Register(scope string)
  • func (s *Store) SetPath(path string)

Functions

func Create

func Create(options CreateOptions) (tls.Certificate, error)

Create creates a new TLS certificate.

func Write

func Write(cert tls.Certificate, certPath, keyPath string) error

Write writes the provided certificate and its private key to certPath and keyPath respectively.

Types

type CreateOptions

type CreateOptions struct {
	// Subject Alternate Name values.
	// Should contain the DNS names that this certificate is valid for.
	// E.g. example.com, *.example.com
	DNSNames []string

	// Subject Alternate Name values.
	// Should contain the IP addresses that the certificate is valid for.
	IPAddresses []net.IP

	// Subject specifies the certificate Subject.
	//
	// Subject.CommonName can contain the DNS name that this certificate
	// is valid for. Server certificates should specify both a Subject
	// and a Subject Alternate Name.
	Subject pkix.Name

	// Duration specifies the amount of time that the certificate is valid for.
	Duration time.Duration

	// Ed25519 specifies whether to generate an Ed25519 key pair.
	// If false, an ECDSA key will be generated instead.
	// Ed25519 is not as widely supported as ECDSA.
	Ed25519 bool
}

CreateOptions configures the creation of a TLS certificate.

type Store

type Store struct {
	// CreateCertificate, if not nil, is called by Get to create a new
	// certificate to replace a missing or expired certificate.
	// The provided scope is suitable for use in a certificate's DNSNames.
	CreateCertificate func(scope string) (tls.Certificate, error)
	// contains filtered or unexported fields
}

A Store represents a TLS certificate store. The zero value for Store is an empty store ready to use.

Store can be used to store server certificates. Servers should provide a hostname or wildcard pattern as a certificate scope. Servers will most likely use the methods Register, Load and Get.

Store can also be used to store client certificates. Clients should provide a hostname as a certificate scope. Clients will most likely use the methods Add, Load, and Lookup.

Store is safe for concurrent use by multiple goroutines.

func (*Store) Add

func (s *Store) Add(scope string, cert tls.Certificate) error

Add registers the certificate for the given scope. If a certificate already exists for scope, Add will overwrite it.

func (*Store) Entries

func (s *Store) Entries() map[string]tls.Certificate

Entries returns a map of scopes to certificates.

func (*Store) Get

func (s *Store) Get(hostname string) (*tls.Certificate, error)

Get retrieves a certificate for the given hostname. If no matching scope has been registered, Get returns an error. Get generates new certificates as needed and rotates expired certificates. It calls CreateCertificate to create a new certificate if it is not nil, otherwise it creates certificates with a duration of 100 years.

Get is suitable for use in a gemini.Server's GetCertificate field.

func (*Store) Load

func (s *Store) Load(path string) error

Load loads certificates from the provided path. New certificates will be written to this path. The path should lead to a directory containing certificates and private keys named "scope.crt" and "scope.key" respectively, where "scope" is the scope of the certificate.

func (*Store) Lookup

func (s *Store) Lookup(scope string) (tls.Certificate, bool)

Lookup returns the certificate for the provided scope.

func (*Store) Register

func (s *Store) Register(scope string)

Register registers the provided scope with the certificate store. The scope can either be a hostname or a wildcard pattern (e.g. "*.example.com"). To accept all hostnames, use the special pattern "*".

Calls to Get will only succeed for registered scopes. Other methods are not affected.

func (*Store) SetPath

func (s *Store) SetPath(path string)

SetPath sets the path that new certificates will be written to.