Documentation
¶
Overview ¶
Package identitypreflight is the engine of bide identity check: a pre-flight for a certificate-bound approval setup, run before go-live and when an approver's decision is refused. It reports, one check at a time, whether the identity policy file loads, the pinned CAs and intermediates match, the CRLs are reachable and fresh enough for the declared status ages, the declared values agree with the gate's recorded policy, and a given approver certificate would be accepted.
It decides nothing itself. Every verdict is the gate's own: the policy is compiled by audit.ParseIdentityPolicy, the declared timings are validated by audit.CertApprover.ValidateConfig, CRLs are fetched and judged by the crlrefresh package, and a certificate chain is judged by audit.CertApprover.CheckCertificate, the function the gate's counting and execution checks call. This package reads files and fetches CRLs (it is where that I/O lives, not audit), orders the answers, and words the fix for each.
Index ¶
Constants ¶
const ( ExitReady = 0 // no check failed and nothing was left unchecked ExitFail = 1 // at least one check failed: the setup will not work as configured ExitUsage = 2 // a usage error ExitIO = 3 // a file could not be read, or the tool could not run ExitPartial = 4 // no check failed, but a part was acknowledged as not checked (-no-status, -no-expect) )
Exit codes of bide identity check.
Variables ¶
var NotCheckable = []string{
"the signature of a real decision, and that the approver's key is the certificate's key (no decision exists yet)",
"when a real decision becomes provable: the signed head that will cover it, the log clock, and an independent time source (none is shipped)",
"whether a future decision will be provisional or final: that depends on revocations published after it and on the window W",
"revocations published after this check, and whether the CRLs stay reachable from the gate host (run -fetch on the gate host; the application's own HTTP client, proxy and DNS rules are not exercised)",
"the gate's other settings unless -expect supplies them: separation of duties, the roster, requester mapping, holds, and the GODEBUG of the gate process",
"that the gate embeds the CRL refresher or that a fetch-crl job is running",
}
NotCheckable is what a pre-flight cannot establish ahead of time. It is printed with every report.
Functions ¶
This section is empty.
Types ¶
type Check ¶
type Check struct {
ID string `json:"id"`
Status Status `json:"status"`
Message string `json:"message"`
Fix string `json:"fix,omitempty"`
}
Check is one line of the report. ID is stable (the troubleshooting table of the certificate approvers guide is keyed by it); Fix is empty for an OK.
type IOError ¶
type IOError struct{ Err error }
IOError is a file that could not be read or a tool that could not run; the command exits with ExitIO.
type Options ¶
type Options struct {
// Policy is the certificate policy file; Params the declaration of the CA timings (the file bide
// identity fetch-crl takes).
Policy, Params string
// Expect is the gate's recorded policy (the identity record's "policy" member, or the whole record)
// to compare the declared values with; NoExpect acknowledges that it is not compared.
Expect string
// ExpectDigest is the gate's policy digest (the pause note's identity_policy_digest, or the identity
// record's policy_digest), lowercase hex. It is compared with the digest of the declaration only when
// the -params file states every member the digest covers; otherwise the check fails naming the missing
// members. It can stand in for Expect, or be given with it.
ExpectDigest string
NoExpect bool
// CRLDir is a directory of CRLs read without network: a crlrefresh archive, or a flat directory of CRL
// files. Fetch asks the policy's crl sources over HTTP(S) with the crlrefresh fetch code, storing
// nothing; with CRLDir the directory seeds the rollback memory. NoStatus acknowledges that CRL status
// is not checked.
CRLDir string
Fetch bool
NoStatus bool
// Cert is an approver's certificate chain, leaf first (PEM); Chain holds more certificates to carry
// behind it. As is the approver id; optional when the policy names exactly one.
Cert, Chain, As string
// At is the time to judge at (default now). It cannot be set with Fetch.
At time.Time
// Client is the HTTP client for Fetch (the proxy from the environment, for the command); nil uses the
// library's.
Client *http.Client
}
Options says what to check. Policy and Params are required, and so is a stance on CRL status (CRLDir, Fetch or NoStatus) and on the gate's record (Expect or NoExpect): a pre-flight never reports ready with a part of the setup it was not asked to look at.
type Report ¶
type Report struct {
// Ready is true only when no check failed and nothing the gate relies on was left unchecked.
Ready bool `json:"ready"`
// Partial is true when the caller acknowledged leaving a part out (-no-status, -no-expect): the report
// is then never ready, whatever else passed.
Partial bool `json:"partial"`
CheckedAt time.Time `json:"checked_at"`
Checks []Check `json:"checks"`
// NotCheckable lists what no pre-flight can establish; it is part of every report.
NotCheckable []string `json:"not_checkable"`
}
Report is the result of Run.
func Run ¶
Run performs the checks. The error is an *UsageError for a mistake in o, an *IOError for a file that cannot be read, and otherwise nil: a setup that is wrong is a report with failed checks, not an error.
type Status ¶
type Status string
Status is the outcome of one check.
The outcomes. Fail means a gate built from this setup would refuse, pause or miscount; Warn means it works but will not for long or differs from a recorded value in a way that does not reach a verdict; Skip means the check did not run, and Report.Partial says whether that makes the report incomplete.
type UsageError ¶
type UsageError struct{ Msg string }
UsageError is a mistake in the options; the command exits with ExitUsage.
Source Files