certdb

README

certdb usage

Using a database enables additional functionality for existing commands when a db config is provided:

• sign and gencert add a certificate to the certdb after signing it
• serve enables database functionality for the sign and revoke endpoints

A database is required for the following:

• revoke marks certificates revoked in the database with an optional reason
• ocsprefresh refreshes the table of cached OCSP responses
• ocspdump outputs cached OCSP responses in a concatenated base64-encoded format

Setup/Migration

This directory stores goose db migration scripts for various DB backends. Currently supported:

• SQLite in sqlite
• PostgreSQL in pg

Get goose

go get https://bitbucket.org/liamstask/goose/

Use goose to start and terminate a SQLite DB

To start a SQLite DB using goose:

goose -path $GOPATH/src/github.com/cloudflare/cfssl/certdb/sqlite up'

To tear down a SQLite DB using goose

goose -path $GOPATH/src/github.com/cloudflare/cfssl/certdb/sqlite down

Use goose to start and terminate a PostgreSQL DB

To start a PostgreSQL using goose:

goose -path $GOPATH/src/github.com/cloudflare/cfssl/certdb/pg up

To tear down a PostgreSQL DB using goose

goose -path $GOPATH/src/github.com/cloudflare/cfssl/certdb/pg down

Note: the administration of PostgreSQL DB is not included. We assume the databases being connected to are already created and access control are properly handled.

CFSSL Configuration

Several cfssl commands take a -db-config flag. Create a file with a JSON dictionary:

{"driver":"sqlite3","data_source":"certs.db"}

or

{"driver":"postgres","data_source":"postgres://user:password@host/db"}

Documentation

Index

• func DBFromConfig(path string) (db *sql.DB, err error)
• func InsertCertificate(db *sql.DB, cr *CertificateRecord) error
• func InsertOCSP(db *sql.DB, rr *OCSPRecord) error
• func RevokeCertificate(db *sql.DB, serial string, reasonCode int) error
• func UpdateOCSP(db *sql.DB, serial, body string, expiry time.Time) (err error)
• func UpsertOCSP(db *sql.DB, serial, body string, expiry time.Time) (err error)
• type CertificateRecord
  • func GetCertificate(db *sql.DB, serial string) (*CertificateRecord, error)
  • func GetUnexpiredCertificates(db *sql.DB) (crs []*CertificateRecord, err error)
• type DBConfig
  • func LoadFile(path string) (cfg *DBConfig, err error)
• type OCSPRecord
  • func GetOCSP(db *sql.DB, serial string) (rr *OCSPRecord, err error)
  • func GetUnexpiredOCSPs(db *sql.DB) (rrs []*OCSPRecord, err error)

Functions

func DBFromConfig

func DBFromConfig(path string) (db *sql.DB, err error)

DBFromConfig opens a sql.DB from settings in a db config file

func InsertCertificate

func InsertCertificate(db *sql.DB, cr *CertificateRecord) error

InsertCertificate puts a CertificateRecord into db.

func InsertOCSP

func InsertOCSP(db *sql.DB, rr *OCSPRecord) error

InsertOCSP puts a new OCSPRecord into the db.

func RevokeCertificate

func RevokeCertificate(db *sql.DB, serial string, reasonCode int) error

RevokeCertificate updates a certificate with a given serial number and marks it revoked.

func UpdateOCSP

func UpdateOCSP(db *sql.DB, serial, body string, expiry time.Time) (err error)

UpdateOCSP updates a ocsp response record with a given serial number.

func UpsertOCSP

func UpsertOCSP(db *sql.DB, serial, body string, expiry time.Time) (err error)

UpsertOCSP update a ocsp response record with a given serial number, or insert the record if it doesn't yet exist in the db Implementation note: We didn't implement 'upsert' with SQL statement and we lost race condition prevention provided by underlying DMBS. Reasoning: 1. it's diffcult to support multiple DBMS backends in the same time, the SQL syntax differs from one to another. 2. we don't need a strict simultaneous consistency between OCSP and certificate status. It's OK that a OCSP response still shows 'good' while the corresponding certificate is being revoked seconds ago, as long as the OCSP response catches up to be eventually consistent (within hours to days). Write race condition between OCSP writers on OCSP table is not a problem, since we don't have write race condition on Certificate table and OCSP writers should periodically use Certificate table to update OCSP table to catch up.

Types

type CertificateRecord

type CertificateRecord struct {
	Serial    string    `sql:"serial"`
	CALabel   string    `sql:"ca_label"`
	Status    string    `sql:"status"`
	Reason    int       `sql:"reason"`
	Expiry    time.Time `sql:"expiry"`
	RevokedAt time.Time `sql:"revoked_at"`
	PEM       string    `sql:"pem"`
}

CertificateRecord encodes a certificate and its metadata that will be recorded in a database.

func GetCertificate

func GetCertificate(db *sql.DB, serial string) (*CertificateRecord, error)

GetCertificate gets a CertificateRecord indexed by serial.

func GetUnexpiredCertificates

func GetUnexpiredCertificates(db *sql.DB) (crs []*CertificateRecord, err error)

GetUnexpiredCertificates gets all unexpired certificate from db.

type DBConfig

type DBConfig struct {
	DriverName     string `json:"driver"`
	DataSourceName string `json:"data_source"`
}

DBConfig contains the database driver name and configuration to be passed to Open

func LoadFile

func LoadFile(path string) (cfg *DBConfig, err error)

LoadFile attempts to load the db configuration file stored at the path and returns the configuration. On error, it returns nil.

type OCSPRecord

type OCSPRecord struct {
	Serial string    `sql:"serial"`
	Body   string    `sql:"body"`
	Expiry time.Time `sql:"expiry"`
}

OCSPRecord encodes a OCSP response body and its metadata that will be recorded in a database.

func GetOCSP

func GetOCSP(db *sql.DB, serial string) (rr *OCSPRecord, err error)

GetOCSP retrieves a OCSPRecord from db by serial.

func GetUnexpiredOCSPs

func GetUnexpiredOCSPs(db *sql.DB) (rrs []*OCSPRecord, err error)

GetUnexpiredOCSPs retrieves all unexpired OCSPRecord from db.