IF Commons GitHub

dsse

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-crypto FR-006

in-toto Statements v1 and DSSE envelopes (commons 0001-crypto FR-006): a statement says that a predicate of some type holds of its subjects, each named and identified by its digests; DSSE signs a payload of a stated type, by the pre-authentication encoding (PAE) of the two, and carries it in a JSON envelope with its signatures. Signing and verifying use Web Crypto (crypto.subtle) on keys the caller has imported as CryptoKeys, so the module has no effect beyond the computation: Ed25519, ECDSA on P-256, P-384 and P-521 (with SHA-256, SHA-384 and SHA-512, the signature in ASN.1 DER as sigstore and in-toto's own tools write it), and RSA-PSS and RSASSA-PKCS1-v1_5 with the key's hash. Verification returns the payload, or an error that says why it was refused: an envelope that is malformed, a payload type not the one expected, a key not usable, or too few valid signatures.

Taken from Stolos's src/archon/export/intoto.ts, which built a statement and an envelope for a signature callback but never verified one. What changed: the statement is generic in its predicate; the subject's digest is any map of algorithms; signing takes keys rather than a callback; verification, the envelope's decoder and the ECDSA signature form are new. Stolos's evidence bundle predicate (its predicate type, the manifest's summary and the subject list of a bundle's items) is Stolos's own domain and stays there.

import { pae, signStatement, statement, subject, verifyStatement } from "./dsse.ts";
import { unknownValue } from "@intellectual-frontiers/core";
new TextDecoder().decode(pae("http://example.com/HelloWorld", new TextEncoder().encode("hello world")));
// "DSSEv1 29 http://example.com/HelloWorld 11 hello world"
const keys = await crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]);
const s = statement([await subject("a.txt", new TextEncoder().encode("a"))], "https://example.com/Note/v1", { note: "hi" });
const signed = await signStatement(s, [{ key: keys.privateKey, keyid: "me" }]);
if (signed.kind === "ok") await verifyStatement(signed.value, [{ key: keys.publicKey, keyid: "me" }], unknownValue); // { kind: "ok", ... }

Source: commons/crypto/src/dsse.ts

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

dssenamespace
namespace dsse
dsse.STATEMENT_TYPEconstno test imports it
const STATEMENT_TYPE: "https://in-toto.io/Statement/v1"

The _type of an in-toto Statement v1.

dsse.INTOTO_PAYLOAD_TYPEconstno test imports it
const INTOTO_PAYLOAD_TYPE: "application/vnd.in-toto+json"

The DSSE payload type of an in-toto statement.

dsse.ResourceDescriptortypeno test imports it
type ResourceDescriptor = {
  readonly name: string;
  readonly digest: Readonly<Record<string, string>>;
  readonly uri?: string;
  readonly mediaType?: string;
  readonly annotations?: Readonly<Record<string, unknown>>;
};

An in-toto ResourceDescriptor as a statement's subject: its name, its digests by algorithm (sha256, ...) in lower-case hexadecimal, and what else is known of it.

dsse.Statementtypeno test imports it
type Statement<P> = {
  readonly _type: typeof STATEMENT_TYPE;
  readonly subject: readonly ResourceDescriptor[];
  readonly predicateType: string;
  readonly predicate: P;
};

An in-toto Statement v1: a predicate of type predicateType that holds of the subjects.

dsse.DsseEnvelopetypeno test imports it
type DsseEnvelope = {
  readonly payload: string;
  readonly payloadType: string;
  readonly signatures: readonly { readonly keyid?: string; readonly sig: string }[];
};

A DSSE envelope: the payload in base64, its type, and the signatures (base64) over PAE(payloadType, payload).

dsse.DsseKeytypeno test imports it
type DsseKey = { readonly key: CryptoKey; readonly keyid?: string };

A key to sign with (a private key) or verify with (a public key), and the id that names it in an envelope, if any.

dsse.DsseAlgorithmtypeno test imports it
type DsseAlgorithm =
  | { readonly kind: "ed25519" }
  | { readonly kind: "ecdsa"; readonly curve: "P-256" | "P-384" | "P-521" }
  | { readonly kind: "rsa-pss"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" }
  | { readonly kind: "rsassa-pkcs1-v1_5"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" };

A signature algorithm this module signs and verifies with, as read from a key.

dsse.DsseKeyErrortypeno test imports it
type DsseKeyError = { readonly kind: "key"; readonly index: number; readonly reason: string };

Why a key cannot sign or verify: its place in the list given, and the reason.

dsse.DsseErrortypeno test imports it
type DsseError =
  | { readonly kind: "malformed"; readonly reason: string }
  | { readonly kind: "payload-type"; readonly expected: string; readonly found: string }
  | DsseKeyError
  | { readonly kind: "no-valid-signature"; readonly signatures: number; readonly verified: number; readonly threshold: number };

Why an envelope was refused.

dsse.StatementErrortypeno test imports it
type StatementError = DsseError | { readonly kind: "statement"; readonly error: DecodeError };

Why a signed statement was refused: the envelope's error, or a payload that is not an in-toto statement with the predicate expected.

dsse.Verifiedtypeno test imports it
type Verified = { readonly payloadType: string; readonly payload: Uint8Array; readonly keys: readonly DsseKey[] };

What a verified envelope carries: its payload type, its payload, and the keys that verified a signature.

dsse.subjectfunctionno test imports it
function subject(name: string, bytes: Uint8Array<ArrayBufferLike>, more?: { readonly uri?: string | undefined; readonly mediaType?: string | undefined; readonly annotations?: Readonly<Record<string, unknown>> | undefined; }): Promise<ResourceDescriptor>

A subject: the name, and the SHA-256 of the bytes; more adds a URI, a media type or annotations.

dsse.statementfunctionno test imports it
function statement<P>(subjects: readonly ResourceDescriptor[], predicateType: string, predicate: P): Statement<P>

A statement of the predicate about the subjects.

dsse.resourceDescriptorDecoderconstno test imports it
const resourceDescriptorDecoder: Decoder<ResourceDescriptor>

The decoder of a ResourceDescriptor with a name and digests.

dsse.statementDecoderfunctionno test imports it
function statementDecoder<P>(predicate: Decoder<P>): Decoder<Statement<P>>

The decoder of an in-toto Statement v1 whose predicate predicate decodes.

dsse.envelopeDecoderconstno test imports it
const envelopeDecoder: Decoder<DsseEnvelope>

The decoder of a DSSE envelope: its fields present, and the payload and signatures in base64.

dsse.parseEnvelopefunctionno test imports it
function parseEnvelope(text: string): Result<DsseEnvelope, DsseError>

A DSSE envelope read from JSON text, or why it is not one.

dsse.paefunctionno test imports it
function pae(payloadType: string, payload: Uint8Array<ArrayBufferLike>): Uint8Array<ArrayBuffer>

DSSE's pre-authentication encoding: DSSEv1 <len(type)> <type> <len(payload)> <payload>, the lengths in bytes as ASCII decimal.

dsse.signatureAlgorithmfunctionno test imports it
function signatureAlgorithm(key: CryptoKey): Result<DsseAlgorithm, string>

The signature algorithm of a key, or the reason it is not one this module uses.

dsse.signEnvelopefunctionno test imports it
function signEnvelope(payloadType: string, payload: Uint8Array<ArrayBufferLike>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>

The payload of the type signed by every key given (private keys), in an envelope; or the first key that cannot sign.

dsse.verifyEnvelopefunctionno test imports it
function verifyEnvelope(envelope: DsseEnvelope, payloadType: string, keys: readonly DsseKey[], threshold?: number): Promise<Result<Verified, DsseError>>

The payload of an envelope whose type is payloadType and which at least threshold of the keys given (public keys, 1 by default) each verify a signature of. A signature that names a key id is tried only with the keys of that id or of none.

dsse.signStatementfunctionno test imports it
function signStatement<P>(s: Statement<P>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>

A statement as JSON, signed by every key given, in an envelope of type application/vnd.in-toto+json.

dsse.verifyStatementfunctionno test imports it
function verifyStatement<P>(envelope: DsseEnvelope, keys: readonly DsseKey[], predicate: Decoder<P>, threshold?: number): Promise<Result<Statement<P>, StatementError>>

The statement an envelope of type application/vnd.in-toto+json carries, verified as verifyEnvelope does, its predicate decoded by predicate.

STATEMENT_TYPEconst
const STATEMENT_TYPE: "https://in-toto.io/Statement/v1"

The _type of an in-toto Statement v1.

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

INTOTO_PAYLOAD_TYPEconst
const INTOTO_PAYLOAD_TYPE: "application/vnd.in-toto+json"

The DSSE payload type of an in-toto statement.

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

ResourceDescriptortypeno test imports it
type ResourceDescriptor = {
  readonly name: string;
  readonly digest: Readonly<Record<string, string>>;
  readonly uri?: string;
  readonly mediaType?: string;
  readonly annotations?: Readonly<Record<string, unknown>>;
};

An in-toto ResourceDescriptor as a statement's subject: its name, its digests by algorithm (sha256, ...) in lower-case hexadecimal, and what else is known of it.

Statementtypeno test imports it
type Statement<P> = {
  readonly _type: typeof STATEMENT_TYPE;
  readonly subject: readonly ResourceDescriptor[];
  readonly predicateType: string;
  readonly predicate: P;
};

An in-toto Statement v1: a predicate of type predicateType that holds of the subjects.

DsseEnvelopetype
type DsseEnvelope = {
  readonly payload: string;
  readonly payloadType: string;
  readonly signatures: readonly { readonly keyid?: string; readonly sig: string }[];
};

A DSSE envelope: the payload in base64, its type, and the signatures (base64) over PAE(payloadType, payload).

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

DsseKeytype
type DsseKey = { readonly key: CryptoKey; readonly keyid?: string };

A key to sign with (a private key) or verify with (a public key), and the id that names it in an envelope, if any.

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

DsseAlgorithmtypeno test imports it
type DsseAlgorithm =
  | { readonly kind: "ed25519" }
  | { readonly kind: "ecdsa"; readonly curve: "P-256" | "P-384" | "P-521" }
  | { readonly kind: "rsa-pss"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" }
  | { readonly kind: "rsassa-pkcs1-v1_5"; readonly hash: "SHA-256" | "SHA-384" | "SHA-512" };

A signature algorithm this module signs and verifies with, as read from a key.

DsseKeyErrortypeno test imports it
type DsseKeyError = { readonly kind: "key"; readonly index: number; readonly reason: string };

Why a key cannot sign or verify: its place in the list given, and the reason.

DsseErrortypeno test imports it
type DsseError =
  | { readonly kind: "malformed"; readonly reason: string }
  | { readonly kind: "payload-type"; readonly expected: string; readonly found: string }
  | DsseKeyError
  | { readonly kind: "no-valid-signature"; readonly signatures: number; readonly verified: number; readonly threshold: number };

Why an envelope was refused.

StatementErrortypeno test imports it
type StatementError = DsseError | { readonly kind: "statement"; readonly error: DecodeError };

Why a signed statement was refused: the envelope's error, or a payload that is not an in-toto statement with the predicate expected.

Verifiedtypeno test imports it
type Verified = { readonly payloadType: string; readonly payload: Uint8Array; readonly keys: readonly DsseKey[] };

What a verified envelope carries: its payload type, its payload, and the keys that verified a signature.

subjectfunction
function subject(name: string, bytes: Uint8Array<ArrayBufferLike>, more?: { readonly uri?: string | undefined; readonly mediaType?: string | undefined; readonly annotations?: Readonly<Record<string, unknown>> | undefined; }): Promise<ResourceDescriptor>

A subject: the name, and the SHA-256 of the bytes; more adds a URI, a media type or annotations.

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

statementfunction
function statement<P>(subjects: readonly ResourceDescriptor[], predicateType: string, predicate: P): Statement<P>

A statement of the predicate about the subjects.

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

resourceDescriptorDecoderconstno test imports it
const resourceDescriptorDecoder: Decoder<ResourceDescriptor>

The decoder of a ResourceDescriptor with a name and digests.

statementDecoderfunction
function statementDecoder<P>(predicate: Decoder<P>): Decoder<Statement<P>>

The decoder of an in-toto Statement v1 whose predicate predicate decodes.

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

envelopeDecoderconst
const envelopeDecoder: Decoder<DsseEnvelope>

The decoder of a DSSE envelope: its fields present, and the payload and signatures in base64.

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

parseEnvelopefunction
function parseEnvelope(text: string): Result<DsseEnvelope, DsseError>

A DSSE envelope read from JSON text, or why it is not one.

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

paefunction
function pae(payloadType: string, payload: Uint8Array<ArrayBufferLike>): Uint8Array<ArrayBuffer>

DSSE's pre-authentication encoding: DSSEv1 <len(type)> <type> <len(payload)> <payload>, the lengths in bytes as ASCII decimal.

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

signatureAlgorithmfunction
function signatureAlgorithm(key: CryptoKey): Result<DsseAlgorithm, string>

The signature algorithm of a key, or the reason it is not one this module uses.

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

signEnvelopefunction
function signEnvelope(payloadType: string, payload: Uint8Array<ArrayBufferLike>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>

The payload of the type signed by every key given (private keys), in an envelope; or the first key that cannot sign.

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

verifyEnvelopefunction
function verifyEnvelope(envelope: DsseEnvelope, payloadType: string, keys: readonly DsseKey[], threshold?: number): Promise<Result<Verified, DsseError>>

The payload of an envelope whose type is payloadType and which at least threshold of the keys given (public keys, 1 by default) each verify a signature of. A signature that names a key id is tried only with the keys of that id or of none.

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

signStatementfunction
function signStatement<P>(s: Statement<P>, keys: readonly DsseKey[]): Promise<Result<DsseEnvelope, DsseKeyError>>

A statement as JSON, signed by every key given, in an envelope of type application/vnd.in-toto+json.

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

verifyStatementfunction
function verifyStatement<P>(envelope: DsseEnvelope, keys: readonly DsseKey[], predicate: Decoder<P>, threshold?: number): Promise<Result<Statement<P>, StatementError>>

The statement an envelope of type application/vnd.in-toto+json carries, verified as verifyEnvelope does, its predicate decoded by predicate.

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

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