Skip to content

Package audit/crlrefresh ​

Go module github.com/bide-ai/bide; all packages.

github.com/bide-ai/bide/audit/crlrefresh · pkg.go.dev · Stability: experimental

Package crlrefresh keeps the status snapshot of a certificate-bound approver (audit.CertApprover) supplied with the newest verified CRLs of the issuing CAs its policy pins, and archives every CRL it accepts (docs/design/crl-refresher.md, docs/guides/certificate-approvers.md).

Constants

  • const MarkerRollback = "rollback", const MarkerConflict = "conflict": Markers on a CRL archived but not added to the snapshot: a rollback (its number is below the issuer's high-water mark) or a conflict (the mark's number with another TBSCertList).
  • const MarkerSetAside = "setaside": MarkerSetAside marks a CRL a source served after an operator set it aside.

type Alarm ​

go
type Alarm struct {
	Issuer    audit.SPKIHash
	Active    bool
	Critical  bool
	Age       time.Duration
	Threshold time.Duration
	Limit     time.Duration
	At        time.Time
	Detail    string
}

Alarm is a change in an issuer's alarm state.

type Archive ​

go
type Archive interface {
	PutCRL(ctx context.Context, issuer audit.SPKIHash, a ArchivedCRL, der []byte) error

	List(ctx context.Context, issuer audit.SPKIHash) ([]ArchivedCRL, error)

	Read(ctx context.Context, issuer audit.SPKIHash, a ArchivedCRL) ([]byte, error)

	PutReset(ctx context.Context, issuer audit.SPKIHash, r ResetRecord) error
	Resets(ctx context.Context, issuer audit.SPKIHash) ([]ResetRecord, error)
	AckReset(ctx context.Context, issuer audit.SPKIHash, r ResetRecord) error
}

Archive is the dated archive of the CRLs the refresher accepts, and its rollback memory.

type ArchivedCRL ​

go
type ArchivedCRL struct {
	Name       string
	Number     *big.Int
	ThisUpdate time.Time
	Marker     string

	Source  string
	Fetched time.Time
}

ArchivedCRL describes one CRL file of the archive.

type DirArchive ​

go
type DirArchive string

DirArchive is a Archive in a directory: <dir>/crl/<issuer key hash>/<number>-<thisUpdate>.crl, with a .meta.json beside each file (source and fetch time), and RESET-<time>.json for resets.

Methods

  • func (d DirArchive) AckReset(_ context.Context, issuer audit.SPKIHash, r ResetRecord) error: AckReset implements Archive.
  • func (d DirArchive) List(_ context.Context, issuer audit.SPKIHash) ([]ArchivedCRL, error): List implements Archive.
  • func (d DirArchive) PutCRL(_ context.Context, issuer audit.SPKIHash, a ArchivedCRL, der []byte) error: PutCRL implements Archive.
  • func (d DirArchive) PutReset(_ context.Context, issuer audit.SPKIHash, r ResetRecord) error: PutReset implements Archive.
  • func (d DirArchive) Read(_ context.Context, issuer audit.SPKIHash, a ArchivedCRL) ([]byte, error): Read implements Archive.
  • func (d DirArchive) Resets(_ context.Context, issuer audit.SPKIHash) ([]ResetRecord, error): Resets implements Archive.

type Event ​

go
type Event struct {
	Kind     EventKind
	Issuer   audit.SPKIHash
	Feed     string
	URL      string
	Detail   string
	Number   *big.Int
	Held     *big.Int
	Hash     [32]byte
	Err      error
	At       time.Time
	Outcomes []URLOutcome
}

Event is one thing the refresher did or refused.

type EventKind ​

go
type EventKind string

EventKind names what an Event reports.

Constants

  • const EventStartup EventKind = "startup", const EventFetched EventKind = "fetched", const EventUnchanged EventKind = "unchanged", const EventFetchFailed EventKind = "fetch-failed", const EventRollback EventKind = "rollback", const EventConflict EventKind = "conflict", const EventBadSignature EventKind = "bad-signature", const EventDistrusted EventKind = "distrusted", const EventUnsupportedCRL EventKind = "unsupported-crl", const EventFutureDated EventKind = "future-dated", const EventStaleOnArrival EventKind = "stale-on-arrival", const EventArchiveError EventKind = "archive-error", const EventArchiveDropped EventKind = "archive-dropped", const EventArchiveCorrupt EventKind = "archive-corrupt", const EventClockSkew EventKind = "clock-skew", const EventHighWaterReset EventKind = "high-water-reset", const EventSetAsideServed EventKind = "set-aside-served", const EventSourcesChanged EventKind = "sources", const EventPanic EventKind = "panic", const EventSeedStopped EventKind = "seed-stopped", const EventUnpairedDelta EventKind = "unpaired-delta", const EventRedirectRefused EventKind = "redirect-refused", const EventOversizeResponse EventKind = "oversize": The events.

type Hooks ​

go
type Hooks struct {
	OnEvent func(Event)
	OnAlarm func(Alarm)
}

Hooks are called from the refresher's goroutines, possibly concurrently for different issuers.

type IssuerHealth ​

go
type IssuerHealth struct {
	Issuer              audit.SPKIHash
	URLs, DeltaURLs     []string
	LastAttempt         time.Time
	LastSuccess         time.Time
	NewestNumber        *big.Int
	NewestThisUpdate    time.Time
	NewestNextUpdate    time.Time
	Age                 time.Duration
	NextExpected        time.Time
	NextAttempt         time.Time
	ConsecutiveFailures int
	LastError           string
	ArchiveBacklog      int
	Paired              bool
	Alarm, Critical     bool
	Limit               time.Duration
	AlarmAge            time.Duration
	Loop                time.Time
	UnackedResets       int
}

IssuerHealth is the state of one issuer, from Health.

type IssuerResult ​

go
type IssuerResult struct {
	Issuer audit.SPKIHash
	Err    error
}

IssuerResult is the outcome of one issuer in RefreshOnce.

type Options ​

go
type Options struct {
	Issuers []*x509.Certificate

	DeltaPeriodFor map[audit.SPKIHash]time.Duration

	StandIn *StandIn

	Client *http.Client

	Archive Archive

	Hooks Hooks

	Sleep func(ctx context.Context, d time.Duration) error
	Rand  func() float64

	MaxArchiveQueueBytes int
}

Options configures New.

type Refresher ​

go
type Refresher struct {
	// contains filtered or unexported fields
}

Refresher keeps the audit.StatusSnapshot of a audit.CertApprover supplied with the newest verified CRLs of the issuing CAs the certificate policy pins, and archives every CRL it accepts (docs/design/crl-refresher.md).

Constructors and functions

  • func New(a *audit.CertApprover, sources audit.CRLSources, opt Options) (*Refresher, error): New builds the refresher for approver's snapshot.

Methods

  • func (r *Refresher) AckReset(ctx context.Context, issuer audit.SPKIHash, name string) error: AckReset marks a high-water reset record of the issuer (by its name, as Health and the start-up event give it) as acknowledged by an operator: the start-up event for it stops.
  • func (r *Refresher) Health() []IssuerHealth: Health returns the state of every issuer, ordered by key.
  • func (r *Refresher) Ready() <-chan struct{}: Ready is closed once every issuer holds a fresh CRL.
  • func (r *Refresher) RefreshOnce(ctx context.Context) []IssuerResult: RefreshOnce runs one attempt for every feed of every issuer (seeding from the archive first when the snapshot is empty) and returns each issuer's outcome: an error when no valid CRL was obtained or the newest one is not fresh.
  • func (r *Refresher) ResetHighWater(ctx context.Context, issuer audit.SPKIHash, req ResetRequest) error: ResetHighWater is the operator's way out of a poisoned high-water mark: a CA that issued one CRL with a mistaken huge number, or was restored from a backup and restarted its numbering, would otherwise leave every later real CRL a rollback.
  • func (r *Refresher) Run(ctx context.Context) error: Run seeds from the archive, then fetches until ctx is cancelled and the in-flight requests end.
  • func (r *Refresher) Seed(ctx context.Context) error: Seed loads what the live rule needs from the archive into the snapshot, newest first, and takes the high-water marks from the CRLs that verify.

type ResetItem ​

go
type ResetItem struct {
	Hash   string `json:"hash"`
	Number string `json:"number"`
}

ResetItem is one CRL a reset sets aside.

type ResetRecord ​

go
type ResetRecord struct {
	Name     string      `json:"-"`
	Issuer   string      `json:"issuer"`
	SetAside []ResetItem `json:"set_aside"`

	LostSerials []string  `json:"lost_serials,omitempty"`
	Reason      string    `json:"reason"`
	Operator    string    `json:"operator"`
	Time        time.Time `json:"time"`
	Acked       bool      `json:"-"`
}

ResetRecord is the durable record of an operator's reset of an issuer's high-water mark: the CRLs it sets aside, who did it and why.

type ResetRequest ​

go
type ResetRequest struct {
	Reason, Operator string

	SetAside [][32]byte

	AcceptLostListings bool
}

ResetRequest is an operator's request to reset an issuer's high-water mark.

type StandIn ​

go
type StandIn struct{ Missing []string }

StandIn says what a declaration file lacked of the values the policy digest covers (audit.StatusDecl.MissingForDigest).

type URLOutcome ​

go
type URLOutcome struct {
	URL string `json:"url"`

	Kind   string `json:"kind"`
	Status int    `json:"status,omitempty"`
	Detail string `json:"detail,omitempty"`
}

URLOutcome is the result of asking one URL in one attempt, for the event.

Apache-2.0 licensed.