IF Commons GitHub

physical/signer

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-grc-evidence FR-005, 0006-grc-evidence FR-006, 0006-grc-evidence FR-007

The signer port and attestation (0006-grc-evidence): a signer signs and verifies a payload in an envelope and says how its keys are held; the evidence policy decides which custody is enough and which roles may attest. The port is structural: the envelope is { payloadType, payload (base64), signatures } and a key is whatever the signer takes, so that a signer of another kind (a file of allowed signers, a hardware token) plugs in without this layer knowing it.

Source: commons/grc/src/physical/signer.ts

5 of 20 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

physical.Envelopetypeno test imports it
type Envelope = {
  readonly payloadType: string;
  readonly payload: string;
  readonly signatures: readonly { readonly keyid?: string; readonly sig: string }[];
};

A signed payload.

physical.SignProblemtypeno test imports it
type SignProblem = { readonly kind: "key" | "signature" | "payload-type"; readonly message: string };

Why a signer did not sign or verify.

physical.Signertypeno test imports it
type Signer = { readonly id: string; /** How its keys are held. */ readonly custody: Custody; sign(payloadType: … (421 characters)
type Signer = {
  readonly id: string;
  /** How its keys are held. */
  readonly custody: Custody;
  sign(payloadType: string, payload: Uint8Array, keys: readonly unknown[]): Promise<Result<Envelope, SignProblem>>;
  /** The payload, where at least one of the keys (public) verifies a signature. */
  verify(envelope: Envelope, payloadType: string, keys: readonly unknown[]): Promise<Result<Uint8Array, SignProblem>>;
};

A signer.

physical.Signerstypeno test imports it
type Signers = Registry<Signer>;

A registry of signers.

physical.createSignersfunctionno test imports it
function createSigners(): Signers

A registry of signers, empty.

physical.signerAllowedfunctionno test imports it
function signerAllowed(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}, signer: Signer): boolean

Whether the signer's custody is at least what the policy needs (none < file < managed < hardware).

physical.mayAttestfunctionno test imports it
function mayAttest(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}, role: string): boolean

Whether a role may attest by the policy.

physical.AttestProblemtypeno test imports it
type AttestProblem = { readonly kind: "role" | "custody" | "signing"; readonly message: string };

Why an attestation was refused.

physical.AttestInputtypeno test imports it
type AttestInput = {
  readonly subject: string;
  readonly check: string;
  readonly claim: "pass" | "fail";
  readonly statement: string;
  readonly attester: string;
  readonly role: string;
  readonly evidence: readonly string[];
  readonly at: string;
};

What an attestation says.

physical.attestfunctionno test imports it
function attest(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Dec… (724 characters)
function attest(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}, signer: Signer | undefined, keys: readonly unknown[], input: AttestInput): Promise<Result<Document & { readonly subject: string; readonly check: string; readonly claim: "fail" | "pass"; readonly statement: string; readonly attester: string; readonly role: string; readonly evidence: readonly string[]; } & { readonly signature?: string | undefined; readonly signer?: string | undefined; }, AttestProblem>>

The attestation, signed by signer with keys where the policy needs a key (custody above none); refused, saying which of the two failed, where the role may not attest or the signer's custody is too weak.

Envelopetypeno test imports it
type Envelope = {
  readonly payloadType: string;
  readonly payload: string;
  readonly signatures: readonly { readonly keyid?: string; readonly sig: string }[];
};

A signed payload.

SignProblemtypeno test imports it
type SignProblem = { readonly kind: "key" | "signature" | "payload-type"; readonly message: string };

Why a signer did not sign or verify.

Signertype
type Signer = { readonly id: string; /** How its keys are held. */ readonly custody: Custody; sign(payloadType: … (421 characters)
type Signer = {
  readonly id: string;
  /** How its keys are held. */
  readonly custody: Custody;
  sign(payloadType: string, payload: Uint8Array, keys: readonly unknown[]): Promise<Result<Envelope, SignProblem>>;
  /** The payload, where at least one of the keys (public) verifies a signature. */
  verify(envelope: Envelope, payloadType: string, keys: readonly unknown[]): Promise<Result<Uint8Array, SignProblem>>;
};

A signer.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

Signerstypeno test imports it
type Signers = Registry<Signer>;

A registry of signers.

createSignersfunction
function createSigners(): Signers

A registry of signers, empty.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

signerAllowedfunction
function signerAllowed(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}, signer: Signer): boolean

Whether the signer's custody is at least what the policy needs (none < file < managed < hardware).

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

mayAttestfunction
function mayAttest(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}, role: string): boolean

Whether a role may attest by the policy.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

AttestProblemtypeno test imports it
type AttestProblem = { readonly kind: "role" | "custody" | "signing"; readonly message: string };

Why an attestation was refused.

AttestInputtypeno test imports it
type AttestInput = {
  readonly subject: string;
  readonly check: string;
  readonly claim: "pass" | "fail";
  readonly statement: string;
  readonly attester: string;
  readonly role: string;
  readonly evidence: readonly string[];
  readonly at: string;
};

What an attestation says.

attestfunction
function attest(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Dec… (724 characters)
function attest(policy: Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}, signer: Signer | undefined, keys: readonly unknown[], input: AttestInput): Promise<Result<Document & { readonly subject: string; readonly check: string; readonly claim: "fail" | "pass"; readonly statement: string; readonly attester: string; readonly role: string; readonly evidence: readonly string[]; } & { readonly signature?: string | undefined; readonly signer?: string | undefined; }, AttestProblem>>

The attestation, signed by signer with keys where the policy needs a key (custody above none); refused, saying which of the two failed, where the role may not attest or the signer's custody is too weak.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.