Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

11.0 KB
Raw Blame
/**
 * Locate and frame the APK Signing Block (APK Signature Scheme v2+). The block
 * sits between the last ZIP entry and the central directory:
 *   [ zip entries ][ APK Signing Block ][ central directory ][ EOCD ]
 * and is framed as:
 *   uint64 size | id-value pairs | uint64 size | "APK Sig Block 42"
 * where each pair is `uint64 length | uint32 id | value[length-4]`.
 *
 * Dependency-free and bounded: the end-of-central-directory record is found by a
 * bounded backward scan, every size/offset is checked against the buffer before
 * use, and a malformed or absent block yields a tagged {@link Result}, never a
 * throw. Absence of the block is `ok(null)` (the APK is v1-only or unsigned),
 * not an error. All integers are little-endian (ZIP).
 */
import { type Result, err, ok } from "../result.js";

const EOCD_SIGNATURE = 0x06054b50;
const ZIP64_EOCD_LOCATOR_SIGNATURE = 0x07064b50;
const ZIP64_EOCD_SIGNATURE = 0x06064b50;
const EOCD_MIN_SIZE = 22;
const MAX_COMMENT = 0xffff;
const ZIP64_SENTINEL = 0xffffffff;
/** The 16-bit EOCD entry count saturates here when Zip64 carries the real count. */
const ZIP64_ENTRIES_SENTINEL = 0xffff;
/** "APK Sig Block 42" — the 16-byte block magic (JAR/APK signing block spec). */
const BLOCK_MAGIC = "APK Sig Block 42";
/** A single pair is at least 12 bytes (uint64 length + uint32 id); cap the count. */
const MAX_PAIRS = 4096;

/** Well-known APK Signing Block pair IDs. */
export const APK_BLOCK_ID = {
  signatureV2: 0x7109871a,
  signatureV3: 0xf05368c0,
  signatureV31: 0x1b93ad61,
  sourceStampV1: 0x2b09189e,
  sourceStampV2: 0x6dff800d,
} as const;

export type ApkSigningBlockError =
  | { readonly kind: "not-a-zip"; readonly detail: string }
  | { readonly kind: "zip64-unsupported"; readonly detail: string }
  | {
      /** A ZIP whose end-of-central-directory is damaged or inconsistent. */
      readonly kind: "malformed-zip";
      readonly offset: number;
      readonly detail: string;
    }
  | {
      readonly kind: "malformed-block";
      readonly offset: number;
      readonly detail: string;
    }
  | {
      readonly kind: "budget-exceeded";
      readonly resource: "signing-block-pairs";
      readonly limit: number;
    };

export interface ZipTail {
  readonly eocdOffset: number;
  readonly centralDirectoryOffset: number;
  readonly centralDirectorySize: number;
  readonly totalEntries: number;
  /**
   * The classic EOCD record's 16-bit entry count. apksig takes the record
   * count from this field alone (it ignores a Zip64 record), so it reads only
   * this many records when Zip64 declares more.
   */
  readonly classicEntryCount: number;
}

export interface ApkSigningBlockPair {
  readonly id: number;
  /** View over the block buffer; not copied. */
  readonly value: Uint8Array;
}

export interface ApkSigningBlock {
  readonly blockStart: number;
  readonly pairs: readonly ApkSigningBlockPair[];
}

const view = (bytes: Uint8Array): DataView =>
  new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);

/** Read an unsigned 64-bit little-endian value as a Number, or null if unsafe/oob. */
const u64 = (dv: DataView, at: number): number | null => {
  if (at < 0 || at + 8 > dv.byteLength) return null;
  const value = dv.getBigUint64(at, true);
  return value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : null;
};

/** The archive starts with a ZIP local file header (`PK\x03\x04`). */
const hasLocalFileHeader = (bytes: Uint8Array): boolean =>
  bytes.length >= 4 &&
  bytes[0] === 0x50 &&
  bytes[1] === 0x4b &&
  bytes[2] === 0x03 &&
  bytes[3] === 0x04;

/**
 * Every EOCD candidate in the permitted comment window whose comment ends
 * exactly at the end of the archive, latest first.
 */
const eocdCandidates = (bytes: Uint8Array): number[] => {
  const dv = view(bytes);
  const found: number[] = [];
  const earliest = Math.max(0, bytes.length - EOCD_MIN_SIZE - MAX_COMMENT);
  for (let at = bytes.length - EOCD_MIN_SIZE; at >= earliest; at -= 1) {
    if (dv.getUint32(at, true) !== EOCD_SIGNATURE) continue;
    const commentLength = dv.getUint16(at + 20, true);
    if (at + EOCD_MIN_SIZE + commentLength === bytes.length) found.push(at);
  }
  return found;
};

/** Resolve the central-directory offset, following a Zip64 EOCD when present. */
const centralDirectoryOffset = (
  bytes: Uint8Array,
  eocdOffset: number,
): Result<
  { offset: number; size: number; entries: number; end: number },
  ApkSigningBlockError
> => {
  const dv = view(bytes);
  const entries = dv.getUint16(eocdOffset + 10, true);
  const size = dv.getUint32(eocdOffset + 12, true);
  const offset = dv.getUint32(eocdOffset + 16, true);
  const saturated =
    offset === ZIP64_SENTINEL ||
    size === ZIP64_SENTINEL ||
    entries === ZIP64_ENTRIES_SENTINEL;
  if (!saturated) return ok({ offset, size, entries, end: eocdOffset });
  // Zip64: a locator precedes the EOCD, pointing at the Zip64 EOCD record.
  const locator = eocdOffset - 20;
  if (
    locator < 0 ||
    dv.getUint32(locator, true) !== ZIP64_EOCD_LOCATOR_SIGNATURE
  ) {
    // Exactly 65,535 entries saturates the count without Zip64; that archive
    // is still described completely by its 32-bit EOCD fields.
    if (offset !== ZIP64_SENTINEL && size !== ZIP64_SENTINEL)
      return ok({ offset, size, entries, end: eocdOffset });
    return err({
      kind: "zip64-unsupported",
      detail: "missing Zip64 EOCD locator",
    });
  }
  const recordOffset = u64(dv, locator + 8);
  if (
    recordOffset === null ||
    recordOffset + 56 > locator ||
    dv.getUint32(recordOffset, true) !== ZIP64_EOCD_SIGNATURE
  )
    return err({
      kind: "zip64-unsupported",
      detail: "malformed Zip64 EOCD record",
    });
  const z64Offset = u64(dv, recordOffset + 48);
  const z64Size = u64(dv, recordOffset + 40);
  // The Zip64 record's total entry count; the 16-bit EOCD field saturates.
  const z64Entries = u64(dv, recordOffset + 32);
  if (z64Offset === null || z64Size === null || z64Entries === null)
    return err({
      kind: "zip64-unsupported",
      detail: "Zip64 sizes exceed safe range",
    });
  return ok({
    offset: z64Offset,
    size: z64Size,
    entries: z64Entries,
    end: recordOffset,
  });
};

/** Parse the ZIP end-of-central-directory to find the central directory. */
export const parseZipTail = (
  bytes: Uint8Array,
): Result<ZipTail, ApkSigningBlockError> => {
  if (bytes.length < EOCD_MIN_SIZE)
    return err({ kind: "not-a-zip", detail: "shorter than a ZIP EOCD record" });
  const candidates = eocdCandidates(bytes);
  // Two records that each end the archive exactly (one inside the other's
  // comment) leave the archive's directory undetermined: whichever a reader
  // picks, the other may be attacker-placed. apksigner and Android take the
  // one nearest the end; that choice can report a signed APK as unsigned, so
  // REA deliberately refuses instead (stricter than apksigner: a crafted APK
  // that apksigner verifies may be refused here, never misreported).
  if (candidates.length > 1)
    return err({
      kind: "malformed-zip",
      offset: candidates[0]!,
      detail: `${String(candidates.length)} end-of-central-directory records each end the archive (one inside another's comment); the central directory is ambiguous`,
    });
  const eocdOffset = candidates[0] ?? null;
  if (eocdOffset === null)
    // A local-file header without an EOCD is a damaged/truncated archive, not
    // a different file type.
    return hasLocalFileHeader(bytes)
      ? err({
          kind: "malformed-zip",
          offset: bytes.length,
          detail:
            "ZIP local headers present but no end-of-central-directory (truncated or damaged archive)",
        })
      : err({
          kind: "not-a-zip",
          detail: "no end-of-central-directory record",
        });
  const cd = centralDirectoryOffset(bytes, eocdOffset);
  if (!cd.ok) return cd;
  if (
    cd.value.offset > cd.value.end ||
    cd.value.size > cd.value.end - cd.value.offset
  )
    return err({
      kind: "malformed-zip",
      offset: eocdOffset,
      detail:
        "central-directory extent overlaps or extends past the ZIP end records",
    });
  // An EOCD declaring no entries cannot describe an archive that holds a
  // local file entry (e.g. a fake EOCD planted in the real one's comment);
  // reading on would report a signed APK as confidently unsigned.
  if (
    (cd.value.entries === 0 || cd.value.size === 0) &&
    hasLocalFileHeader(bytes)
  )
    return err({
      kind: "malformed-zip",
      offset: eocdOffset,
      detail:
        "end-of-central-directory declares no entries, but the archive holds local file entries",
    });
  return ok({
    eocdOffset,
    centralDirectoryOffset: cd.value.offset,
    centralDirectorySize: cd.value.size,
    totalEntries: cd.value.entries,
    classicEntryCount: view(bytes).getUint16(eocdOffset + 10, true),
  });
};

const hasBlockMagic = (bytes: Uint8Array, cdOffset: number): boolean => {
  if (cdOffset < 16) return false;
  let magic = "";
  for (let i = 0; i < 16; i += 1)
    magic += String.fromCharCode(bytes[cdOffset - 16 + i]!);
  return magic === BLOCK_MAGIC;
};

/**
 * Locate and frame the APK Signing Block immediately before the central
 * directory. Returns `ok(null)` when no block magic is present (v1-only or
 * unsigned), or the framed id-value pairs otherwise.
 */
export const locateApkSigningBlock = (
  bytes: Uint8Array,
  tail: ZipTail,
): Result<ApkSigningBlock | null, ApkSigningBlockError> => {
  const cdOffset = tail.centralDirectoryOffset;
  if (!hasBlockMagic(bytes, cdOffset)) return ok(null);
  const dv = view(bytes);
  const trailingSize = u64(dv, cdOffset - 24);
  // The footer alone (trailing size + magic) is 24 bytes; a smaller declared
  // size would alias the leading and trailing fields (apksig rejects it too).
  if (trailingSize === null || trailingSize < 24)
    return err({
      kind: "malformed-block",
      offset: cdOffset - 24,
      detail: "bad trailing size",
    });
  const blockStart = cdOffset - trailingSize - 8;
  if (blockStart < 0)
    return err({
      kind: "malformed-block",
      offset: cdOffset,
      detail: "block extends before file start",
    });
  const leadingSize = u64(dv, blockStart);
  if (leadingSize === null || leadingSize !== trailingSize)
    return err({
      kind: "malformed-block",
      offset: blockStart,
      detail: "leading/trailing size mismatch",
    });

  const pairs: ApkSigningBlockPair[] = [];
  let cursor = blockStart + 8;
  const pairsEnd = cdOffset - 24; // stop before trailing size + magic
  while (cursor < pairsEnd) {
    const length = u64(dv, cursor);
    if (length === null || length < 4 || cursor + 8 + length > pairsEnd + 0)
      return err({
        kind: "malformed-block",
        offset: cursor,
        detail: "pair length out of range",
      });
    if (pairs.length >= MAX_PAIRS)
      return err({
        kind: "budget-exceeded",
        resource: "signing-block-pairs",
        limit: MAX_PAIRS,
      });
    const id = dv.getUint32(cursor + 8, true);
    const valueStart = cursor + 12;
    pairs.push({
      id,
      value: bytes.subarray(valueStart, valueStart + (length - 4)),
    });
    cursor += 8 + length;
  }
  return ok({ blockStart, pairs });
};