ocspd

README

GOAL

First goal is to play well with HAProxy, without being specific to it:

• take "bundle" PEMs as input containing the certificate chain, falling back to a .issuer-suffixed file
• output OCSP response in a .ocsp-suffixed file

All other usages can come later, as options if needed.

REQUIREMENTS

https://gist.github.com/sleevi/5efe9ef98961ecfb4da8

SPECIFICATIONS

• https://tools.ietf.org/html/rfc6960
• https://tools.ietf.org/html/rfc5019

FEATURES

1. update-ocsp: command-line tool updating OCSP responses for a set of certificates, replacing openssl ocsp or the more complete hapos-upd script (but without the part that's specific to HAProxy)
2. ocspd: long-lived program deciding when OCSP responses need to be refreshed, eliminating the need for a Cron job
3. both provide a hook mechanism to notify applications through external programs (e.g. update HAProxy through the set ssl ocsp-response Unix Socket command); an update-haproxy.sh script is provided for HAProxy.

ROADMAP

1. cleanup and iron out the library API
2. easy integration with "crypto/tls".Config.GetCertificate and golang.org/x/crypto/acme/autocert

Documentation

Index

• Constants
• Variables
• func NeedsRefresh(resp *ocsp.Response, mtime time.Time, period time.Duration) bool
• func ResponderURL(cert *x509.Certificate) (string, error)
• func Update(cert, issuer *x509.Certificate, responderURL string) ([]byte, error)
• type Event
• type Fetcher
  • func NewFetcher(client *http.Client) *Fetcher
  • func (f *Fetcher) Fetch(req *Request, etag string, lastModified, nextUpdate time.Time) (*Response, error)
  • func (f *Fetcher) FetchR(req *Request, prev *Response) (*Response, error)
• type Request
  • func CreateRequest(cert, issuer *x509.Certificate, responderURL string) (req *Request, err error)
• type Response
  • func Fetch(req *Request, etag string, lastModified, nextUpdate time.Time) (*Response, error)
  • func FetchForCert(cert, issuer *x509.Certificate, responderURL, etag string, ...) (*Response, error)
  • func FetchR(req *Request, prev *Response) (*Response, error)
  • func NeedsRefreshFile(filename string, issuer *x509.Certificate, period time.Duration) (bool, *Response, error)
• type Updater
  • func (u *Updater) AddOrUpdate(tag string, req *Request, resp *Response) error
  • func (u *Updater) Remove(tag string)
  • func (u *Updater) Start()
  • func (u *Updater) Stop()
  • func (u *Updater) UpdateNow()

Constants

const DefaultTickRound = 5 * time.Minute

Variables

var ErrDuplicateTag = errors.New("ocspd: duplicate tag")

Functions

func NeedsRefresh

func NeedsRefresh(resp *ocsp.Response, mtime time.Time, period time.Duration) bool

NeedsRefresh determines whether the given OCSP response needs to be refreshed.

If the response has no NextUpdate information, it needs to be refreshed. Otherwise, it'll need to be refreshed halfway through its validity period, and to avoid refreshing too many times during that interval the last refresh time and the checks period are used as guidance.

func ResponderURL

func ResponderURL(cert *x509.Certificate) (string, error)

ResponderURL extracts the OCSP responder URL from the given certificate.

func Update

func Update(cert, issuer *x509.Certificate, responderURL string) ([]byte, error)

Update queries the OCSP responder and returns an OCSP response.

If responderURL is empty then the OCSP responder URL is extracted from the passed in certificates.

Types

type Event

type Event struct {
	Response    *ocsp.Response
	RawResponse []byte
	Tags        []string
}

type Fetcher

type Fetcher struct {
	Client *http.Client
	// contains filtered or unexported fields
}

func NewFetcher

func NewFetcher(client *http.Client) *Fetcher

func (*Fetcher) Fetch

func (f *Fetcher) Fetch(req *Request, etag string, lastModified, nextUpdate time.Time) (*Response, error)

func (*Fetcher) FetchR

func (f *Fetcher) FetchR(req *Request, prev *Response) (*Response, error)

type Request

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

func CreateRequest

func CreateRequest(cert, issuer *x509.Certificate, responderURL string) (req *Request, err error)

type Response

type Response struct {
	OCSPResponse    *ocsp.Response
	RawOCSPResponse []byte
	MaxAge          time.Time
	Etag            string
	LastModified    time.Time
}

func Fetch

func Fetch(req *Request, etag string, lastModified, nextUpdate time.Time) (*Response, error)

func FetchForCert

func FetchForCert(cert, issuer *x509.Certificate, responderURL, etag string, lastModified, nextUpdate time.Time) (*Response, error)

func FetchR

func FetchR(req *Request, prev *Response) (*Response, error)

func NeedsRefreshFile

func NeedsRefreshFile(filename string, issuer *x509.Certificate, period time.Duration) (bool, *Response, error)

NeedsRefreshFile applies NeedsRefresh heuristics to an OCSP response stored in a file: it will check if the file exists, parse it, then call NeedsRefresh with parsed OCSP response, the file's last modification time and the given period.

type Updater

type Updater struct {
	OnUpdate  func(Event)
	TickRound time.Duration
	Log       func(format string, v ...interface{})
	Fetcher   *Fetcher
	// contains filtered or unexported fields
}

Updater schedules queries to OCSP responders at appropriate times in order to maintain fresh OCSP responses for a set of certificates.

Queries are scheduled such that the OCSP responses are always fresh but but without hammering the OCSP responders, hopefully making a single query at the appropriate time to get a fresh response (rather than the same that's already cached).

Internally, Updater organizes certificates in such a way that if a certificate is added twice it won't cause more work to be done; a certificate can thus be associated to several "tags".

Whenever the OCSP response for a certificate is refreshed, the OnUpdate function is called.

func (*Updater) AddOrUpdate

func (u *Updater) AddOrUpdate(tag string, req *Request, resp *Response) error

AddOrUpdate adds a certificate to be monitored, with an optional response (generally coming from a cache).

The OCSPResponse and MaxAge in resp will be used to schedule the next update, the ETag and LastModified will be used for the next update if provided; RawOCSPResponse is never used.

If the certificate is already monitored, its next update will be rescheduled.

func (*Updater) Remove

func (u *Updater) Remove(tag string)

func (*Updater) Start

func (u *Updater) Start()

Start begins scheduling OCSP fetches for the monitored certificates.

It schedules calls to UpdateNow at specific times to always maintain monitored certificates' OCSP responses up to date.

It's a no-op if the Updater is already started, and blocks otherwise.

func (*Updater) Stop

func (u *Updater) Stop()

Stop terminates the scheduled monitoring.

It waits for ongoing fetches and only prevents future fetches from being scheduled.

func (*Updater) UpdateNow

func (u *Updater) UpdateNow()

UpdateNow fetches OCSP responses that needs to be refreshed.