certinel

package module
v1.2.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 30, 2022 License: BSD-3-Clause Imports: 2 Imported by: 1

README

certinel GoDoc

Unsupported

NOTE: This is Pantheon's fork of https://github.com/cloudflare/certinel. It adds additional functionality and Pantheon-specific opinions.

Certinel is a Go library that makes it even easier to implement zero-hit TLS certificate changes by watching for certificate changes for you. The methods required by tls.Config are already implemented for you.

There are two watcher implementations available:

  • pollwatcher: Uses the stat() systemcall to check for an updated certificate on a configurable intervable. Common intervals are 1-5 minutes.
  • fswatcher: Uses the fsnotify library for immediate change detection.

There are a number of edge cases with fsnotify based fswatcher and it is generally recommended to use the stat()-based pollwatcher instead. Some issues to watch out for with the fswatcher:

  1. Ordering of writes matters. Ensure that the external app that is writing the certificates writes the files in this order: .key first, .crt next.
  2. If mv or cp is used to put new certificate/key files in place the updates will be missed.
  3. If you pass a combined key and cert file to fwatcher, ensure the external app writes the new file in a single write(), otherwise the watcher will trigger a read of a partial cert.

Usage

Create a watcher instance to watch for changes to your certificate files, then create the certinel instance, pass your watcher instance, then start it with Watch. Finally, pass the GetCertificate or GetClientCertificate method to your tls.Config instance.

Runnable examples are available in the ./examples directory.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Certinel

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

Certinel is a container for zero-hit tls.Certificate changes, by receiving new certificates from sentries and presenting the functions expected by Go's tls.Config{}. Reading certificates from a Certinel instance is safe across multiple goroutines.

func New

func New(w Watcher, log logger, errBack func(error)) *Certinel

New creates a Certinel that watches for changes with the provided Watcher. Takes an optional logger and errBack func. Both can be nil if you don't want to log or handle errors.

func (*Certinel) Close

func (c *Certinel) Close() error

Close calls Close on the held Watcher instance. After closing it is no longer safe to use this Certinel instance.

func (*Certinel) GetCertificate

func (c *Certinel) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate returns the current tls.Certificate instance. The function can be passed as the GetCertificate member in a tls.Config object. It is safe to call across multiple goroutines.

func (*Certinel) GetClientCertificate

func (c *Certinel) GetClientCertificate(certificateRequest *tls.CertificateRequestInfo) (*tls.Certificate, error)

GetClientCertificate returns the current tls.Certificate instance. The function can be passed as the GetClientCertificate member in a tls.Config object. (Introduced in go-1.8) It is safe to call across multiple goroutines.

func (*Certinel) Watch

func (c *Certinel) Watch()

Watch setups the Certinel's channel handles and calls Watch on the held Watcher instance.

type Watcher

type Watcher interface {
	Watch() (<-chan tls.Certificate, <-chan error)
	Close() error
}

Watchers provide a way to construct (and close!) channels that bind a Certinel to a changing certificate.

Directories

Path Synopsis
examples
fswatcher command
pollwatcher command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL