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
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
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
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
type DirArchive stringDirArchive 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
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
type EventKind stringEventKind 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
type Hooks struct {
OnEvent func(Event)
OnAlarm func(Alarm)
}Hooks are called from the refresher's goroutines, possibly concurrently for different issuers.
type IssuerHealth
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
type IssuerResult struct {
Issuer audit.SPKIHash
Err error
}IssuerResult is the outcome of one issuer in RefreshOnce.
type Options
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
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
type ResetItem struct {
Hash string `json:"hash"`
Number string `json:"number"`
}ResetItem is one CRL a reset sets aside.
type ResetRecord
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
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
type StandIn struct{ Missing []string }StandIn says what a declaration file lacked of the values the policy digest covers (audit.StatusDecl.MissingForDigest).
type URLOutcome
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.