iya-sts
    Preparing search index...

    A workload agent: one join token, the SPIRE Server API, and the Workload API on a Unix socket beside the workload (#324).

    Index
    • Records the options. Nothing is bound and nothing is attested here.

      Parameters

      • opts: any

        the server, the socket, the trust domain, the join token and the trust bundle

      Returns export=

    agentCertPem: string
    agentKeyPem: string
    agentSpiffeId: string
    anchorsPem: string
    attestAttempts: number
    attestPauseMs: number
    attestWorkloads: boolean
    bundleCa: string
    bundleUrl: string
    clients: any
    counter: number
    groupPath: string
    grpcServer: any
    injector: any
    joinToken: string
    latest: any
    listener: any
    log: any
    native: any
    nativePath: string
    passwdPath: string
    peers: Map<number, any>
    procRoot: string
    requireSecurityHeader: boolean
    server: string
    services: any
    socketPath: string
    started: boolean
    stopped: boolean
    timers: Set<any>
    trustBundlePem: string
    trustDomain: string
    • Records one accepted peer and injects the paused socket.

      Parameters

      • socket: any

        the accepted socket

      Returns void

    • Turns a thrown error into the refusal a handler reports.

      Parameters

      • err: any

        what was thrown

      Returns any

      the refusal

    • Attests with the join token, retrying while the call failed. A token minted on another node is not visible everywhere at once, and a refusal before the token is known does not spend it. A success is not retried: the token is spent.

      Parameters

      • csr: Buffer

        the agent's CSR

      Returns Promise<any>

      the agent X509-SVID message

    • One AttestAgent exchange. The send side stays open until the answer arrives: half-closing first makes the server finish the stream before the handler replies, and the token is spent on an empty answer.

      Parameters

      • csr: Buffer

        the agent's CSR

      Returns Promise<any>

      the response message

    • The entries the Server API says this agent may issue.

      Returns Promise<any[]>

      the entries

    • Binds the Unix socket and hands each connection to grpc-js after the peer is recorded. The socket is mode 0666 so a workload of another uid in the same task can connect. It is not resumed.

      Returns Promise<void>

    • FetchJWTSVID's answer.

      Parameters

      • request: any

        the request

      • selectors: string[]

        the caller's selector texts

      Returns Promise<any>

      the response

    • ValidateJWTSVID's answer. The signature is checked here, with node, against the bundle the Server API publishes.

      Parameters

      • request: any

        the request

      Returns Promise<any>

      the SPIFFE ID and the claims

    • Mints an X509-SVID for every entry the caller matches.

      Parameters

      • selectors: string[]

        the caller's selector texts

      Returns Promise<any>

      the SVIDs, the federated bundles and the shortest lifetime

    • One bundle response. The trust domain's own bundle is written after every federated one, so a federated document cannot replace it.

      Parameters

      • kind: string

        x509 or jwt

      Returns Promise<any>

      the response message

    • Marks a connection's facts as no longer the process that connected, so the next call on that socket is refused. A test uses this; killing the pidfd from outside is the same check against a live process.

      Parameters

      • facts: any

        the connection's facts

      Returns void

    • One unary Server API call.

      Parameters

      • client: any

        the service client

      • method: string

        the method

      • request: any

        the request

      Returns Promise<any>

      the response

    • Accepts the server only when its certificate names this trust domain's SPIRE server. A hostname check cannot: the certificate has no DNS name.

      Parameters

      • hostname: string

        unused; grpc-js passes it

      • cert: any

        the peer certificate

      Returns any

      undefined when it matches, otherwise an Error

    • Stops one stream's rotation and forgets its timer.

      Parameters

      • open: any

        the stream's flag

      Returns void

    • The entries this agent may issue, narrowed to the caller when attestation is on.

      Parameters

      • selectors: string[]

        the caller's selector texts

      Returns Promise<any[]>

      the entries

    • The device and inode of a process's executable.

      Parameters

      • pid: number

        the process id

      Returns any

      the device and inode, or zeros

    • Ends a server stream with a status.

      Parameters

      • call: any

        the gRPC call

      • refusal: any

        the error code, the status and the sentence

      Returns void

    • Fails a unary call.

      Parameters

      • call: any

        the gRPC call

      • callback: any

        grpc-js's callback

      • refusal: any

        the error code, the status and the sentence

      Returns void

    • Federated bundles named by registration entries. A denial is ignored: one trust domain the server will not show must not empty the answer. A key equal to this trust domain is skipped.

      Parameters

      • domains: string[]

        the trust domain names

      • jwt: boolean

        JWT documents rather than X.509 DER

      Returns Promise<any>

      the map keyed by spiffe://<domain>

    • GETs a URL and returns the body. Used for the public bundle document only.

      Parameters

      • url: string

        the URL

      Returns Promise<string>

      the body

    • Closes the pidfd and drops the facts.

      Parameters

      • facts: any

        the connection's facts

      Returns void

    • The Workload API handlers, keyed by the proto's method names.

      Returns any

      the handlers

    • Re-sends a stream at half the lifetime, and again after that, while the client is still there. Two functions, so the wait and the send are not one function calling itself: this is the Workload API's own rotation, per stream, in this process.

      Parameters

      • call: any

        the gRPC call

      • open: any

        the stream's flag

      • label: string

        what is being re-sent

      • build: any

        the next message

      • lifetimeSeconds: number

        the lifetime the last message carried

      Returns void

    • This trust domain's JWT authorities, as a JWK Set document.

      Returns Promise<Buffer>

      the document's bytes

    • The JWT keys of a trust domain. Null when this agent has no bundle for it. A failure to reach this trust domain's own bundle is thrown.

      Parameters

      • trustDomain: string

        the trust domain

      Returns Promise<any[]>

      the JWKs, or null

    • The facts of the connection accepted most recently, or null.

      Returns any

      the facts

    • Fetches the trust anchors: the PEM handed in, or the public HTTPS bundle document's x509-svid certificates.

      Returns Promise<void>

    • Loads the native peer-credentials module. A failure here is the end: the socket is not created, because a Workload API that cannot say who called it must not answer.

      Returns void

    • Loads the four Server API services and the Workload API service.

      Returns void

    • Makes one ECDSA P-256 certificate request. The server reads the public key and ignores the subject. The attributes tag is present and empty, because PKCS#10 requires it and pkijs omits it when the member is undefined.

      Parameters

      • commonName: string

        the subject CN

      Returns Promise<any>

      the PKCS#8 private key and the CSR, both DER

    • The next X509 response, or a refusal when the caller is entitled to nothing any more.

      Parameters

      • prepared: any

        the caller

      Returns Promise<any>

      the message and the lifetime

    • What the kernel says about the socket's peer, taken at accept. Never throws; a failure is facts.error and the socket is closed.

      Parameters

      • socket: any

        the accepted socket

      Returns any

      the facts

    • FetchJWTSVID.

      Parameters

      • call: any

        the gRPC call

      • callback: any

        grpc-js's callback

      Returns void

    • FetchJWTBundles. Stays open.

      Parameters

      • call: any

        the gRPC call

      Returns void

    • FetchX509SVID. The first message is written and the stream stays open.

      Parameters

      • call: any

        the gRPC call

      Returns void

    • FetchX509Bundles. Stays open. A caller entitled to no SVID still receives the bundles: the method is how a client validates.

      Parameters

      • call: any

        the gRPC call

      Returns void

    • FetchWITSVID and FetchWITBundles. Unimplemented, after the header.

      Parameters

      • call: any

        the gRPC call

      • method: string

        the method

      Returns void

    • ValidateJWTSVID.

      Parameters

      • call: any

        the gRPC call

      • callback: any

        grpc-js's callback

      Returns void

    • Opens the Server API clients with the agent SVID.

      Returns void

    • This trust domain's X.509 anchors, concatenated DER.

      Returns Promise<Buffer>

      the DER

    • The number in unix:attested-<n>, matched as a whole number. A prefix would take 1 out of unix:attested-10.

      Parameters

      • call: any

        the gRPC call

      Returns number

      the id, or null

    • The header, then the attested peer. The header wins, so a client that forgot it is told about the header.

      Parameters

      • call: any

        the gRPC call

      • method: string

        the method

      Returns any

      the caller, or a refusal

    • Whether the call carries workload.spiffe.io: true.

      Parameters

      • call: any

        the gRPC call

      Returns boolean

      whether it does

    • The selector texts for one connection's uid and gid.

      Parameters

      • facts: any

        the connection's facts

      Returns string[]

      the texts unix:uid:…

    • Writes the first bundle response and keeps the stream open.

      Parameters

      • call: any

        the gRPC call

      • open: any

        the stream's flag

      • kind: string

        x509 or jwt

      Returns Promise<void>

    • Writes the first X509 response and keeps the stream open.

      Parameters

      • call: any

        the gRPC call

      • open: any

        the stream's flag

      • prepared: any

        the caller

      Returns Promise<void>

    • The Server API address, without a scheme.

      Returns string

      host:port

    • Waits. One delay inside an attestation attempt, not a periodic timer.

      Parameters

      • ms: number

        the delay

      Returns Promise<void>

    • Attests, then serves. The native module is loaded before any socket exists. A failure throws an Error whose code is STS-SPIFFE-0148.

      Returns Promise<void>

    • A process's start time, field 22 of /proc/pid/stat, counted from the last ')' because the command may contain spaces.

      Parameters

      • pid: number

        the process id

      Returns string

      the start time, or ''

    • Whether these facts still name the process that connected. '' when they do. A peer that was never visible (another pid namespace) stays valid: its identity is the uid and gid, which do not change.

      Parameters

      • facts: any

        the connection's facts

      Returns string

      '' or why not

    • Closes the socket, the clients and every pidfd. Safe to call twice, and safe to call when start did not finish.

      Returns void

    • TLS credentials for the Server API. No client certificate until the agent has attested.

      Parameters

      • identity: any

        the agent key and certificate, or null

      Returns any

      the channel credentials

    • Takes the x509-svid x5c certificates out of a JWK Set.

      Parameters

      • text: string

        the document

      Returns string

      PEM anchors, or ''

    • Decodes a base64url segment, adding the padding the JWT omitted.

      Parameters

      • text: string

        the segment

      Returns Buffer

      the bytes

    • Concatenates certificates as PEM, leaf first.

      Parameters

      • ders: any

        the certificate DER fragments

      Returns string

      the PEM

    • Concatenates DER fragments, leaf first as the caller handed them.

      Parameters

      • parts: any

        the fragments

      Returns Buffer

      one buffer

    • Splits a compact JWS. The signing input is the two segments as they were sent, not a re-encoding of the JSON.

      Parameters

      • token: string

        the compact JWS

      Returns any

      the header, the payload and the signing input, or not ok

    • Installs node's Web Crypto as pkijs's engine when nothing has. A process that already installed one — the service, in the in-process test — is left alone: replacing the engine would change the service's signatures.

      Returns void

    • Reads one registration entry out of the Server API's message.

      Parameters

      • message: any

        the proto

      Returns any

      the entry

    • Builds an Error carrying an STS code. The code is for the operator; it is never put on the wire.

      Parameters

      • code: string

        the error code

      • message: string

        the sentence

      Returns any

      the error

    • Reads a boolean flag. Absent means on, which is the default for both checks.

      Parameters

      • value: any

        the text, or undefined

      Returns boolean

      the boolean

    • Reads a SPIFFE ID out of a SPIRE trust_domain and path.

      Parameters

      • message: any

        the proto

      Returns string

      the id, or ''

    • The JWT authorities of a bundle message, as JWKs with use and kid.

      Parameters

      • proto: any

        the bundle

      Returns any[]

      the JWKs

    • The process entry. Loads nothing of the service and binds nothing until start().

      Returns void

    • Looks up one name by id in a passwd- or group-style file.

      Parameters

      • file: string

        the file's path

      • id: string

        the numeric id

      Returns string

      the name, or ''

    • The sentence a caller entitled to nothing is answered with.

      Parameters

      • method: string

        the method

      • what: string

        what it is not entitled to

      Returns string

      the sentence

    • Parses a SPIFFE ID. Enough of the grammar that a caller cannot name an identity by a string that is not one; the server remains the authority for the ids it issues.

      Parameters

      • value: string

        the text

      Returns any

      { ok, id, trustDomain, path } or { ok: false, reason }

    • Wraps DER as a PEM block, 64 columns to a line.

      Parameters

      • der: Buffer

        the DER

      • label: string

        the PEM label

      Returns string

      the PEM

    • Reads argv. A --join-token flag is refused and its value is not repeated. The token comes from the environment or from a file.

      Parameters

      • argv: string[]

        the arguments after the program name

      Returns any

      { ok, message } or { ok, opts, readyFile }, where readyFile is --ready-file or empty

    • Builds a refusal a Workload API method answers with: a gRPC status and the STS code the log records.

      Parameters

      • code: string

        the error code

      • status: number

        the gRPC status

      • message: string

        the sentence the client sees

      Returns any

      the error

    • Removes the ready file, so an agent that has stopped does not still claim to serve.

      Parameters

      • file: string

        the path given as --ready-file, or empty

      Returns void

    • The unix selectors a caller of this uid and gid is seen as. The same set accept emits: uid, gid, and the names when the files have them.

      Parameters

      • uid: any

        the numeric uid

      • gid: any

        the numeric gid

      • Optionalopts: any

        passwdPath and groupPath, when not the system files

      Returns any[]

      the selectors, type unix

    • SPIRE's rule: every selector on the entry is present on the caller. An entry with none matches every caller.

      Parameters

      • entrySelectors: any

        the entry's selectors

      • callerSelectors: any

        the caller's selector texts

      Returns boolean

      whether the entry matches

    • The selectors as the admin API takes them, comma-separated.

      Parameters

      • uid: any

        the numeric uid

      • gid: any

        the numeric gid

      • Optionalopts: any

        passwdPath and groupPath, when not the system files

      Returns string

      the selector text

    • Verifies one JWS signature with node. ES uses IEEE-P1363, PS uses PSS, EdDSA uses the key's own algorithm.

      Parameters

      • alg: string

        the JWS alg

      • data: Buffer

        the signing input

      • sig: Buffer

        the signature

      • jwk: any

        the key, which may still carry use and kid

      Returns boolean

      whether it verified

    • Asks whether one batch item's status is OK. The loader stringifies enums and int64s, and this field is an int32, so 0, '0' and 'OK' are the same answer.

      Parameters

      • status: any

        the status message

      Returns boolean

      whether it is OK

    • Converts a plain object to a google.protobuf.Struct. The well-known type's fields are camelCase even when every other field is kept in the proto's spelling: stringValue, not string_value.

      Parameters

      • value: any

        the object

      Returns any

      the Struct

    • Converts one JSON value to a google.protobuf.Value.

      Parameters

      • value: any

        the value

      Returns any

      the Value

    • Verifies a decoded JWT-SVID: the signature, then the audience, then the expiry. A failure of any of the three is STS-SPIFFE-0037.

      Parameters

      • decoded: any

        the decoded token

      • audience: string

        the audience the caller claims

      • keys: any[]

        the JWKs that may have signed it

      Returns any

      the result

    • Writes the ready file: the agent's SPIFFE ID and a newline, once the socket serves. Written beside itself and renamed, so a reader never sees half an ID. A sidecar's workload waits for this file rather than for the socket, because the socket exists a moment before the agent is worth calling and the ID is what an entry is parented on.

      Parameters

      • file: string

        the path given as --ready-file

      • agentId: string

        the agent's SPIFFE ID

      Returns boolean

      whether the file was written

    • The X.509 anchors of a bundle message.

      Parameters

      • proto: any

        the bundle

      Returns Buffer

      concatenated DER