IF Commons GitHub

merge/signing

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0010-anyfs-merge-signing FR-001, 0010-anyfs-merge-signing FR-002, 0010-anyfs-merge-signing FR-003, 0010-anyfs-merge-signing FR-004, 0010-anyfs-merge-signing FR-005, 0010-anyfs-merge-signing FR-006

The signature of what replicas exchange: a delta, an epoch and a dump are each named by a digest, and a replica that signs says in its own key that it made what the digest names. The key is Ed25519 (the algorithm of the keys the commons already signs with, and the one both runtimes hold); a signature is the text ed25519:<key id>:<base64>, where the key id is the first 16 hexadecimal digits of the SHA-256 of the 32 bytes of the public key; and what is signed is the digest with the domain it is for and the replica that made it (anyfs-delta/1, anyfs-epoch/1, anyfs-dump/1), so that a signature of one thing is never a signature of another. A roster says which keys speak for which replica and when: each entry has a window (not before, not after, in milliseconds), so that a key can be replaced and a delta signed under the old key still holds for the time it was made in.

import { generateSigningKey, makeSigner, rosterTrust, signDelta } from "./signing.ts";
const key = await generateSigningKey(replica);
const signed = await signDelta(delta, await makeSigner(key));
const trust = rosterTrust([key.entry]);

Source: commons/anyfs/src/merge/signing.ts

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

SIGNED_DOMAINSconstno test imports it
const SIGNED_DOMAINS: readonly ["anyfs-delta/1", "anyfs-epoch/1", "anyfs-dump/1"]

What a signature is for: the domain written before the digest.

SignedDomaintypeno test imports it
type SignedDomain = (typeof SIGNED_DOMAINS)[number];

One domain of a signature.

SIGNATURE_ALGORITHMconstno test imports it
const SIGNATURE_ALGORITHM: "ed25519"

The prefix of a signature's text.

KeyEntrytypeno test imports it
type KeyEntry = {
  readonly replica: ReplicaId;
  readonly keyId: string;
  readonly publicKey: string;
  readonly notBefore?: number;
  readonly notAfter?: number;
};

One key that speaks for a replica, and when: the 32 bytes of the public key in base64, with the window in milliseconds it speaks in.

KeyRostertypeno test imports it
type KeyRoster = readonly KeyEntry[];

The keys a replica knows.

Signertypeno test imports it
type Signer = {
  readonly replica: ReplicaId;
  readonly keyId: string;
  sign(domain: SignedDomain, text: string): Promise<string>;
};

Whoever signs: the replica and key they speak with, and the signing of a text.

PrivateJwktypeno test imports it
type PrivateJwk = {
  readonly kty?: string;
  readonly crv?: string;
  readonly x?: string;
  readonly d?: string;
  readonly ext?: boolean;
  readonly key_ops?: string[];
};

The private key of a replica as a JSON Web Key (RFC 8037, Ed25519): declared here, so that no consumer needs the dom library for a type of it.

SigningKeytypeno test imports it
type SigningKey = { readonly privateJwk: PrivateJwk; readonly entry: KeyEntry };

A key pair made for a replica: the private key as a JWK (to be kept as a secret), the roster entry to give to others, and the signer.

keyIdOffunction
function keyIdOf(publicRaw: Uint8Array<ArrayBufferLike>): Promise<string>

The id of a key: the first 16 hexadecimal digits of the SHA-256 of its 32 bytes.

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

generateSigningKeyfunction
function generateSigningKey(replica: ReplicaId, window?: { readonly notBefore?: number | undefined; readonly notAfter?: number | undefined; }): Promise<SigningKey>

A new key pair for a replica.

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

messageOfconst
const messageOf: (domain: "anyfs-delta/1" | "anyfs-dump/1" | "anyfs-epoch/1", replica: ReplicaId, digest: string) => string

The message that is signed: the domain, the replica that made the thing, and its digest, each on a line.

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

makeSignerfunction
function makeSigner(key: SigningKey): Promise<Signer>

A signer from a private key (a JWK) and the entry it belongs to.

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

signDeltafunctionno test imports it
function signDelta(delta: Delta, signer: Signer): Promise<Delta>

A delta with the signature of the replica that made it: the signature is over the identity of the delta, which is made without it.

parseSignaturefunction
function parseSignature(signature: string): Result<{ readonly keyId: string; readonly bytes: Uint8Array<ArrayBufferLike>; }, string>

The parts of a signature's text, or why it is not one.

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

verifySignedfunction
function verifySigned(roster: KeyRoster, domain: "anyfs-delta/1" | "anyfs-dump/1" | "anyfs-epoch/1", digest: string, signature: string, replica: ReplicaId, at: number): Promise<"bad-signature" | "ok" | "unknown-key">

Whether a signature holds for a thing a replica made at a time: the verdict, and the reason where it is not ok.

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

rosterTrustfunction
function rosterTrust(roster: KeyRoster, replicas?: ReadonlySet<ReplicaId> | undefined): Trust

The trust that takes deltas signed by a key of the roster, from the replicas the roster names alone unless replicas narrows them (a replica must be on both).

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

parseRosterfunction
function parseRoster(source: string): Result<KeyRoster, string>

A roster read from text: a JSON list of entries, each checked, or why the text is not a roster.

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

rosterTextconst
const rosterText: (roster: KeyRoster) => string

The text of a roster: what parseRoster reads.

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

signingKeyTextconst
const signingKeyText: (key: SigningKey) => string

A signing key as it is kept in a file: the replica it speaks for, the roster entry others add to their roster, and the private key. The file is a secret and is never written to a command line.

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

parseSigningKeyfunction
function parseSigningKey(source: string): Result<SigningKey, string>

A signing key read from a file's text, or why the text is not one.

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

signDeltaByfunctionno test imports it
function signDeltaBy(delta: Delta, signers: readonly Signer[]): Promise<Delta>

A delta signed by the signer of its origin among several, as it is signed where more than one replica's key is in hand; a delta whose origin has no signer here is returned as it is, unsigned.

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