Static ReadonlyAUDIT_Static ReadonlyCHECK_Static ReadonlyPURPOSESStaticanchorsIs there anything a site could build a path to? Its own configured anchors, or under paranoid the realm's signer truststore where its use case may reach it. A site asks this where it would otherwise refuse for having no anchor.
the purpose
what the site was configured with
Optionaloptions: any
{ realmId }
whether a path could be built
StaticannouncedWhich settings have been announced as off in this process.
the settings
StaticappliesWhether paranoid applies to a purpose: the master in force AND its row on.
the purpose
OptionalrealmId: string
the realm; the ambient one where omitted
true when the door holds this use case to the full checks
StaticassessTHE DOOR. Holds a certificate to what its use case asks and answers one verdict. Never rejects for a bad certificate; a verdict says so.
the purpose
{ leaf, chain, key, registered: { chain }, pinned, peer, verified, source }; peer is getPeerCertificate(true)
Optionaloptions: any
{ realmId, now, skewMs, expectName, anchors, anchorSources (only narrower), allowCritical, allowSha1, variant, role, heldAnchors, force }; force holds it to the checks whatever the
settings say, for the inventory, and neither counts nor audits it
a promise of the verdict
StaticassessWhat a handshake's peer owes once OpenSSL has verified it, with revocation:
holdPeer(), then the fetch a hold cannot wait for. Counted and audited as
assess() is. A staple is asked first, and the store variant refuses
only what is revoked (see the table).
the purpose
getPeerCertificate(true)
Optionaloptions: any
{ realmId, now, staple, variant, expectName, pinnedTo };
pinnedTo is the dialer's own ca
a promise of { ok, inForce, code, why }
StaticassessThe synchronous door, for a site that cannot wait: a one-hop path through
verifyIssuedDirectly() and the register alone. A purpose whose
revocation needs a fetch answers not-asked, which paranoid refuses: the
right answer here, since such a caller must move to assess().
the purpose
{ leaf, chain }
Optionaloptions: any
as assess(); anchors are the authorities
the verdict
StaticauditThe audit of one realm: every pin and every truststore entry, the result kept for the page, and a log line and a mail only for what CHANGED, so a daily job does not say the same thing daily.
OptionalrealmId: string
the realm; the ambient one where omitted
Optionaloptions: any
{ now }
a promise of { pins, truststore, changes }
StaticbareA JWK that carries an x5c is held as jose-signer would hold its leaf; a
bare one is left alone, which OpenID Federation 1.1 section 3 defines.
the key that verified
Optionaloptions: any
as pinnedSync()
{ ok, code, why }
StaticcountersWhat the door has answered, in every process of this cluster.
OptionalrealmId: string
the realm; the ambient one where omitted
per purpose, { assessed, refused, lastRefusal }
StaticdirectThe synchronous door for a one-hop issuer check, in the shape
pki.verifyIssuedDirectly() answers. no-path is answered uncounted,
since a site tries one authority after another and only the last says
anything.
the purpose
the leaf's DER
as verifyIssuedDirectly() takes them
Optionaloptions: any
{ realmId, now, skewMs, allowCritical, variant }
{ ok, chain } or { ok: false, check, reason, code }
StaticdocsThe published table of use cases, generated from the purpose table so the documentation and the code cannot disagree.
the whole of docs/v1.1.0/pki-use-cases.md
StaticdocsWhere the generated page lives.
its path
StaticendingThe same stop for a client certificate, under paranoid PKI mode: a chain that OpenSSL verified ends at the listener's own anchor. Only what that listener trusts counts, so a public root is no anchor here. Out of force the chain is as presented, which is what the row off owes.
what is above the leaf, as DER
the listener's anchors, as DER
the chain to ask revocation of
StaticfieldsA certificate's own fields, under the purpose's rule, where something else has already decided how it came to be trusted: a responder its issuer delegated to, a pinned certificate, a signature a site just checked. Counted and audited as any other refusal.
the purpose
PEM, DER or an x5c member
Optionaloptions: any
{ realmId, now, skewMs, variant, mayBeCa, fieldRole, only (the checks to ask, all of them otherwise) }; a fieldRole other
than leaf asks for a certificate authority
{ ok, code, why }; ok when paranoid does not apply
StaticforgetRemoves a pin source, for a test putting back what it found.
the source's name
StaticholdTHE HOLD ON A HANDSHAKE: what can be decided while OpenSSL's verdict is
being read, before any request on the connection is. OpenSSL built the
path, so this asks the rules of it, and under paranoid the leaf's fields.
Not in force, it is the baseline: the rules alone, which is what
holdToPathRules() asked before #1360. Revocation is a fetch, so a
listener asks it apart (tls_server.js's holdConnectionsOn()), except
options.register, this service's own register, which has no network.
the purpose: tls-client or cell-peer
getPeerCertificate(true)
Optionaloptions: any
{ realmId, now, register }
{ ok, inForce, check, code, why }
StaticinWhether the master is in force in a realm.
OptionalrealmId: string
the realm; the ambient one where omitted
{ master, inForce, decidedBy }
StaticinstallRegisters the audit job and the write rule: called once per process by the composition root, which every process runs, so all register the same jobs.
OptionalschedulerInstance: any
the scheduler; the service's where omitted
true when this call registered the job
StaticlastWhat the audit last found for a realm.
OptionalrealmId: string
the realm; the ambient one where omitted
{ assessedAt, pins, truststore }, or an empty answer
StaticmarkdownA markdown table cell. A backslash is escaped before a pipe, so a cell cannot open a column and a backslash cannot unescape the pipe after it.
the cell's text
the escaped cell
StaticpathThe door for a site that builds a path to anchors it was configured with,
in the shape pki.verifyPathToAnchors() answers, so the site's own codes
and wording stand. Not in force, it IS that call. In force, it is
assess(), and a refusal adds code, the door's name for what failed; the
audit row is assess()'s.
the purpose
the leaf's DER
DER, any order
what the site trusts
Optionaloptions: any
{ realmId, now, skewMs, allowCritical, variant, siteAsksRevocation }
{ ok, chain } or { ok: false, check, reason, code }
StaticpinnedEvery certificate the realm pins, from every source, with its status.
OptionalrealmId: string
the realm; the ambient one where omitted
Optionaloptions: any
{ now }
a promise of the rows
StaticpinnedA pinned certificate at a door that cannot wait: a SAML request's signature
and a WS-Security token are answered in one tick, inside handlers that hand
back a value. Fields, the pin rule, and one hop through the signer truststore
are decided here. REVOCATION IS READ FROM WHAT WAS LAST FETCHED, and a
certificate nothing has been fetched about starts that fetch and is refused
this once, since a check nobody made is a refusal; pki.pins.audit and the
first request both fill it. A certificate that names no list and no responder
has nothing to fetch, and the register answers for it now.
the purpose
PEM or DER
Optionaloptions: any
{ realmId, now, registered (a pin) }
{ ok, code, why }; ok when paranoid does not apply
StaticpurposeStaticreachesWhether what a leaf's own Authority Information Access led to reaches an anchor this realm holds, so an address in a certificate decides nothing.
the leaf's DER
what was fetched, as DER
a promise of true or false
StaticrealmThe door for a certificate that must chain to this realm's own
Intermediate, in the shape pki.verifyLeaf() answers. The path and its
revocation are that function's; in force the leaf's fields are asked too.
the purpose
the realm, or undefined for the ambient one
the leaf
what was presented with it
Optionaloptions: any
{ now, skewMs, variant }
what verifyLeaf() answers, or { ok: false, why, revocation }
marked with the field's code
StaticregisterRegisters one owner's list of what it pins.
the source's name
(realmId) => PinnedSource[], or a promise of them
StaticregistrationA certificate at the door it is registered through, under paranoid PKI mode: its fields only. A write is not a use, so its chain and revocation are asked at the use, and something that will expire next year is written today.
the purpose it will be used for
PEM or DER
Optionaloptions: any
{ realmId, now }
null, or { code, why }
Staticrequireassess(), thrown: a refusal is an Error carrying .code and .verdict.
the purpose
as assess()
Optionaloptions: any
as assess()
a promise of the verdict, when it holds
StaticrowWhether a purpose's own row is on.
the purpose
OptionalrealmId: string
the realm; the ambient one where omitted
the row's value
StaticsignerA registered key's certificate chain, at the use: what the RFC 7523 and RFC
7522 verifiers call in place of pki.verifySignerChain(), with its answer's
shape. Not in force it IS that function. In force: an incomplete chain is
completed from the signer truststore before it is refused, the leaf's fields
are asked, and a self-signed x5c[0] is held to the purpose's rule, which
closes the asymmetry with the upload door. Revocation stays where the sites
already ask it, registeredKeyVerdictFor().
the purpose: jose-signer or saml-signer
{ certificate, chain, key, source, index }
Optionaloptions: any
{ realmId }
a promise of verifySignerChain()'s answer
StaticwriteThe write rule of the paranoid rows: it refuses nothing, because an operator may have a reason, and it is the one place a write that turns a check off in product is logged.
the setting
the value being written
null, always
The one door every X.509 validation goes through, and the settings of paranoid PKI mode.
A static utility class:
common/outbound_tls.ts's shape. It composescrypto.js's field checks,pki.js's paths andrevocation_status.js.