amd-ucode-patch 1.0.0__tar.gz → 1.0.1__tar.gz

{amd_ucode_patch-1.0.0 → amd_ucode_patch-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amd-ucode-patch
-Version: 1.0.0
+Version: 1.0.1
 Summary: A Python library for parsing and interpreting AMD microcode patch files
 Project-URL: Homepage, https://github.com/amd-zenith/amd-ucode-patch
 Project-URL: Repository, https://github.com/amd-zenith/amd-ucode-patch
@@ -23,7 +23,9 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Hardware
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
-Requires-Dist: rich
+Requires-Dist: amd-cpuid==1.0.1
+Requires-Dist: pycryptodome==3.23.0
+Requires-Dist: rich==15.0.0
 Description-Content-Type: text/markdown
 
 # AMD Microcode Patch

{amd_ucode_patch-1.0.0 → amd_ucode_patch-1.0.1}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling", "hatch-vcs"]
+requires = ["hatchling==1.30.1", "hatch-vcs==0.5.0"]
 build-backend = "hatchling.build"
 
 [project]
@@ -30,7 +30,9 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-  "rich",
+  "amd-cpuid==1.0.1",
+  "pycryptodome==3.23.0",
+  "rich==15.0.0",
 ]
 
 [project.urls]
@@ -39,7 +41,8 @@ Repository = "https://github.com/amd-zenith/amd-ucode-patch"
 Issues = "https://github.com/amd-zenith/amd-ucode-patch/issues"
 
 [project.scripts]
-amd_ucode_patch_info = "amd_ucode_patch.cli_info:main"
+amd_ucode_patch_info = "amd_ucode_patch.cli.info:main"
+amd_ucode_patch_sign = "amd_ucode_patch.cli.sign:main"
 
 [tool.hatch.version]
 source = "vcs"

amd_ucode_patch-1.0.0/src/amd_ucode_patch/cli_info.py → amd_ucode_patch-1.0.1/src/amd_ucode_patch/cli/info.py

@@ -10,10 +10,11 @@ from pathlib import Path
 from rich import box
 from rich.console import Console
 from rich.table import Table
-from .banner import BANNER
-from .parse import ucode_patch_parse
+from ..banner import BANNER
+from ..parse import ucode_patch_parse
+from ..structures.patch_level import PatchLevelV2
 
-COLS = ["File", "Date", "Upd. Rev", "Loader ID", "Proc. Rev", "CPUID", "Family", "Model", "Stepping", "Autorun", "Encrypted", "Body size"]
+COLS = ["File", "Date", "Patch level", "PL Ver", "PL Rev", "Loader ID", "Proc. Rev", "CPUID", "Family", "Family Name", "Model", "Stepping", "Microarch", "Codename", "Signed", "Autorun", "Encrypted", "Body size"]
 
 
 def expand_paths(patterns):
@@ -27,19 +28,28 @@ def expand_paths(patterns):
 
 
 def _row_fields(path, patch):
+    patch_level = patch.header.patch_level
+    # Advanced (v2 / Zen+) patch level fields are only meaningful when present.
+    patch_rev = f"{patch_level.rev:02x}" if isinstance(patch_level, PatchLevelV2) else ""
     return (
         str(path),
-        f"{patch.header.year:04d}-{patch.header.month:02d}-{patch.header.day:02d}",
-        f"{patch.header.update_revision:08x}",
+        str(patch.header.date),
+        str(patch_level),
+        f"v{int(patch_level.version)}",
+        patch_rev,
         f"{patch.header.loader_id:04x}",
-        f"{patch.header.processor_rev_id:04x}",
-        patch.header.cpuid_str,
-        f"0x{patch.header.cpu_family:02x}",
-        f"0x{patch.header.cpu_model:02x}",
-        f"0x{patch.header.cpu_stepping:02x}",
-        f"{patch.verified_header.autorun if patch.verified_header is not None else ''}",
-        f"{patch.verified_header.encrypted if patch.verified_header is not None else ''}",
-        f"{len(patch.body)}",
+        f"{patch.header.cpuid.ucode_signature:04x}",
+        f"{patch.header.cpuid.cpuid_signature:08X}",
+        f"0x{patch.header.cpuid.family:02x}",
+        patch.header.cpuid.familyname,
+        f"0x{patch.header.cpuid.model:02x}",
+        f"0x{patch.header.cpuid.stepping:02x}",
+        patch.header.cpuid.microarchitecture,
+        patch.header.cpuid.codename,
+        "yes" if patch.header.signature is not None else "no",
+        f"{patch.body.verified_header.autorun if patch.body.verified_header is not None else ''}",
+        f"{patch.body.verified_header.encrypted if patch.body.verified_header is not None else ''}",
+        f"{len(patch.body.data)}",
     )
 
 def print_table(console: Console, paths, format):

amd_ucode_patch-1.0.1/src/amd_ucode_patch/cli/sign.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+'''
+A command line tool to inspect and verify AMD uCode patch signatures.
+'''
+
+import sys
+import argparse
+from Crypto.Cipher import AES
+from Crypto.Hash import CMAC
+from rich import box
+from rich.console import Console
+from rich.table import Table
+from ..banner import BANNER
+from ..parse import ucode_patch_parse
+from .info import expand_paths
+
+COLS = ["File", "Signed", "Digest", "Valid"]
+
+
+def _parse_key(value: str) -> bytes:
+    text = value.strip().lower()
+    if text.startswith("0x"):
+        text = text[2:]
+    try:
+        key = bytes.fromhex(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"key must be hexadecimal, got {value!r}")
+    if len(key) != 16:
+        raise argparse.ArgumentTypeError(
+            f"key must be 16 bytes (32 hex chars), got {len(key)}"
+        )
+    return key
+
+
+def _row(path, key):
+    """Return (row_cells, verdict) where verdict is True/False (key given) or None."""
+    patch = ucode_patch_parse(path)
+    signature = patch.header.signature
+
+    if signature is None:
+        return (str(path), "[yellow]no[/yellow]", "", "[dim]n/a[/dim]"), None
+
+    recovered = signature.recover_digest()
+    digest = recovered.hex() if recovered is not None else "[red]<bad padding>[/red]"
+
+    if key is None:
+        return (str(path), "[green]yes[/green]", digest, "[dim]not checked[/dim]"), None
+
+    computed = CMAC.new(key, msg=patch.body.to_bytes(), ciphermod=AES).digest()
+    verdict = recovered is not None and recovered == computed
+    valid = "[green]yes[/green]" if verdict else "[red]no[/red]"
+    return (str(path), "[green]yes[/green]", digest, valid), verdict
+
+
+def main():
+    console = Console()
+    console.print(BANNER, highlight=False)
+
+    parser = argparse.ArgumentParser(
+        description="Inspect AMD microcode patch signatures; verify them when a key is provided.",
+        epilog="The published Zen 1-4 CMAC key is 2b7e151628aed2a6abf7158809cf4f3c.",
+    )
+    parser.add_argument("files", nargs="+", help="Patch files to inspect")
+    parser.add_argument(
+        "-k", "--key", type=_parse_key, default=None,
+        help="AES-128 CMAC key as hex (32 hex chars); enables signature verification",
+    )
+    args = parser.parse_args()
+
+    table = Table(*COLS, box=box.HEAVY_HEAD)
+    all_ok = True
+    for path in expand_paths(args.files):
+        try:
+            row, verdict = _row(path, args.key)
+            table.add_row(*row)
+            if verdict is False:
+                all_ok = False
+        except Exception as e:
+            console.log(f"Error reading {path}: {e}")
+            all_ok = False
+    console.print(table)
+
+    # Non-zero only when a key was given and a signature failed to verify.
+    sys.exit(0 if all_ok else 1)
+
+
+if __name__ == "__main__":
+    main()

amd_ucode_patch-1.0.1/src/amd_ucode_patch/naming.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from .structures.patch import Patch
+
+def ucode_patch_name(patch: Patch, enc_override=None) -> str:
+    # Format should be:
+    # family<family>_cpuid<cpuid>_rev<revision>_date<yyyymmdd>_enc<ee>.bin
+    # The _enc<ee> suffix is only present when a verified header exists.
+    cpuid = patch.header.cpuid
+    name = f"family{cpuid.family:02x}_cpuid{cpuid.cpuid_signature:08X}_rev{patch.header.patch_level}_date{patch.header.date.year:04}{patch.header.date.month:02}{patch.header.date.day:02}"
+    if patch.body.verified_header is not None:
+        enc = patch.body.verified_header.encrypted if enc_override is None else enc_override
+        name += f"_enc{enc:02}"
+    name += ".bin"
+    return name

amd_ucode_patch-1.0.1/src/amd_ucode_patch/parse.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from pathlib import Path
+from .structures.patch import Patch
+
+def ucode_patch_parse(file: Path) -> Patch:
+    with file.open("rb") as f:
+        return Patch.from_bytes(f.read())

amd_ucode_patch-1.0.1/src/amd_ucode_patch/structures/body.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from dataclasses import dataclass
+from .verified_header import VerifiedHeader
+
+
+#: Family at/after which the body carries a verified header (options + rev).
+#: This is the Zen boundary; kept independent of the signature gating.
+VERIFIED_HEADER_MIN_FAMILY = 0x17
+
+
+@dataclass
+class Body:
+    """
+    The signed portion of an AMD microcode patch -- the region the RSA signature
+    in :class:`PatchHeader` covers (through the AES-CMAC).
+
+    On Zen (signed) patches it is the ``options``/``rev`` block
+    (:class:`VerifiedHeader`) followed by the match registers and the (encrypted)
+    microcode opquads. On pre-Zen patches there is no verified header and the
+    whole thing is the raw, unsigned microcode.
+    """
+
+    verified_header: VerifiedHeader | None
+    data: bytes
+
+    @staticmethod
+    def from_bytes(buf: bytes, family: int | None = None) -> "Body":
+        """
+        Parse the body. The verified header (options + rev) is present only on
+        Zen patches (family >= ``VERIFIED_HEADER_MIN_FAMILY``); ``family`` selects
+        that. When ``family`` is unknown the body is treated as having none.
+        """
+        if family is not None and family >= VERIFIED_HEADER_MIN_FAMILY:
+            verified_header = VerifiedHeader.from_bytes(buf, family=family)
+            data = buf[VerifiedHeader.SIZE:]
+        else:
+            verified_header = None
+            data = buf
+        return Body(verified_header=verified_header, data=data)
+
+    def to_bytes(self) -> bytes:
+        prefix = self.verified_header.to_bytes() if self.verified_header is not None else b""
+        return prefix + self.data

amd_ucode_patch-1.0.1/src/amd_ucode_patch/structures/patch.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from dataclasses import dataclass
+from .patch_header import PatchHeader
+from .body import Body
+
+
+@dataclass
+class Patch:
+    header: PatchHeader
+    body: Body
+
+
+    @staticmethod
+    def from_bytes(buf: bytes) -> "Patch":
+        header = PatchHeader.from_bytes(buf)
+        # Everything after the header is the signed body: the verified header
+        # (options + rev, Zen only) plus the microcode itself.
+        body = Body.from_bytes(buf[header.size:], family=header.cpuid.family)
+        return Patch(header=header, body=body)
+
+    def signature_verifies(self, cmac_key: bytes) -> bool | None:
+        """
+        Whether the patch signature verifies against its embedded public key,
+        using the provided CMAC key (see :data:`Signature.verify`).
+
+        ``None`` for unsigned (pre-Zen) patches. A ``False`` result does not by
+        itself mean the patch is forged: patches signed with a CMAC key this
+        library does not ship -- Zen 5, and AMD's post-EntrySign patches that
+        rotated the key -- also report ``False`` even though their RSA signature
+        is structurally valid against the embedded modulus.
+        """
+        if self.header.signature is None:
+            return None
+        return self.header.signature.verify(self.body.to_bytes(), cmac_key)

amd_ucode_patch-1.0.1/src/amd_ucode_patch/structures/patch_date.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import struct
+from dataclasses import dataclass
+
+from amd_ucode_patch.utils.bcd import decode_bcd, encode_bcd, is_bcd
+
+
+@dataclass
+class PatchDate:
+    """
+    Build date stored in the first 32-bit word of an AMD microcode patch header.
+
+    The field is a little-endian, packed binary-coded-decimal value laid out as
+    0xMMDDYYYY: the high byte holds the month, the next byte the day, and the low
+    16 bits the four-digit year (e.g. 0x12282021 decodes to 2021-12-28).
+    """
+
+    FMT = "<HBB"  # year (u16), day (u8), month (u8)
+    SIZE = struct.calcsize(FMT)
+
+    YEAR_NIBBLES = 4
+    DAY_NIBBLES = 2
+    MONTH_NIBBLES = 2
+    NIBBLE_COUNT = YEAR_NIBBLES + DAY_NIBBLES + MONTH_NIBBLES
+
+    # Loose calendar bounds, used only to reject obviously bogus values when
+    # probing a file.
+    MIN_YEAR = 1990
+    MAX_YEAR = 2099
+
+    # Known AMD patches that ship an out-of-range date but are otherwise
+    # legitimate. Treated as plausible despite failing the calendar checks.
+    # 2011-13-09 -> family12_cpuid00300F10_rev03000027 (month 13).
+    KNOWN_EXCEPTIONS = frozenset({(2011, 13, 9)})
+
+    year: int
+    month: int
+    day: int
+
+    @staticmethod
+    def from_bytes(buf: bytes) -> "PatchDate":
+        if len(buf) < PatchDate.SIZE:
+            raise ValueError("not enough bytes for AMD patch date")
+        raw_year, raw_day, raw_month = struct.unpack(PatchDate.FMT, buf[0:PatchDate.SIZE])
+        return PatchDate(
+            year=decode_bcd(raw_year, PatchDate.YEAR_NIBBLES),
+            day=decode_bcd(raw_day, PatchDate.DAY_NIBBLES),
+            month=decode_bcd(raw_month, PatchDate.MONTH_NIBBLES),
+        )
+
+    def to_bytes(self) -> bytes:
+        return struct.pack(
+            PatchDate.FMT,
+            encode_bcd(self.year, PatchDate.YEAR_NIBBLES),
+            encode_bcd(self.day, PatchDate.DAY_NIBBLES),
+            encode_bcd(self.month, PatchDate.MONTH_NIBBLES),
+        )
+
+    @staticmethod
+    def is_valid_encoding(buf: bytes) -> bool:
+        """
+        Return ``True`` if ``buf`` holds well-formed packed BCD that decodes to a
+        plausible calendar date. Intended as a lightweight signature check while
+        deciding whether a file looks like a microcode patch.
+        """
+        if len(buf) < PatchDate.SIZE:
+            return False
+        raw_year, raw_day, raw_month = struct.unpack(PatchDate.FMT, buf[0:PatchDate.SIZE])
+        if not (
+            is_bcd(raw_year, PatchDate.YEAR_NIBBLES)
+            and is_bcd(raw_day, PatchDate.DAY_NIBBLES)
+            and is_bcd(raw_month, PatchDate.MONTH_NIBBLES)
+        ):
+            return False
+        return PatchDate.from_bytes(buf).is_plausible()
+
+    def is_plausible(self) -> bool:
+        """Return ``True`` if the components fall within sane calendar ranges."""
+        if (self.year, self.month, self.day) in PatchDate.KNOWN_EXCEPTIONS:
+            return True
+        return (
+            1 <= self.month <= 12
+            and 1 <= self.day <= 31
+            and PatchDate.MIN_YEAR <= self.year <= PatchDate.MAX_YEAR
+        )
+
+    def __str__(self) -> str:
+        return f"{self.year:04d}-{self.month:02d}-{self.day:02d}"

amd_ucode_patch-1.0.1/src/amd_ucode_patch/structures/patch_header.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import struct
+from dataclasses import dataclass
+from amd_cpuid import AmdCpuId
+from amd_ucode_patch.structures.patch_date import PatchDate
+from amd_ucode_patch.structures.patch_level import PatchLevel
+from amd_ucode_patch.structures.signature import Signature
+
+
+#: Patches are cryptographically signed starting with Zen (family 0x17). Earlier
+#: families carry no signature block.
+SIGNED_MIN_FAMILY = 0x17
+
+
+@dataclass
+class PatchHeader:
+    '''
+    AMD microcode patch header.
+
+    The fixed 32-byte core is the Linux ``microcode_header_amd``. The fields the
+    project interprets are:
+
+    - ``date``        -- build date (``data_code``; a BCD date, not a code)
+    - ``patch_level`` -- patch id / revision (``patch_id``; the value ``rdmsr
+                         0x8B`` reports for the loaded microcode)
+    - ``loader_id``   -- microcode loader id
+    - ``cpuid``       -- target processor, decoded from the ucode signature
+                         (``processor_rev_id``)
+
+    On Zen and later (family >= 0x17) a 768-byte cryptographic ``Signature`` block.
+
+    The header has two sizes: ``SIZE`` is the fixed core (32 bytes) and the
+    ``size`` property is the total encoding (core + signature block when present).
+    '''
+    # Fields after the leading PatchDate (data_code) and PatchLevel (patch_id).
+    FMT = "<HBB I II H BBBBBB"
+    # Size of the fixed core struct (the Linux ``microcode_header_amd``). The
+    # optional Zen signature block follows it; use ``size`` for the total.
+    SIZE = PatchDate.SIZE + PatchLevel.SIZE + struct.calcsize(FMT)
+
+    date: PatchDate
+    patch_level: PatchLevel
+    loader_id: int
+    unk0: int
+    unk1: int
+    unk2: int
+    unk3: int
+    unk4: int
+    cpuid: AmdCpuId
+    unk5: int
+    unk6: int
+    unk7: int
+    unk8: int
+    unk9: int
+    unk10: int
+    #: Cryptographic signature block; present only on Zen (family >= 0x17).
+    signature: Signature | None
+
+    @staticmethod
+    def from_bytes(buf: bytes) -> "PatchHeader":
+        if len(buf) < PatchHeader.SIZE:
+            raise ValueError("not enough bytes for AMD header")
+        date = PatchDate.from_bytes(buf)
+        rest_start = PatchDate.SIZE + PatchLevel.SIZE
+        chunk = buf[rest_start:PatchHeader.SIZE]
+        vals = struct.unpack(PatchHeader.FMT, chunk)
+        cpuid = AmdCpuId.from_ucode_signature(vals[6])
+        # The patch level layout depends on the CPU family, so build cpuid first.
+        patch_level = PatchLevel.from_bytes(buf[PatchDate.SIZE:], family=cpuid.family)
+        # The signature block follows the core struct, on Zen and later only.
+        signature = (
+            Signature.from_bytes(buf[PatchHeader.SIZE:])
+            if cpuid.family >= SIGNED_MIN_FAMILY
+            else None
+        )
+        return PatchHeader(
+            date=date,
+            patch_level=patch_level,
+            loader_id=vals[0],
+            unk0=vals[1],
+            unk1=vals[2],
+            unk2=vals[3],
+            unk3=vals[4],
+            unk4=vals[5],
+            cpuid=cpuid,
+            unk5=vals[7],
+            unk6=vals[8],
+            unk7=vals[9],
+            unk8=vals[10],
+            unk9=vals[11],
+            unk10=vals[12],
+            signature=signature,
+        )
+
+    @property
+    def size(self) -> int:
+        """Total encoded size: the core struct plus the signature block if present."""
+        return PatchHeader.SIZE + (Signature.SIZE if self.signature is not None else 0)
+
+    def to_bytes(self) -> bytes:
+        core = self.date.to_bytes() + self.patch_level.to_bytes() + struct.pack(
+            PatchHeader.FMT,
+            self.loader_id,
+            self.unk0,
+            self.unk1,
+            self.unk2,
+            self.unk3,
+            self.unk4,
+            self.cpuid.ucode_signature,
+            self.unk5,
+            self.unk6,
+            self.unk7,
+            self.unk8,
+            self.unk9,
+            self.unk10,
+        )
+        if self.signature is not None:
+            core += self.signature.to_bytes()
+        return core

amd_ucode_patch-1.0.1/src/amd_ucode_patch/structures/patch_level.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import struct
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import ClassVar
+
+
+#: Effective family at which the v2 (Zen) layout applies. The Linux kernel
+#: switches behaviour on ``x86_family(bsp_cpuid_1_eax) >= 0x17``.
+V2_MIN_FAMILY = 0x17
+
+
+class PatchLevelError(Exception):
+    """Base error for patch level operations."""
+
+
+class PatchLevelMismatchError(PatchLevelError):
+    """Raised when comparing two v2 patch levels that target different CPUs."""
+
+
+class PatchLevelVersion(IntEnum):
+    """Which structural layout a :class:`PatchLevel` uses (see module docs)."""
+
+    V1 = 1
+    V2 = 2
+
+    def __str__(self) -> str:
+        return {
+            PatchLevelVersion.V1: "v1 (pre-Zen)",
+            PatchLevelVersion.V2: "v2 (Zen+)",
+        }[self]
+
+
+@dataclass
+class PatchLevel(ABC):
+    """
+    Microcode patch level (a.k.a. patch ID / update revision), the second 32-bit
+    word of an AMD microcode patch header.
+
+    Names across sources, all the same ``u32`` at header offset 4:
+
+    - ``patch_id``           -- Linux ``struct microcode_header_amd``
+    - ``revision``           -- zentool ``struct ucodehdr``
+    - ``ucode_level`` / "Patch level" -- AMD ``amd_ucode_info.py`` / linux-firmware
+    - ``MSR_AMD64_PATCH_LEVEL`` (MSR ``0x8B``) -- what the CPU reports for the
+      currently loaded patch; the kernel verifies ``rdmsr 0x8B == hdr.patch_id``
+      after applying a patch.
+
+    The value is compared as a whole word by the loader, but it is not opaque.
+    It is a structured patch identifier whose layout depends on the CPU
+    generation. There are two documented versions ("v1" pre-Zen, "v2" Zen).
+
+    --------------------------------------------------------------------------
+    Version 1 -- pre-Zen (family <= 0x16)
+    --------------------------------------------------------------------------
+    The patch level is an *opaque, monotonically increasing counter*. The CPU
+    that a patch targets is NOT encoded here; matching is done via a separate
+    equivalence table (``equiv_cpu_entry``) keyed on ``CPUID(1).EAX``, and the
+    header's ``processor_rev_id`` links each patch to that table.
+
+    Apply rule (kernel): whole-word compare -- ``n->patch_id > p->patch_id``.
+
+    No source documents an internal sub-byte layout for v1. Empirically over the
+    collection the top byte still tracks the extended family
+    (``patch_id[31:24] == cpuid.familyext``), but the low 24 bits are just a
+    counter and bits ``[19:16]`` are NOT reserved (some v1 patches set them).
+    Do not decode model/stepping from a v1 patch level.
+
+    --------------------------------------------------------------------------
+    Version 2 -- Zen and later (family >= 0x17)
+    --------------------------------------------------------------------------
+    The patch level hardcodes the target family/model/stepping so the loader can
+    skip the equivalence table entirely. Bit layout (Linux ``union
+    zen_patch_rev``)::
+
+        bits [ 7: 0]  rev         patch sequence number (the only part that
+                                  increments between updates for a given CPU)
+        bits [11: 8]  stepping    CPU stepping
+        bits [15:12]  model       model, low nibble
+        bits [19:16]  (reserved)  always 0
+        bits [23:20]  ext_model   model, high nibble
+        bits [31:24]  ext_fam     extended family (effective family - 0xF)
+
+    Effective family = ``0xF + ext_fam``; effective model =
+    ``(ext_model << 4) | model``. These upper three bytes mirror
+    ``CPUID(1).EAX`` (base family nibble is forced to ``0xF`` and reconstructed).
+
+    Apply rule (kernel ``patch_newer``): the stepping must match, then compare
+    only the low byte -- ``zn.rev > zp.rev``.
+
+    --------------------------------------------------------------------------
+    References
+    --------------------------------------------------------------------------
+    - Linux ``arch/x86/kernel/cpu/microcode/amd.c`` -- ``struct
+      microcode_header_amd``, ``union zen_patch_rev``, ``patch_newer()``,
+      ``equiv_cpu_entry``, ``MSR_AMD64_PATCH_LEVEL``.
+    - AMD ``amd_ucode_info.py`` (AMDESE) and linux-firmware ``amd-ucode/README``.
+    - AMD CPUID Specification (PDF 25481) for the ``CPUID(1).EAX`` f/m/s layout.
+    """
+
+    FMT = "<I"
+    SIZE = struct.calcsize(FMT)
+
+    #: Layout this instance uses; set by each concrete subclass.
+    version: ClassVar[PatchLevelVersion]
+
+    value: int
+
+    @staticmethod
+    def from_bytes(buf: bytes, family: int | None = None) -> "PatchLevel":
+        """
+        Parse a patch level from the first 4 bytes of ``buf``.
+
+        ``family`` is the effective CPU family (from the header's cpuid). It
+        selects the layout: ``family >= 0x17`` -> v2, otherwise v1. When it is
+        unknown (``None``) the value defaults to the v1 (opaque counter) layout.
+        """
+        if len(buf) < PatchLevel.SIZE:
+            raise ValueError("not enough bytes for AMD patch level")
+        (value,) = struct.unpack(PatchLevel.FMT, buf[0:PatchLevel.SIZE])
+        return PatchLevel.from_value(value, family)
+
+    @staticmethod
+    def from_value(value: int, family: int | None = None) -> "PatchLevel":
+        """Build the variant appropriate for ``family`` (see :meth:`from_bytes`)."""
+        if family is not None and family >= V2_MIN_FAMILY:
+            return PatchLevelV2(value)
+        return PatchLevelV1(value)
+
+    def to_bytes(self) -> bytes:
+        return struct.pack(PatchLevel.FMT, self.value)
+
+    @abstractmethod
+    def is_valid(self, cpuid=None) -> bool:
+        """
+        Whether the structured fields are self-consistent (and, if ``cpuid`` is
+        given, consistent with it). See the concrete variants for the rules.
+        """
+
+    @abstractmethod
+    def _cmp_same(self, other: "PatchLevel") -> int:
+        """Compare against a same-version instance; return -1, 0 or 1."""
+
+    def _compare(self, other: object):
+        if not isinstance(other, PatchLevel):
+            return NotImplemented
+        if type(self) is not type(other):
+            raise PatchLevelError(
+                f"cannot compare {self.version} with {other.version} patch levels"
+            )
+        return self._cmp_same(other)
+
+    def __lt__(self, other: object):
+        r = self._compare(other)
+        return r < 0 if r is not NotImplemented else NotImplemented
+
+    def __le__(self, other: object):
+        r = self._compare(other)
+        return r <= 0 if r is not NotImplemented else NotImplemented
+
+    def __gt__(self, other: object):
+        r = self._compare(other)
+        return r > 0 if r is not NotImplemented else NotImplemented
+
+    def __ge__(self, other: object):
+        r = self._compare(other)
+        return r >= 0 if r is not NotImplemented else NotImplemented
+
+    def __int__(self) -> int:
+        return self.value
+
+    def __str__(self) -> str:
+        return f"{self.value:08x}"
+
+
+@dataclass
+class PatchLevelV1(PatchLevel):
+    """
+    Pre-Zen (family <= 0x16) patch level
+    An opaque, monotonically increasing counter.
+    """
+
+    version: ClassVar[PatchLevelVersion] = PatchLevelVersion.V1
+
+    @property
+    def rev(self) -> int:
+        """The monotonic patch counter."""
+        return self.value
+
+    def is_valid(self, cpuid=None) -> bool:
+        # v1 has no documented internal structure to validate. The top byte
+        # only advisorily tracks the extended family and a few genuine early
+        # patches violate even that, so validity is not gated on it.
+        return True
+
+    def _cmp_same(self, other: "PatchLevel") -> int:
+        return (self.value > other.value) - (self.value < other.value)
+
+
+@dataclass
+class PatchLevelV2(PatchLevel):
+    """
+    Zen and later (family >= 0x17) patch level.
+    The whole word decodes (Linux ``union zen_patch_rev``); the upper three bytes
+    identify the target CPU and only :attr:`rev` (low byte) increments between
+    updates.
+
+    Comparison requires the same target CPU: comparing two v2 patch levels whose
+    upper three bytes differ raises :class:`PatchLevelMismatchError`; otherwise
+    the low :attr:`rev` byte is compared.
+    """
+
+    version: ClassVar[PatchLevelVersion] = PatchLevelVersion.V2
+
+    @property
+    def rev(self) -> int:
+        """Patch sequence number (bits 7:0); the only part that increments."""
+        return self.value & 0xFF
+
+    @property
+    def stepping(self) -> int:
+        """CPU stepping (bits 11:8)."""
+        return (self.value >> 8) & 0xF
+
+    @property
+    def modelbase(self) -> int:
+        """Model low nibble (bits 15:12)."""
+        return (self.value >> 12) & 0xF
+
+    @property
+    def reserved(self) -> int:
+        """Reserved field (bits 19:16); expected to be 0."""
+        return (self.value >> 16) & 0xF
+
+    @property
+    def modelext(self) -> int:
+        """Model high nibble (bits 23:20)."""
+        return (self.value >> 20) & 0xF
+
+    @property
+    def familyext(self) -> int:
+        """Extended family (bits 31:24); ``family == 0xF + familyext``."""
+        return (self.value >> 24) & 0xFF
+
+    @property
+    def family(self) -> int:
+        """Effective family (``0xF + familyext``)."""
+        return 0xF + self.familyext
+
+    @property
+    def model(self) -> int:
+        """Effective model (``(modelext << 4) | modelbase``)."""
+        return (self.modelext << 4) | self.modelbase
+
+    def matches(self, cpuid) -> bool:
+        """Whether the embedded f/m/s match an ``AmdCpuId`` (upper 3 bytes)."""
+        expected = (
+            (cpuid.familyext << 16)
+            | (cpuid.modelext << 12)
+            | (cpuid.modelbase << 4)
+            | cpuid.stepping
+        )
+        return (self.value >> 8) == expected
+
+    def is_valid(self, cpuid=None) -> bool:
+        if self.reserved != 0:
+            return False
+        if self.familyext < (V2_MIN_FAMILY - 0xF):
+            return False
+        if cpuid is not None and not self.matches(cpuid):
+            return False
+        return True
+
+    def _cmp_same(self, other: "PatchLevel") -> int:
+        if (self.value >> 8) != (other.value >> 8):
+            raise PatchLevelMismatchError(f"patch levels target different CPUs: {self} vs {other}")
+        return (self.rev > other.rev) - (self.rev < other.rev)

amd_ucode_patch-1.0.1/src/amd_ucode_patch/structures/signature.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from dataclasses import dataclass
+from Crypto.Cipher import AES
+from Crypto.Hash import CMAC
+from amd_ucode_patch.utils.rsa import digest_recover, pkcs1_v15_verify
+
+
+@dataclass
+class Signature:
+    """
+    Cryptographic signature block of a Zen (family >= 0x17) AMD microcode patch.
+
+    It sits immediately after the 32-byte header core and is absent on pre-Zen
+    patches. Layout (offsets are from the start of the patch)::
+
+        offset  32  signature[256]  RSA-2048 signature (PKCS#1 v1.5, e=0x10001)
+        offset 288  modulus[256]    RSA-2048 public key, embedded in the patch
+        offset 544  check[256]      Montgomery helper derived from the modulus
+    """
+
+    SIG_SIZE = 256
+    MODULUS_SIZE = 256
+    CHECK_SIZE = 256
+    SIZE = SIG_SIZE + MODULUS_SIZE + CHECK_SIZE
+
+    signature: bytes
+    modulus: bytes
+    check: bytes
+
+    @staticmethod
+    def from_bytes(buf: bytes) -> "Signature":
+        if len(buf) < Signature.SIZE:
+            raise ValueError("not enough bytes for AMD signature block")
+        return Signature(
+            signature=buf[0:Signature.SIG_SIZE],
+            modulus=buf[Signature.SIG_SIZE:Signature.SIG_SIZE + Signature.MODULUS_SIZE],
+            check=buf[Signature.SIG_SIZE + Signature.MODULUS_SIZE:Signature.SIZE],
+        )
+
+    def to_bytes(self) -> bytes:
+        return self.signature + self.modulus + self.check
+
+    def recover_digest(self) -> bytes | None:
+        """
+        Recover the digest this signature commits to, using only the embedded
+        public ``modulus`` (no CMAC key required): compute
+        ``signature ^ 0x10001 mod modulus`` and strip the PKCS#1 v1.5 padding.
+
+        Returns the recovered payload — the 16-byte AES-CMAC AMD signed — or
+        ``None`` if the recovered block is not well-formed PKCS#1 v1.5 (e.g. a
+        corrupt signature or wrong modulus).
+        """
+        return digest_recover(self.signature, self.modulus)
+
+    def verify(self, signed_region: bytes, cmac_key: bytes) -> bool:
+        """
+        Return ``True`` if this RSA signature, checked against the embedded
+        ``modulus``, recovers the AES-CMAC of ``signed_region`` (the body:
+        ``options`` + ``rev`` + match registers + opquads).
+
+        Uses the Zen 1-4 CMAC key by default; Zen 5 uses a different, unpublished
+        key, so Zen 5 patches will not verify unless the right ``cmac_key`` is
+        supplied.
+        """
+        digest = CMAC.new(cmac_key, msg=signed_region, ciphermod=AES).digest()
+        return pkcs1_v15_verify(self.signature, self.modulus, digest)

{amd_ucode_patch-1.0.0 → amd_ucode_patch-1.0.1}/src/amd_ucode_patch/structures/verified_header.py

@@ -3,32 +3,33 @@
 
 import struct
 from dataclasses import dataclass
-
+from amd_ucode_patch.structures.patch_level import PatchLevel
 
 
 @dataclass
 class VerifiedHeader:
-    FMT = "<BB BB I"
-    SIZE = struct.calcsize(FMT)
+    # Fields before the trailing PatchLevel.
+    FMT = "<BB BB"
+    SIZE = struct.calcsize(FMT) + PatchLevel.SIZE
 
     autorun: int
     encrypted: int
     unk0: int
     unk1: int
-    update_revision: int
+    patch_level: PatchLevel
 
     @staticmethod
-    def from_bytes(buf: bytes) -> "VerifiedHeader":
+    def from_bytes(buf: bytes, family: int | None = None) -> "VerifiedHeader":
         if len(buf) < VerifiedHeader.SIZE:
             raise ValueError("not enough bytes for AMD verified header")
-        chunk = buf[0:VerifiedHeader.SIZE]
-        vals = struct.unpack(VerifiedHeader.FMT, chunk)
+        head = struct.calcsize(VerifiedHeader.FMT)
+        vals = struct.unpack(VerifiedHeader.FMT, buf[0:head])
         return VerifiedHeader(
             autorun=vals[0],
             encrypted=vals[1],
             unk0=vals[2],
             unk1=vals[3],
-            update_revision=vals[4],
+            patch_level=PatchLevel.from_bytes(buf[head:VerifiedHeader.SIZE], family=family),
         )
 
     def to_bytes(self) -> bytes:
@@ -38,5 +39,4 @@ class VerifiedHeader:
             self.encrypted,
             self.unk0,
             self.unk1,
-            self.update_revision,
-        )
+        ) + self.patch_level.to_bytes()

amd_ucode_patch-1.0.1/src/amd_ucode_patch/utils/bcd.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+"""
+Helpers for working with packed binary-coded-decimal (BCD) values, where each
+nibble holds a single decimal digit (0-9). AMD microcode patch headers encode
+their build date this way.
+"""
+
+
+def is_bcd(value: int, num_nibbles: int) -> bool:
+    """
+    Return ``True`` if the low ``num_nibbles`` nibbles of ``value`` are all valid
+    decimal digits (0-9), i.e. the value is a well-formed packed-BCD number.
+    """
+    for i in range(num_nibbles):
+        if ((value >> (i * 4)) & 0xF) > 9:
+            return False
+    return True
+
+
+def decode_bcd(value: int, num_nibbles: int) -> int:
+    """
+    Decode the low ``num_nibbles`` nibbles of a packed-BCD ``value`` into its
+    decimal integer equivalent (e.g. ``0x2018 -> 2018``). Callers must first
+    confirm the value is valid BCD via :func:`is_bcd`.
+    """
+    result = 0
+    multiplier = 1
+    for i in range(num_nibbles):
+        result += ((value >> (i * 4)) & 0xF) * multiplier
+        multiplier *= 10
+    return result
+
+
+def encode_bcd(value: int, num_nibbles: int) -> int:
+    """
+    Encode a decimal integer ``value`` into its packed-BCD equivalent across
+    ``num_nibbles`` nibbles (e.g. ``2018 -> 0x2018``). Raises ``ValueError`` if
+    ``value`` does not fit in ``num_nibbles`` decimal digits.
+    """
+    if value < 0 or value >= 10 ** num_nibbles:
+        raise ValueError(f"{value} does not fit in {num_nibbles} BCD nibbles")
+    result = 0
+    for i in range(num_nibbles):
+        result |= (value % 10) << (i * 4)
+        value //= 10
+    return result

amd_ucode_patch-1.0.1/src/amd_ucode_patch/utils/rsa.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+"""
+Minimal RSA signature verification helpers (textbook RSA + PKCS#1 v1.5 type 1).
+
+No private-key operations and no external dependencies: verification is just a
+modular exponentiation (``pow``) plus unpadding, which is all that is needed to
+check an AMD microcode patch signature against its embedded public modulus.
+"""
+
+
+def rsa_recover(signature: bytes, modulus: bytes, exponent: int = 0x10001) -> bytes:
+    """
+    Return the RSA-recovered block ``signature ** exponent mod modulus`` as a
+    big-endian byte string the same width as ``modulus``.
+    """
+    n = int.from_bytes(modulus, "big")
+    s = int.from_bytes(signature, "big")
+    if n == 0 or s >= n:
+        raise ValueError("signature is not a residue modulo the public modulus")
+    m = pow(s, exponent, n)
+    return m.to_bytes(len(modulus), "big")
+
+
+def pkcs1_v15_unpad(block: bytes) -> bytes | None:
+    """
+    Strip PKCS#1 v1.5 block-type-1 padding (``00 01 FF..FF 00 || payload``) and
+    return the payload, or ``None`` if the padding is malformed.
+    """
+    if len(block) < 11 or block[0] != 0x00 or block[1] != 0x01:
+        return None
+    i = 2
+    while i < len(block) and block[i] == 0xFF:
+        i += 1
+    if i < 10 or i >= len(block) or block[i] != 0x00:
+        return None
+    return block[i + 1:]
+
+
+def digest_recover(signature: bytes, modulus: bytes, exponent: int = 0x10001) -> bytes | None:
+    """
+    Recover the digest this signature commits to, using only the embedded
+    public ``modulus`` (no CMAC key required): compute
+    ``signature ^ 0x10001 mod modulus`` and strip the PKCS#1 v1.5 padding.
+
+    Returns the recovered payload — the 16-byte AES-CMAC AMD signed — or
+    ``None`` if the recovered block is not well-formed PKCS#1 v1.5 (e.g. a
+    corrupt signature or wrong modulus).
+    """
+    try:
+        block = rsa_recover(signature, modulus, exponent)
+    except ValueError:
+        return None
+    return pkcs1_v15_unpad(block)
+
+
+def pkcs1_v15_verify(signature: bytes, modulus: bytes, digest: bytes,
+                     exponent: int = 0x10001) -> bool:
+    """
+    Verify a PKCS#1 v1.5 signature whose padded payload is the raw ``digest``
+    (no DigestInfo ASN.1 wrapper, as AMD uses a bare 16-byte CMAC).
+    """
+    payload = digest_recover(signature, modulus, exponent)
+    return payload is not None and payload == digest

amd_ucode_patch-1.0.0/src/amd_ucode_patch/naming.py

@@ -1,15 +0,0 @@
-#!/usr/bin/env python
-# SPDX-License-Identifier: GPL-2.0-or-later
-
-from .structures.ucode_patch import UcodePatch
-
-def ucode_patch_name(patch: UcodePatch, enc_override=None) -> str:
-    # Format should be:
-    # family<family>_cpuid<cpuid>_rev<revision>_date<yyyymmdd>_enc<ee>.bin
-    # The _enc<ee> suffix is only present when a verified header exists.
-    name = f"family{patch.header.cpu_family:02x}_cpuid{patch.header.cpuid_str}_rev{patch.header.update_revision:08x}_date{patch.header.year:04}{patch.header.month:02}{patch.header.day:02}"
-    if patch.verified_header is not None:
-        enc = patch.verified_header.encrypted if enc_override is None else enc_override
-        name += f"_enc{enc:02}"
-    name += ".bin"
-    return name

amd_ucode_patch-1.0.0/src/amd_ucode_patch/parse.py

@@ -1,9 +0,0 @@
-#!/usr/bin/env python
-# SPDX-License-Identifier: GPL-2.0-or-later
-
-from pathlib import Path
-from .structures.ucode_patch import UcodePatch
-
-def ucode_patch_parse(file: Path) -> UcodePatch:
-    with file.open("rb") as f:
-        return UcodePatch.from_bytes(f.read())

amd_ucode_patch-1.0.0/src/amd_ucode_patch/structures/ucode_patch.py

@@ -1,29 +0,0 @@
-#!/usr/bin/env python
-# SPDX-License-Identifier: GPL-2.0-or-later
-
-from dataclasses import dataclass
-from .ucode_patch_header import UcodePatchHeader
-from .verified_header import VerifiedHeader
-
-
-@dataclass
-class UcodePatch:
-    header: UcodePatchHeader
-    signature: bytes
-    public_key: bytes
-    verified_header: VerifiedHeader | None
-    body: bytes
-
-
-    @staticmethod
-    def from_bytes(buf: bytes) -> "UcodePatch":
-        header = UcodePatchHeader.from_bytes(buf)
-        verified_header = None if header.cpu_family < 0x16 else VerifiedHeader.from_bytes(buf[800::])
-        body_start_pos = UcodePatchHeader.SIZE + 256 + 512 + (0 if verified_header is None else VerifiedHeader.SIZE)
-        return UcodePatch(
-            header=header,
-            signature=buf[UcodePatchHeader.SIZE:UcodePatchHeader.SIZE+256],
-            public_key=buf[UcodePatchHeader.SIZE+256:UcodePatchHeader.SIZE+256+512],
-            verified_header=verified_header,
-            body=buf[body_start_pos::]
-        )

amd_ucode_patch-1.0.0/src/amd_ucode_patch/structures/ucode_patch_header.py

@@ -1,126 +0,0 @@
-#!/usr/bin/env python
-# SPDX-License-Identifier: GPL-2.0-or-later
-
-import struct
-from dataclasses import dataclass
-
-def _weird_hex_as_dec(x: int) -> int:
-    return int(f"{x:x}", 10)
-
-
-def _dec_as_weird_hex(x: int) -> int:
-    return int(str(x), 16)
-
-
-@dataclass
-class UcodePatchHeader:
-    '''
-    https://github.com/torvalds/linux/blob/3544d5ce36f403db6e5c994f526101c870ffe9fe/arch/x86/kernel/cpu/microcode/amd.c#L70
-    
-    Original structure:
-    struct microcode_header_amd {
-        u32	data_code;
-        u32	patch_id;
-        u16	mc_patch_data_id;
-        u8	mc_patch_data_len;
-        u8	init_flag;
-        u32	mc_patch_data_checksum;
-        u32	nb_dev_id;
-        u32	sb_dev_id;
-        u16	processor_rev_id;
-        u8	nb_rev_id;
-        u8	sb_rev_id;
-        u8	bios_api_rev;
-        u8	reserved1[3];
-        u32	match_reg[8];
-    } __packed;
-
-    data_code is in reality a date. We split that into u16, u8, u8.
-    patch_id is referred to as revision in many other places.
-    '''
-    FMT = "<HBB I HBB I II H BBBBBB"
-    SIZE = struct.calcsize(FMT)
-
-    year: int
-    day: int
-    month: int
-    update_revision: int
-    loader_id: int
-    unk0: int
-    unk1: int
-    unk2: int
-    unk3: int
-    unk4: int
-    processor_rev_id: int
-    unk5: int
-    unk6: int
-    unk7: int
-    unk8: int
-    unk9: int
-    unk10: int
-
-    @property
-    def cpu_family(self) -> int:
-        return 0xf + (self.processor_rev_id >> 12)
-
-    @property
-    def cpu_model(self) -> int:
-        return (self.processor_rev_id >> 4) & 0xf
-    
-    @property
-    def cpu_stepping(self) -> int:
-        return self.processor_rev_id & 0xf
-
-    @property
-    def cpuid_str(self) -> str:
-        hi = (self.processor_rev_id >> 8) & 0xFF
-        lo = self.processor_rev_id & 0xFF
-        return f"00{hi:02X}0F{lo:02X}"
-
-    @staticmethod
-    def from_bytes(buf: bytes) -> "UcodePatchHeader":
-        if len(buf) < UcodePatchHeader.SIZE:
-            raise ValueError("not enough bytes for AMD header")
-        chunk = buf[0:UcodePatchHeader.SIZE]
-        vals = struct.unpack(UcodePatchHeader.FMT, chunk)
-        return UcodePatchHeader(
-            year=_weird_hex_as_dec(vals[0]),
-            day=_weird_hex_as_dec(vals[1]),
-            month=_weird_hex_as_dec(vals[2]),
-            update_revision=vals[3],
-            loader_id=vals[4],
-            unk0=vals[5],
-            unk1=vals[6],
-            unk2=vals[7],
-            unk3=vals[8],
-            unk4=vals[9],
-            processor_rev_id=vals[10],
-            unk5=vals[11],
-            unk6=vals[12],
-            unk7=vals[13],
-            unk8=vals[14],
-            unk9=vals[15],
-            unk10=vals[16],
-        )
-
-    def to_bytes(self) -> bytes:
-        return struct.pack(
-            UcodePatchHeader.FMT,
-            _dec_as_weird_hex(self.year),
-            _dec_as_weird_hex(self.day),
-            _dec_as_weird_hex(self.month),
-            self.update_revision,
-            self.loader_id,
-            self.unk0,
-            self.unk1,
-            self.unk2,
-            self.unk3,
-            self.unk4,
-            self.processor_rev_id,
-            self.unk5,
-            self.unk6,
-            self.unk7,
-            self.unk8,
-            self.unk9,
-            self.unk10,
-        )