dyocsp

README

DyOCSP - Flexible DB OCSP Responder

Introduction

DyOCSP is an OCSP responder for private CA, and implementation of RFC 6960 and RFC 5019. The objective is to have a responder with flexible database backend choices.

Download

• Get the latest binary from releases.
• Or pull docker image:

docker pull yuxki/dyocsp:v0.1.0

• Or get the sources:

git clone https://github.com/yuxki/dyocsp

Please try Demo after download.

Supported Environments

Database

• File
• DynamoDB

Protocol

• HTTP (POST Method Only)

Signing Key Format

• PKCS# 8

Full Documentation

Documentation is available here: manual

Demo

Start OCSP Responder Server

Build and run dyocsp with a demo configuration file, certificate, and key.

• Binary

$ cd ./demo
$ go build ../cmd/dyocsp
$ ./dyocsp -c delegate-dyocsp.yml

• Docker Image

$ cd ./demo
$ docker pull yuxki/dyocsp:v0.1.0
$ docker run --rm -v $(pwd):/work --workdir=/work yuxki/dyocsp:v0.1.0 -c delegate-dyocsp.yml

Test OCSP Request

Open another terminal.

# Request "successful good" certificate
$ cd demo
$ openssl ocsp \
    -CAfile ca/root-ca.crt \
    -issuer ca/sub-ca.crt \
    -cert ca/good.crt \
    -no_nonce \
    -url http://localhost:9080

# Request "successful revoked" certificate
$ cd ./demo
$ openssl ocsp \
    -CAfile ca/root-ca.crt \
    -issuer ca/sub-ca.crt \
    -cert ca/revoked.crt \
    -no_nonce \
    -url http://localhost:9080

Documentation

Index

• Constants
• Variables
• func CreateHTTPServer(host string, cfg config.DyOCSPConfig, handler http.Handler) *http.Server
• func NewCacheHandler(cacheStore *cache.ResponseCacheStoreRO, responder *Responder, ...) http.Handler
• func WithDelay(delay time.Duration) func(*CacheBatch)
• func WithExpiration(exp expBehavior) func(*CacheBatch)
• func WithHandlerLogger(logger *zerolog.Logger) func(*CacheHandler)
• func WithIntervalSec(sec int) func(*CacheBatch)
• func WithLogger(logger *zerolog.Logger) func(*CacheBatch)
• func WithMaxAge(max int) func(*CacheHandler)
• func WithMaxRequestBytes(max int) func(*CacheHandler)
• func WithQuiteChan(quite chan string) func(*CacheBatch)
• func WithStrict(strict bool) func(*CacheBatch)
• type AuthorizedType
• type CADBClient
• type CacheBatch
  • func NewCacheBatch(ca string, cacheStore *cache.ResponseCacheStore, caDBClient CADBClient, ...) (*CacheBatch, error)
  • func (c *CacheBatch) Run(ctx context.Context)
  • func (c *CacheBatch) RunOnce(ctx context.Context) []cache.ResponseCache
• type CacheBatchOption
• type CacheHandler
  • func (c CacheHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type CacheHandlerOption
• type IssuerHash
• type KeyAlg
• type KeyFormat
• type Responder
  • func BuildResponder(rCertPem, rPrivKeyPem, issuerCertPem []byte, nowT time.Time) (*Responder, error)
  • func (r *Responder) SignCacheResponse(cache cache.ResponseCache) (cache.ResponseCache, error)
  • func (r *Responder) Verify(nowT time.Time) error

Constants

const (
	Ignore expBehavior = iota
	Warn
	Invalid
)

const (
	DefaultInterval = 60
)

Default values.

Variables

var ErrDelayExceedsInterval = errors.New("delay must be less than interval or equal")

Functions

func CreateHTTPServer

func CreateHTTPServer(
	host string,
	cfg config.DyOCSPConfig,
	handler http.Handler,
) *http.Server

func NewCacheHandler

func NewCacheHandler(
	cacheStore *cache.ResponseCacheStoreRO,
	responder *Responder,
	chain alice.Chain,
	opts ...CacheHandlerOption,
) http.Handler

NewCacheHandler creates a new instance of dyocsp.CacheHandler. It chains the following handlers before the handler that sends the OCSP response. (It uses 'https://github.com/justinas/alice' to chain the handlers.)

• Send http.StatusMethodNotAllowed unless the request method is POST.
• Send http.StatusRequestEntityTooLarge if the size of the request exceeds the value of the variable spec.MaxRequestBytes..

func WithDelay

func WithDelay(delay time.Duration) func(*CacheBatch)

WithDelay sets delay option. Delay is a duration specification that pauses the execution of the program for a specified CacheBatchSpec.Interval before continuing to process further. Default value is 0 duraiton.

func WithExpiration

func WithExpiration(exp expBehavior) func(*CacheBatch)

WithExpiration sets expiration. This expiration determines the behavior when the Expiration Date is exceeded. Default value is Ignore.

func WithHandlerLogger

func WithHandlerLogger(logger *zerolog.Logger) func(*CacheHandler)

WithHandlerLogger sets logger. If not set, global logger is used.

func WithIntervalSec

func WithIntervalSec(sec int) func(*CacheBatch)

WithIntervalSec sets interval seconds option. Interval is the duration specification between the Next Update and the Next Update. If zero is set, DefaultInterval is used.

func WithLogger

func WithLogger(logger *zerolog.Logger) func(*CacheBatch)

WithLogger sets logger. If not set, global logger is used.

func WithMaxAge

func WithMaxAge(max int) func(*CacheHandler)

MaxAge defines the maximum age, in seconds, for a cached response as specified in the Cache-Control max-age directive. If the duration until the nextUpdate of a cached response exceeds MaxAge, the handler sets the response's Cache-Control max-age directive to that duration. Default value is 0.

func WithMaxRequestBytes

func WithMaxRequestBytes(max int) func(*CacheHandler)

MaxRequestBytes defines the maximum size of a request in bytes. If the content of a request exceeds this parameter, the handler will respond with http.StatusRequestEntityTooLarge. Default value is 0, and if 0 is set, this option is ignored.

func WithQuiteChan

func WithQuiteChan(quite chan string) func(*CacheBatch)

WithQuietChan sets a quiet message channel, which stops the loop of dyocsp.CacheBatch.Run(). It also sends a message immediately before quieting the loop.

func WithStrict

func WithStrict(strict bool) func(*CacheBatch)

WithDelay sets strict option.// The strict specification of dyocsp.CacheBatch means that it is in 'strict mode',which calls panic() when a CADBClient error occurs during the scanning of the database. Default value is false.

Types

type AuthorizedType

type AuthorizedType int

AuthorizedType represents the entity that authorizes a responder.

const (
	// CA signs the response cache directory itself.
	Itself AuthorizedType = iota
	// CA has delegated signing authorization to the responder.
	// The responder's certificate contains the id-kp-OCSPSigning extension.
	Delegation
)

type CADBClient

type CADBClient interface {
	Scan(ctx context.Context) ([]db.IntermidiateEntry, error)
}

CADBClient is an interface that represents a client for scanning a database and creating IntermediateEntries.

type CacheBatch

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

The CacheBatch function scans the CA database for certificates with revocation information and generates response caches. It then updates the dyocsp.ResponseCacheStore with these caches. The job is repeated infinitely with an interval between each job. The interval refers to the interval of the OCSP Response Next Update. This Loop delays processing until the specified interval is reached, taking into account the duration of the batch job.

func NewCacheBatch

func NewCacheBatch(
	ca string,
	cacheStore *cache.ResponseCacheStore,
	caDBClient CADBClient,
	responder *Responder,
	nextUpdate time.Time,
	opts ...CacheBatchOption,
) (*CacheBatch, error)

NewCacheBatch creates a new instance of dyocsp.CacheBatch and returns it.

func (*CacheBatch) Run

func (c *CacheBatch) Run(ctx context.Context)

Run starts a loop that processes the batch and caches signed response caches in the interval specification. The batch execute following jobs in order.

• Scan the CA database with db.CADBClient.Scan().
• Verify revocation information entries and create, sign OCSP response.
• Verify the revocation information entries.
• Create and sign an OCSP response.
• Compute the wait time needed to adjust for any out-of-sync between the actual time and the next update time. This can occur due to delays in processing or the duration of batch processing.
• Update Next Update.
• Wait for next update.

func (*CacheBatch) RunOnce

func (c *CacheBatch) RunOnce(ctx context.Context) []cache.ResponseCache

RunOnce returns a slice of cache.ResponseCache through the following process.

• Scan the CA database to identify entries related to certificate revocation.
• Verify and parse entries for pre-signed response caches.
• Sign the pre-signed response caches using the dyocsp.Responder.

This function is the main job of dyocsp.CacheBatch.Run().

type CacheBatchOption

type CacheBatchOption func(*CacheBatch)

CacheBatchOption is type of an functional option for dyocsp.CacheBatch.

type CacheHandler

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

CacheHandler is an implementation of the http.Handler interface. It is used to handle OCSP requests.

func (CacheHandler) ServeHTTP

func (c CacheHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles an OCSP request with following steps.

• Verify that the request is in the correct form of an OCSP request. If the request is Malformed, it sends ocsp.MalformedRequestErrorResponse.
• Check if the issuer is correct. If the issuer is not valid, it sends ocsp.UnauthorizedErrorRespons.
• Searche for a response cache using the serial number from the request. If the cache is not found, it sends ocsp.UnauthorizedErrorRespons.

This Handler add headers Headers introduced in RFC5019. (https://www.rfc-editor.org/rfc/rfc5019#section-5)

type CacheHandlerOption

type CacheHandlerOption func(*CacheHandler)

CacheHandlerOption is type of an functional option for dyocsp.CacheHandler.

type IssuerHash

type IssuerHash struct {
	// SHA-1 hash.
	SHA1 []byte
}

IssuerHash is used to compare the hashes of the responder's issuer and the requested issuer to check if they are the same.

type KeyAlg

type KeyAlg int

KeyAlg is a supported signing key algorithm.

const (
	// RSA signing key algorithm.
	AlgRSA KeyAlg = iota
	// ECDSA signing key algorithm.
	AlgECDSA
	AlgUnknown
)

type KeyFormat

type KeyFormat int

KeyFormat is a supported key format type.

const (
	// PKCS #8 key format.
	PKCS8 KeyFormat = iota
	FormatUnknown
)

type Responder

type Responder struct {

	// Hash of issuer's DN
	IssuerNameHash IssuerHash
	// Hash of issuer's public key
	IssuerKeyHash IssuerHash
	// Represents the entity that authorizes a responder.
	AuthType AuthorizedType
	// contains filtered or unexported fields
}

The Responder struct represents an OCSP responder. It has the ability to sign the response cache and verify the issuer in OCSP requests.

func BuildResponder

func BuildResponder(rCertPem, rPrivKeyPem, issuerCertPem []byte, nowT time.Time) (*Responder, error)

BuildResponder verifies the provided certificates and private key formats. It takes a PEM format responder certificate, a PKCS#8 encoded PEM format responder private key, and a PEM format issuer certificate as input. It then creates and returns a new dyocsp.Responder instance.

func (*Responder) SignCacheResponse

func (r *Responder) SignCacheResponse(cache cache.ResponseCache) (cache.ResponseCache, error)

SignResponse signs the pre-signed cache.ResponseCache and creates a SHA-1 hash from the signed response for caching by the client (e.g., ETag). The type of signature algorithm used depends on the specific type of private key being used by the responder.

func (*Responder) Verify

func (r *Responder) Verify(nowT time.Time) error

Verify that the responder has valid certificates and a private key.