iya-sts
    Preparing search index...

    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 composes crypto.js's field checks, pki.js's paths and revocation_status.js.

    Index
    AUDIT_JOB: "pki.pins.audit" = AUDIT_JOB
    CHECK_ORDER: CheckId[] = CHECK_ORDER
    PURPOSES: Purpose[] = PURPOSES
    • Is 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.

      Parameters

      • id: string

        the purpose

      • anchors: any[]

        what the site was configured with

      • Optionaloptions: any

        { realmId }

      Returns boolean

      whether a path could be built

    • Which settings have been announced as off in this process.

      Returns string[]

      the settings

    • Whether paranoid applies to a purpose: the master in force AND its row on.

      Parameters

      • id: string

        the purpose

      • OptionalrealmId: string

        the realm; the ambient one where omitted

      Returns boolean

      true when the door holds this use case to the full checks

    • THE DOOR. Holds a certificate to what its use case asks and answers one verdict. Never rejects for a bad certificate; a verdict says so.

      Parameters

      • id: string

        the purpose

      • material: any

        { 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

      Returns Promise<TrustVerdict>

      a promise of the verdict

    • What 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).

      Parameters

      • id: string

        the purpose

      • peer: any

        getPeerCertificate(true)

      • Optionaloptions: any

        { realmId, now, staple, variant, expectName, pinnedTo }; pinnedTo is the dialer's own ca

      Returns Promise<any>

      a promise of { ok, inForce, code, why }

    • The 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().

      Parameters

      • id: string

        the purpose

      • material: any

        { leaf, chain }

      • Optionaloptions: any

        as assess(); anchors are the authorities

      Returns TrustVerdict

      the verdict

    • The 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.

      Parameters

      • OptionalrealmId: string

        the realm; the ambient one where omitted

      • Optionaloptions: any

        { now }

      Returns Promise<any>

      a promise of { pins, truststore, changes }

    • A 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.

      Parameters

      • jwk: any

        the key that verified

      • Optionaloptions: any

        as pinnedSync()

      Returns any

      { ok, code, why }

    • What the door has answered, in every process of this cluster.

      Parameters

      • OptionalrealmId: string

        the realm; the ambient one where omitted

      Returns any

      per purpose, { assessed, refused, lastRefusal }

    • The 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.

      Parameters

      • id: string

        the purpose

      • leaf: any

        the leaf's DER

      • authorities: any[]

        as verifyIssuedDirectly() takes them

      • Optionaloptions: any

        { realmId, now, skewMs, allowCritical, variant }

      Returns any

      { ok, chain } or { ok: false, check, reason, code }

    • The published table of use cases, generated from the purpose table so the documentation and the code cannot disagree.

      Returns string

      the whole of docs/pki-use-cases.md

    • Where the generated page lives.

      Returns string

      its path

    • The 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.

      Parameters

      • chain: Buffer[]

        what is above the leaf, as DER

      • anchors: Buffer[]

        the listener's anchors, as DER

      Returns Buffer[]

      the chain to ask revocation of

    • A 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.

      Parameters

      • id: string

        the purpose

      • cert: any

        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

      Returns any

      { ok, code, why }; ok when paranoid does not apply

    • Removes a pin source, for a test putting back what it found.

      Parameters

      • name: string

        the source's name

      Returns void

    • THE 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.

      Parameters

      • id: string

        the purpose: tls-client or cell-peer

      • peer: any

        getPeerCertificate(true)

      • Optionaloptions: any

        { realmId, now, register }

      Returns any

      { ok, inForce, check, code, why }

    • Whether the master is in force in a realm.

      Parameters

      • OptionalrealmId: string

        the realm; the ambient one where omitted

      Returns any

      { master, inForce, decidedBy }

    • Registers 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.

      Parameters

      • OptionalschedulerInstance: any

        the scheduler; the service's where omitted

      Returns boolean

      true when this call registered the job

    • What the audit last found for a realm.

      Parameters

      • OptionalrealmId: string

        the realm; the ambient one where omitted

      Returns any

      { assessedAt, pins, truststore }, or an empty answer

    • The 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.

      Parameters

      • id: string

        the purpose

      • leaf: any

        the leaf's DER

      • intermediates: any[]

        DER, any order

      • anchors: any

        what the site trusts

      • Optionaloptions: any

        { realmId, now, skewMs, allowCritical, variant, siteAsksRevocation }

      Returns Promise<any>

      { ok, chain } or { ok: false, check, reason, code }

    • Every certificate the realm pins, from every source, with its status.

      Parameters

      • OptionalrealmId: string

        the realm; the ambient one where omitted

      • Optionaloptions: any

        { now }

      Returns Promise<PinnedCertificate[]>

      a promise of the rows

    • A 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.

      Parameters

      • id: string

        the purpose

      • cert: any

        PEM or DER

      • Optionaloptions: any

        { realmId, now, registered (a pin) }

      Returns any

      { ok, code, why }; ok when paranoid does not apply

    • One row of the purpose table.

      Parameters

      • id: string

        the purpose

      Returns Purpose

      the row

      Error for a purpose the table does not name: a programming error

    • Whether what a leaf's own Authority Information Access led to reaches an anchor this realm holds, so an address in a certificate decides nothing.

      Parameters

      • leaf: Buffer

        the leaf's DER

      • issuers: Buffer[]

        what was fetched, as DER

      Returns Promise<boolean>

      a promise of true or false

    • The 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.

      Parameters

      • id: string

        the purpose

      • realmId: string

        the realm, or undefined for the ambient one

      • pem: string

        the leaf

      • chain: string[]

        what was presented with it

      • Optionaloptions: any

        { now, skewMs, variant }

      Returns Promise<any>

      what verifyLeaf() answers, or { ok: false, why, revocation } marked with the field's code

    • Registers one owner's list of what it pins.

      Parameters

      • name: string

        the source's name

      • fn: (realmId: string) => PinnedSource[] | Promise<PinnedSource[]>

        (realmId) => PinnedSource[], or a promise of them

      Returns void

    • A 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.

      Parameters

      • id: string

        the purpose it will be used for

      • cert: any

        PEM or DER

      • Optionaloptions: any

        { realmId, now }

      Returns any

      null, or { code, why }

    • assess(), thrown: a refusal is an Error carrying .code and .verdict.

      Parameters

      • id: string

        the purpose

      • material: any

        as assess()

      • Optionaloptions: any

        as assess()

      Returns Promise<TrustVerdict>

      a promise of the verdict, when it holds

    • Whether a purpose's own row is on.

      Parameters

      • id: string

        the purpose

      • OptionalrealmId: string

        the realm; the ambient one where omitted

      Returns boolean

      the row's value

    • A 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().

      Parameters

      • id: string

        the purpose: jose-signer or saml-signer

      • material: any

        { certificate, chain, key, source, index }

      • Optionaloptions: any

        { realmId }

      Returns Promise<any>

      a promise of verifySignerChain()'s answer

    • The 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.

      Parameters

      • key: string

        the setting

      • parsed: unknown

        the value being written

      Returns null

      null, always