@push.rocks/smartlinuxrepo 1.0.0 → 1.1.1

package/ts/signing/verifiers.ts

@@ -0,0 +1,357 @@
+import * as plugins from '../plugins.js';
+import { LinuxRepoError } from '../shared/errors.js';
+import { assertBytes, assertString, assertTimestamp } from '../shared/validation.js';
+import {
+  dearmor,
+  decodeArmorBytes,
+  readPacketTags,
+  splitCleartextSignedMessage,
+  type IFramingFailure,
+} from './openpgpframing.js';
+
+/** The hash algorithms the verifier accepts. */
+export type TOpenPgpHashAlgorithm = 'sha256' | 'sha384' | 'sha512';
+
+/** A signature that verified. */
+export interface IOpenPgpSignatureVerification {
+  /** The primary key or subkey that verified the signature, 40 uppercase hex digits. */
+  readonly signingKeyFingerprint: string;
+  /** The signature's creation time (whole seconds). */
+  readonly created: Date;
+  readonly hashAlgorithm: TOpenPgpHashAlgorithm;
+}
+
+/** A cleartext-signed message that verified. */
+export interface IOpenPgpCleartextVerification extends IOpenPgpSignatureVerification {
+  /**
+   * The signed text: dash-escaping removed, lines joined by LF, without the
+   * line break before the signature block (RFC 9580 section 7.1). For
+   * GnuPG's and the codec's `InRelease` this is `Release` without its final
+   * line break; for Gitea 28.2.0's (go-crypto) it is the whole `Release`.
+   */
+  readonly signedText: string;
+}
+
+/**
+ * Verifies OpenPGP signatures against one public key. Every method fails
+ * closed with a `LinuxRepoError` and never returns a verdict of failure:
+ * `malformed-signature`, `wrong-key`, `unusable-key` or `bad-signature`
+ * (bad arguments are `invalid-input`).
+ *
+ * A signature is valid when it is exactly one OpenPGP v4 signature packet,
+ * SHA-256, SHA-384 or SHA-512, issued by the primary key or one of its
+ * subkeys, created at or before `date` and not expired at `date`, made by a
+ * key or subkey that can sign both at the signature's creation time and at
+ * `date` (not expired, not revoked, sign flag set, valid binding and
+ * back-signature, openpgp.js's algorithm floor), and when it verifies
+ * cryptographically. `date` is required; the codec reads no clock.
+ */
+export interface IOpenPgpVerifier {
+  /** The primary key's v4 fingerprint, 40 uppercase hex digits (as `IOpenPgpKeyPair.fingerprint`). */
+  readonly fingerprint: string;
+  /**
+   * A binary detached signature of type 0x00 over `data`: the packet
+   * `IOpenPgpSigner.signBinary` returns, an Arch `.sig`.
+   */
+  verifyDetachedSignature(inputArg: { data: Uint8Array; signature: Uint8Array; date: Date }): Promise<IOpenPgpSignatureVerification>;
+  /**
+   * An armored detached signature of type 0x00 over `data`: `Release.gpg`,
+   * `repomd.xml.asc`. The armor is ASCII.
+   */
+  verifyArmoredDetachedSignature(inputArg: {
+    data: Uint8Array;
+    signatureArmored: Uint8Array;
+    date: Date;
+  }): Promise<IOpenPgpSignatureVerification>;
+  /**
+   * A cleartext-signed message with a signature of type 0x01: `InRelease`.
+   * The message is strict UTF-8 with LF line endings; see
+   * `splitCleartextSignedMessage` for what its framing may hold.
+   */
+  verifyCleartextMessage(inputArg: { message: Uint8Array; date: Date }): Promise<IOpenPgpCleartextVerification>;
+}
+
+const HASH_ALGORITHMS: ReadonlyMap<number, TOpenPgpHashAlgorithm> = new Map([
+  [plugins.openpgp.enums.hash.sha256, 'sha256'],
+  [plugins.openpgp.enums.hash.sha384, 'sha384'],
+  [plugins.openpgp.enums.hash.sha512, 'sha512'],
+]);
+
+/** Subpacket types openpgp.js reads in the unhashed area (issuer, embedded signature, issuer fingerprint). */
+const UNHASHED_SUBPACKETS_READ = new Set([16, 32, 33]);
+
+/**
+ * The openpgp.js settings verification depends on, pinned instead of taken
+ * from the process-wide `openpgp.config`. The values are openpgp.js 6.3.2's
+ * defaults except `ignoreUnsupportedPackets`.
+ */
+const VERIFY_CONFIG: plugins.openpgp.Config = {
+  ...plugins.openpgp.config,
+  ignoreUnsupportedPackets: false,
+  ignoreMalformedPackets: false,
+  enableParsingV5Entities: false,
+  additionalAllowedPackets: [],
+  allowMissingKeyFlags: false,
+  allowInsecureVerificationWithReformattedKeys: false,
+  minRSABits: 2047,
+  knownNotations: [],
+  rejectHashAlgorithms: new Set([plugins.openpgp.enums.hash.md5, plugins.openpgp.enums.hash.ripemd]),
+  rejectMessageHashAlgorithms: new Set([
+    plugins.openpgp.enums.hash.md5,
+    plugins.openpgp.enums.hash.ripemd,
+    plugins.openpgp.enums.hash.sha1,
+  ]),
+  rejectPublicKeyAlgorithms: new Set([plugins.openpgp.enums.publicKey.elgamal, plugins.openpgp.enums.publicKey.dsa]),
+  rejectCurves: new Set([plugins.openpgp.enums.curve.secp256k1]),
+};
+
+/**
+ * Builds a verifier from one armored OpenPGP public key: exactly one
+ * transferable v4 public key (the primary key with its user IDs, subkeys and
+ * self-signatures, all v4) in exactly one `PUBLIC KEY BLOCK`. A private key
+ * block, several blocks or keys, a v6 key, text around the block, an armor
+ * CRC-24 that does not match or any other garbage is `invalid-key`
+ * (`detail.field` `publicKeyArmored`). Only the structure is checked here;
+ * whether a key can sign depends on time and is checked at verification.
+ */
+export async function createOpenPgpVerifier(inputArg: { publicKeyArmored: string }): Promise<IOpenPgpVerifier> {
+  if (inputArg === null || typeof inputArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+  assertString(inputArg.publicKeyArmored, 'publicKeyArmored');
+  const keyBytes = dearmor(inputArg.publicKeyArmored, 'PUBLIC KEY BLOCK', { code: 'invalid-key', field: 'publicKeyArmored' });
+  let keys: plugins.openpgp.Key[];
+  try {
+    keys = await plugins.openpgp.readKeys({ binaryKeys: keyBytes, config: VERIFY_CONFIG });
+  } catch (error) {
+    throw new LinuxRepoError('invalid-key', 'the OpenPGP public key cannot be read', { field: 'publicKeyArmored' }, {
+      cause: error,
+    });
+  }
+  if (keys.length !== 1) {
+    throw new LinuxRepoError('invalid-key', `expected exactly one OpenPGP public key, got ${keys.length}`, {
+      field: 'publicKeyArmored',
+    });
+  }
+  const key = keys[0];
+  if (key.isPrivate()) {
+    throw new LinuxRepoError('invalid-key', 'a private key is not accepted as the verification key', {
+      field: 'publicKeyArmored',
+    });
+  }
+  if (key.keyPacket.version !== 4 || key.subkeys.some((subkey) => subkey.keyPacket.version !== 4)) {
+    throw new LinuxRepoError('invalid-key', 'only OpenPGP v4 keys and subkeys are accepted', { field: 'publicKeyArmored' });
+  }
+  const publicKey: plugins.openpgp.PublicKey = key;
+  return {
+    fingerprint: publicKey.getFingerprint().toUpperCase(),
+    verifyDetachedSignature: async (input) => {
+      assertInputObject(input);
+      assertBytes(input.data, 'data');
+      assertBytes(input.signature, 'signature');
+      assertTimestamp(input.date, 'date');
+      return verifySignature({
+        key: publicKey,
+        packets: input.signature,
+        content: { binary: input.data },
+        signatureType: plugins.openpgp.enums.signature.binary,
+        date: input.date,
+        field: 'signature',
+        headerHashAlgorithms: [],
+      });
+    },
+    verifyArmoredDetachedSignature: async (input) => {
+      assertInputObject(input);
+      assertBytes(input.data, 'data');
+      assertBytes(input.signatureArmored, 'signatureArmored');
+      assertTimestamp(input.date, 'date');
+      const failure: IFramingFailure = { code: 'malformed-signature', field: 'signatureArmored' };
+      return verifySignature({
+        key: publicKey,
+        packets: dearmor(decodeArmorBytes(input.signatureArmored, failure), 'SIGNATURE', failure),
+        content: { binary: input.data },
+        signatureType: plugins.openpgp.enums.signature.binary,
+        date: input.date,
+        field: 'signatureArmored',
+        headerHashAlgorithms: [],
+      });
+    },
+    verifyCleartextMessage: async (input) => {
+      assertInputObject(input);
+      assertBytes(input.message, 'message');
+      assertTimestamp(input.date, 'date');
+      const parts = splitCleartextSignedMessage(input.message, { code: 'malformed-signature', field: 'message' });
+      const verification = await verifySignature({
+        key: publicKey,
+        packets: parts.signature,
+        // a text signature hashes the text with CRLF line endings; the split refused trailing whitespace,
+        // so this equals the cleartext digest of RFC 9580 section 7.1
+        content: { text: parts.signedText },
+        signatureType: plugins.openpgp.enums.signature.text,
+        date: input.date,
+        field: 'message',
+        headerHashAlgorithms: parts.headerHashAlgorithms,
+      });
+      return { ...verification, signedText: parts.signedText };
+    },
+  };
+}
+
+function hexByte(valueArg: number | null): string {
+  return valueArg === null ? 'none' : `0x${valueArg.toString(16).padStart(2, '0')}`;
+}
+
+function assertInputObject(inputArg: unknown): void {
+  if (inputArg === null || typeof inputArg !== 'object') {
+    throw new LinuxRepoError('invalid-input', 'input must be an object', { field: 'input' });
+  }
+}
+
+/**
+ * The verification steps, each with its own error code: structure
+ * (`malformed-signature`), issuer (`wrong-key`), the signature's own time
+ * rules (`bad-signature`), the issuing key's ability to sign at creation and
+ * at `date` (`unusable-key`), then the cryptographic check (`bad-signature`).
+ */
+async function verifySignature(inputArg: {
+  key: plugins.openpgp.PublicKey;
+  packets: Uint8Array;
+  /** The signed document: bytes for a binary signature, text for a text signature. */
+  content: { binary: Uint8Array } | { text: string };
+  signatureType: plugins.openpgp.enums.signature;
+  date: Date;
+  field: string;
+  headerHashAlgorithms: number[];
+}): Promise<IOpenPgpSignatureVerification> {
+  const { key, date, field } = inputArg;
+  const malformed = (messageArg: string, causeArg?: unknown) =>
+    new LinuxRepoError('malformed-signature', messageArg, { field }, causeArg === undefined ? undefined : { cause: causeArg });
+
+  // 1. structure, before any cryptography
+  const tags = readPacketTags(inputArg.packets, { code: 'malformed-signature', field });
+  if (tags.length !== 1 || tags[0] !== plugins.openpgp.enums.packet.signature) {
+    throw malformed(`expected exactly one signature packet, got packet tags [${tags.join(', ')}]`);
+  }
+  let signature: plugins.openpgp.Signature;
+  try {
+    signature = await plugins.openpgp.readSignature({ binarySignature: inputArg.packets, config: VERIFY_CONFIG });
+  } catch (error) {
+    throw malformed('the signature packet cannot be read', error);
+  }
+  const packet = signature.packets[0];
+  if (signature.packets.length !== 1 || !(packet instanceof plugins.openpgp.SignaturePacket)) {
+    throw malformed('expected exactly one signature packet');
+  }
+  if (packet.version !== 4) {
+    throw malformed(`only v4 signatures are accepted, got v${packet.version}`);
+  }
+  if (packet.signatureType !== inputArg.signatureType) {
+    throw malformed(`expected signature type ${hexByte(inputArg.signatureType)}, got ${hexByte(packet.signatureType)}`);
+  }
+  const hashId = packet.hashAlgorithm;
+  const hashAlgorithm = hashId === null ? undefined : HASH_ALGORITHMS.get(hashId);
+  if (hashId === null || hashAlgorithm === undefined) {
+    throw malformed(`hash algorithm ${hashId} is not SHA-256, SHA-384 or SHA-512`);
+  }
+  if (inputArg.headerHashAlgorithms.length > 0 && !inputArg.headerHashAlgorithms.includes(hashId)) {
+    throw malformed('the Hash: header does not name the signature hash algorithm');
+  }
+  if (packet.created === null) {
+    throw malformed('the signature has no creation time');
+  }
+  const issuerKeyId = packet.issuerKeyID.toHex();
+  if (!/^[0-9a-f]{16}$/.test(issuerKeyId) || /^0+$/.test(issuerKeyId)) {
+    throw malformed('the signature names no issuer, or the wildcard issuer');
+  }
+  if (packet.unknownSubpackets.some((subpacket) => subpacket.critical)) {
+    throw malformed('the signature has an unknown critical subpacket');
+  }
+  if (packet.unhashedSubpackets.some((subpacket) => subpacket.critical && !UNHASHED_SUBPACKETS_READ.has(subpacket.type))) {
+    throw malformed('the signature has a critical unhashed subpacket the verifier does not read');
+  }
+  if (packet.rawNotations.some((notation) => notation.critical)) {
+    throw malformed('the signature has a critical notation');
+  }
+
+  // 2. issuer: the primary key or one of its subkeys, by key ID and, when present, by fingerprint
+  const issuerFingerprint = packet.issuerFingerprint === null ? null : Buffer.from(packet.issuerFingerprint).toString('hex');
+  const issuers = [key, ...key.subkeys].filter(
+    (candidate) =>
+      candidate.getKeyID().equals(packet.issuerKeyID) && (issuerFingerprint === null || candidate.getFingerprint() === issuerFingerprint),
+  );
+  if (issuers.length === 0) {
+    throw new LinuxRepoError('wrong-key', 'the signature was not issued by this key or one of its subkeys', {
+      field,
+      value: (issuerFingerprint ?? issuerKeyId).toUpperCase(),
+    });
+  }
+
+  // 3. the signature's own time rules
+  if (packet.isExpired(date)) {
+    const reason = packet.created.getTime() > date.getTime() ? 'was created after the verification date' : 'has expired at the verification date';
+    throw new LinuxRepoError('bad-signature', `the signature ${reason}`, { field });
+  }
+
+  // 4. the issuing key or subkey must be able to sign at the creation time and at `date`
+  const signingKeyAt = async (whenArg: Date): Promise<plugins.openpgp.PublicKey | plugins.openpgp.Subkey> => {
+    let signingKey: plugins.openpgp.PublicKey | plugins.openpgp.Subkey;
+    try {
+      signingKey = await key.getSigningKey(packet.issuerKeyID, whenArg, undefined, VERIFY_CONFIG);
+    } catch (error) {
+      throw new LinuxRepoError(
+        'unusable-key',
+        `key ${issuerKeyId.toUpperCase()} cannot sign at ${whenArg.toISOString()}`,
+        { field: 'publicKeyArmored', value: issuers[0].getFingerprint().toUpperCase() },
+        { cause: error },
+      );
+    }
+    if (!issuers.includes(signingKey)) {
+      throw new LinuxRepoError('unusable-key', `key ${issuerKeyId.toUpperCase()} cannot sign at ${whenArg.toISOString()}`, {
+        field: 'publicKeyArmored',
+        value: issuers[0].getFingerprint().toUpperCase(),
+      });
+    }
+    return signingKey;
+  };
+  const atCreation = await signingKeyAt(packet.created);
+  const atDate = await signingKeyAt(date);
+  if (atCreation !== atDate) {
+    throw new LinuxRepoError('unusable-key', `key ${issuerKeyId.toUpperCase()} is not the same signing key at creation and at the verification date`, {
+      field: 'publicKeyArmored',
+      value: issuers[0].getFingerprint().toUpperCase(),
+    });
+  }
+
+  // 5. cryptography
+  try {
+    const content = inputArg.content;
+    const { signatures } =
+      'text' in content
+        ? await plugins.openpgp.verify({
+            message: await plugins.openpgp.createMessage({ text: content.text }),
+            signature,
+            verificationKeys: key,
+            date,
+            config: VERIFY_CONFIG,
+          })
+        : await plugins.openpgp.verify({
+            message: await plugins.openpgp.createMessage({ binary: content.binary }),
+            signature,
+            verificationKeys: key,
+            date,
+            format: 'binary',
+            config: VERIFY_CONFIG,
+          });
+    if (signatures.length !== 1) {
+      throw new Error(`openpgp.js evaluated ${signatures.length} signatures, expected 1`);
+    }
+    await signatures[0].verified;
+  } catch (error) {
+    throw new LinuxRepoError('bad-signature', 'the signature does not verify', { field }, { cause: error });
+  }
+  return {
+    signingKeyFingerprint: atDate.getFingerprint().toUpperCase(),
+    created: new Date(packet.created.getTime()),
+    hashAlgorithm,
+  };
+}