py-mspack-decoder 0.1.1__py3-none-any.whl

pac_decoder/__init__.py

@@ -0,0 +1,220 @@
+"""Pure-Python, dependency-free Microsoft Privilege Attribute Certificate decoding.
+
+Security contract:
+* ``decode_pac`` is a parser and does NOT authenticate PACs or signatures.
+* For authorization, use ``decode_completed_context`` after GSSAPI has verified
+  the PAC name attribute, or otherwise establish the trust of the raw bytes.
+* The default strict mode rejects ambiguous or malformed recognized buffers,
+  rather than returning an incomplete authorization identity.
+* ``strict=False`` is for offline diagnostics ONLY, never authorization.
+"""
+
+from __future__ import annotations
+from .binary import (
+    PACDecodeError, decode_attributes_info, decode_client_info,
+    decode_sid, decode_signature_type, decode_upn_dns_info, parse_pac,
+)
+from .claims import decode_claims_info
+from .logon import decode_device_info, decode_logon_info, decode_delegation_info
+
+BUFFER_NAMES = {
+    1: "logon_info", 2: "credential_info", 6: "server_checksum",
+    7: "kdc_checksum", 10: "client_info", 11: "constrained_delegation",
+    12: "upn_dns_info", 13: "client_claims_info", 14: "device_info",
+    15: "device_claims_info", 16: "ticket_checksum", 17: "attributes_info",
+    18: "requestor_sid", 19: "full_checksum",
+}
+SIG_NAMES = {6: "server", 7: "kdc", 16: "ticket", 19: "full"}
+# [MS-PAC] 2.4 explicitly requires recipients to ignore additional instances
+# of these known buffer types. PAC_REQUESTOR_SID (18) is deliberately omitted:
+# the published type entry requires one but does not specify how to handle
+# additional instances. Do not silently choose between different requestors.
+# https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-pac/3341cfa2-6ef5-42e0-b7bc-4544884bf399
+_IGNORABLE_DUPLICATE_TYPES = frozenset({
+    1, 2, 6, 7, 10, 11, 12, 13, 14, 15, 16, 17, 19,
+})
+_EMPTY = (
+    "sid", "sam_name", "upn", "dns_domain", "upn_dns_flags", "upn_constructed",
+    "rid", "domain_sid", "domain_name", "logon_server", "full_name",
+    "groups", "group_memberships", "primary_group_rid", "extra_sids", "resource_groups",
+    "group_count", "account_flags", "user_flags", "sub_auth_status",
+    "last_logon", "last_successful_logon", "last_failed_logon",
+    "logoff_time", "kickoff_time", "password_last_set",
+    "password_can_change", "password_must_change", "logon_count",
+    "bad_password_count", "failed_logon_count", "home_directory",
+    "home_drive", "logon_script", "profile_path", "client_name",
+    "client_auth_time", "requestor_sid", "pac_requested",
+    "pac_given_implicitly", "pac_attributes_flags", "delegation_proxy_target",
+    "delegation_transited_services", "device_info", "client_claims_present",
+    "device_claims_present", "client_claims", "device_claims",
+    "credential_info_present", "pac_signature_types", "pac_version",
+    "pac_size", "pac_buffer_types", "pac_buffer_type_ids",
+)
+
+
+def empty_pac_info() -> dict:
+    return dict.fromkeys(_EMPTY)
+
+
+def _same_name(left: str | None, right: str | None) -> bool:
+    """SAM account names are case-insensitive; UPNs are separate identifiers."""
+    return left is None or right is None or left.casefold() == right.casefold()
+
+
+def _same_upn_info(left: dict, right: dict) -> bool:
+    """Do not silently prefer a separately supplied GSS attribute over the PAC."""
+    for key in ("sid", "sam_name", "upn", "dns_domain"):
+        a, b = left.get(key), right.get(key)
+        if isinstance(a, str) and isinstance(b, str):
+            if a.casefold() != b.casefold():
+                return False
+        elif a != b:
+            return False
+    return left["upn_dns_flags"] == right["upn_dns_flags"]
+
+
+def decode_pac(raw_pac: bytes, upn_dns_attribute: bytes | None = None,
+               *, errors: list[int] | None = None, strict: bool = True,
+               require_logon: bool = False,
+               ignore_invalid_claims: bool = False,
+               include_resource_groups: bool = True) -> dict:
+    """Decode a raw MS-PAC as a dictionary; **does not authenticate it**.
+    In strict mode (default), malformed recognized buffers, conflicting
+    identity buffers, and missing/invalid LOGON_INFO (when
+    ``require_logon=True``) raise PACDecodeError. For buffer types that MS-PAC
+    2.4 explicitly says may be duplicated, only the FIRST occurrence is
+    interpreted; later ones are ignored. Duplicate PAC_REQUESTOR_SID buffers
+    remain an error because MS-PAC does not specify an ignore rule for them.
+    Unknown buffer types are retained as metadata, not interpreted.
+    No partial result is returned.
+    ``strict=False`` is ONLY for offline diagnostics. In this mode malformed
+    buffers are skipped and their type IDs are recorded in ``errors``. Its
+    output MUST NOT be used for authorization. This is intentionally explicit
+    to preserve the older diagnostic API while making normal use fail closed.
+    ``upn_dns_attribute`` may ONLY come from an *independently authenticated*
+    and complete GSSAPI name attribute. The library can't establish trust
+    when caller-provided bytes are passed directly to this function.
+
+    ``ignore_invalid_claims=True`` is an explicit compatibility mode: only
+    malformed optional client/device claims (types 13 and 15) are skipped,
+    never identity, logon, group, or other buffers. Missing claims must not
+    be treated as successful claims-based authorization.
+    ``include_resource_groups=False`` excludes only PAC_LOGON_INFO
+    resource groups from top-level ``groups`` and ``resource_groups``.
+    It does not change raw ``group_memberships``, PAC_DEVICE_INFO, or
+    ``extra_sids`` (which may contain resource-domain SIDs).
+    """
+    if (type(strict) is not bool or type(require_logon) is not bool
+            or type(ignore_invalid_claims) is not bool
+            or type(include_resource_groups) is not bool):
+        raise TypeError("PAC decoder options must be booleans")
+    pac = parse_pac(raw_pac)
+    info = empty_pac_info()
+    info["pac_size"] = pac.size
+    info["pac_version"] = pac.version
+    info["pac_buffer_type_ids"] = [buf.type_id for buf in pac.buffers]
+    info["pac_buffer_types"] = [
+        BUFFER_NAMES.get(buf.type_id, f"unknown_{buf.type_id}")
+        for buf in pac.buffers
+    ]
+    present = set(info["pac_buffer_type_ids"])
+    info["client_claims_present"] = 13 in present
+    info["device_claims_present"] = 15 in present
+    info["credential_info_present"] = 2 in present
+    info["pac_signature_types"] = {}
+
+    seen = set()
+    buffers = {}
+    for buf in pac.buffers:
+        if buf.type_id in seen:
+            # The first occurrence always wins; an invalid FIRST occurrence
+            # must still fail strict parsing (never fall back to a later one).
+            # parse_pac() already validated the directory spans of ALL buffers.
+            if (strict and buf.type_id in BUFFER_NAMES
+                    and buf.type_id not in _IGNORABLE_DUPLICATE_TYPES):
+                raise PACDecodeError(
+                    f"duplicate PAC buffer without defined ignore semantics: "
+                    f"{BUFFER_NAMES[buf.type_id]} ({buf.type_id})"
+                )
+            continue
+        seen.add(buf.type_id)
+        buffers[buf.type_id] = buf.data
+
+    # Decode BOTH versions of UPN_DNS_INFO, if present. Do not allow a
+    # separately authenticated attribute to overwrite identity silently.
+    inline = buffers.get(12)
+    try:
+        if inline is not None:
+            info.update(decode_upn_dns_info(inline))
+        if upn_dns_attribute is not None:
+            separate = decode_upn_dns_info(upn_dns_attribute)
+            if inline is not None and not _same_upn_info(info, separate):
+                raise PACDecodeError("conflicting PAC and GSSAPI UPN_DNS_INFO")
+            if inline is None:
+                info.update(separate)
+    except PACDecodeError as exc:
+        if strict:
+            raise PACDecodeError(f"invalid PAC UPN_DNS_INFO: {exc}") from exc
+        if errors is not None:
+            errors.append(12)
+        # Do not expose even the original UPN fields on an inconsistent parse.
+        for key in ("sid", "sam_name", "upn", "dns_domain", "upn_dns_flags", "upn_constructed"):
+            info[key] = None
+
+    for t, data in buffers.items():
+        if t == 12:
+            continue
+        try:
+            if t == 1:
+                logon = decode_logon_info(data, include_resource_groups=include_resource_groups)
+                if not logon.get("sid") or not isinstance(logon.get("groups"), list):
+                    raise PACDecodeError("LOGON_INFO missing account SID or group list")
+                if info["sid"] is not None and info["sid"] != logon["sid"]:
+                    raise PACDecodeError("conflicting account SIDs in PAC identity buffers")
+                if not _same_name(info["sam_name"], logon["sam_name"]):
+                    raise PACDecodeError("conflicting SAM account names in PAC identity buffers")
+                upn_sam = info["sam_name"]
+                info.update(logon)
+                if upn_sam is not None:
+                    info["sam_name"] = upn_sam
+            elif t == 10:
+                info.update(decode_client_info(data))
+            elif t == 11:
+                info.update(decode_delegation_info(data))
+            elif t == 14:
+                info["device_info"] = decode_device_info(data)
+            elif t == 17:
+                info.update(decode_attributes_info(data))
+            elif t == 18:
+                info["requestor_sid"] = decode_sid(data)
+            elif t in SIG_NAMES:
+                info["pac_signature_types"][SIG_NAMES[t]] = decode_signature_type(data)
+            elif t in (13, 15):
+                key = "client_claims" if t == 13 else "device_claims"
+                # Samba and Windows may include a zero-length claims buffer
+                # when there are no claims. There is no NDR envelope to parse.
+                # Keep *_claims_present=True and decoded claims=None.
+                if data:
+                    info[key] = decode_claims_info(data)
+        except PACDecodeError as exc:
+            if strict and not (ignore_invalid_claims and t in (13, 15)):
+                raise PACDecodeError(
+                    f"invalid PAC {BUFFER_NAMES.get(t, f'buffer {t}')} ({t}): {exc}"
+                ) from exc
+            if errors is not None:
+                errors.append(t)
+            # In diagnostic mode, never leak authorization identity from an
+            # invalid LOGON_INFO (even if UPN_DNS_INFO was decoded earlier).
+            if t == 1:
+                for field in ("groups", "group_memberships", "extra_sids", "resource_groups", "group_count"):
+                    info[field] = None
+    if require_logon and (1 not in buffers or info["sid"] is None or info["groups"] is None):
+        raise PACDecodeError("valid PAC LOGON_INFO required")
+    return info
+
+
+__all__ = [
+    "PACDecodeError", "parse_pac", "decode_sid", "decode_upn_dns_info",
+    "decode_logon_info", "decode_device_info", "decode_delegation_info",
+    "decode_pac", "empty_pac_info", "decode_claims_info",
+]

pac_decoder/binary.py

@@ -0,0 +1,170 @@
+"""Dependency-free binary primitives for Microsoft MS-PAC.
+
+No Kerberos validation is performed here. Only pass PAC data obtained from an
+*authenticated and complete* GSSAPI name attribute.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+import struct
+
+MAX_PAC_BYTES = 4 * 1024 * 1024
+MAX_PAC_ENTRIES = 16_384
+MAX_PAC_GROUPS = 65_535  # Samba-style per-array group/SID bound.
+MAX_GROUP_MEMBERSHIPS = 200_000  # Maximum number of distinct authorization group SIDs.
+MAX_SID_SUBAUTHS = 15
+
+
+class PACDecodeError(ValueError):
+    """Malformed, truncated or unsupported PAC encoding."""
+
+
+@dataclass(frozen=True)
+class PACBuffer:
+    type_id: int
+    data: bytes
+
+
+@dataclass(frozen=True)
+class PAC:
+    version: int
+    size: int
+    buffers: tuple[PACBuffer, ...]
+
+
+def parse_pac(raw: bytes) -> PAC:
+    """Validate and extract an MS-PAC PACTYPE (not an ASN.1 wrapper)."""
+    if not isinstance(raw, bytes) or not 8 <= len(raw) <= MAX_PAC_BYTES:
+        raise PACDecodeError("invalid PAC length or input type")
+    n, version = struct.unpack_from("<II", raw)
+    if n > MAX_PAC_ENTRIES or n > (len(raw) - 8) // 16:
+        raise PACDecodeError("invalid PAC directory size")
+    if version != 0:
+        raise PACDecodeError("unsupported PAC version")
+    directory_end = 8 + 16 * n
+    entries = []
+    ranges = []
+    for i in range(n):
+        type_id, size, offset = struct.unpack_from("<IIQ", raw, 8 + 16 * i)
+        if offset % 8 or offset < directory_end or offset > len(raw):
+            raise PACDecodeError("invalid PAC buffer offset")
+        if size > len(raw) - offset:
+            raise PACDecodeError("PAC buffer exceeds packet")
+        if size:
+            ranges.append((offset, offset + size))
+        entries.append((type_id, offset, size))
+    ranges.sort()
+    for previous, current in zip(ranges, ranges[1:]):
+        if previous[1] > current[0]:
+            raise PACDecodeError("overlapping PAC buffers")
+    buffers = tuple(PACBuffer(t, raw[o:o + n]) for t, o, n in entries)
+    return PAC(version=version, size=len(raw), buffers=buffers)
+
+
+def decode_sid(raw: bytes) -> str:
+    """Decode an exact self-relative binary SID, rejecting malformed SIDs."""
+    if len(raw) < 12:
+        raise PACDecodeError("SID too short")
+    revision, count = raw[0], raw[1]
+    if revision != 1 or not 1 <= count <= MAX_SID_SUBAUTHS:
+        raise PACDecodeError("unsupported SID revision or subauthority count")
+    if len(raw) != 8 + count * 4:
+        raise PACDecodeError("SID size mismatch")
+    authority = int.from_bytes(raw[2:8], "big")
+    subs = struct.unpack_from("<" + "I" * count, raw, 8)
+    return f"S-{revision}-{authority}" + "".join(f"-{n}" for n in subs)
+
+
+def filetime_to_iso(value: int) -> str | None:
+    """Convert Windows FILETIME, including sentinel values used by AD."""
+    if not 0 < value < 0x7FFFFFFFFFFFFFFF:
+        return None
+    try:
+        instant = datetime(1601, 1, 1, tzinfo=timezone.utc) + timedelta(
+            microseconds=value // 10
+        )
+    except (ValueError, OverflowError):
+        return None
+    return instant.isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def decode_upn_dns_info(data: bytes) -> dict:
+    """UPN_DNS_INFO, including optional SAM and SID (PAC buffer type 12)."""
+    if not isinstance(data, bytes) or len(data) < 12:
+        raise PACDecodeError("truncated or invalid UPN_DNS_INFO")
+    upn_length, upn_offset, dns_length, dns_offset, flags = struct.unpack_from(
+        "<HHHHI", data
+    )
+    extended = bool(flags & 0x2)
+    header_size = 20 if extended else 12
+    if len(data) < header_size:
+        raise PACDecodeError("truncated extended UPN_DNS_INFO")
+
+    def read_text(length: int, offset: int) -> str | None:
+        if not length:
+            return None
+        if length & 1 or offset < header_size or length > len(data) - offset:
+            raise PACDecodeError("invalid UPN_DNS_INFO UTF-16 span")
+        try:
+            return data[offset:offset + length].decode("utf-16-le") or None
+        except UnicodeDecodeError as exc:
+            raise PACDecodeError("invalid UPN_DNS_INFO UTF-16") from exc
+
+    result = {
+        "upn": read_text(upn_length, upn_offset),
+        "dns_domain": read_text(dns_length, dns_offset),
+        "upn_dns_flags": flags,
+        "upn_constructed": bool(flags & 1),
+        "sam_name": None,
+        "sid": None,
+    }
+    if extended:
+        sam_length, sam_offset, sid_length, sid_offset = struct.unpack_from(
+            "<HHHH", data, 12
+        )
+        result["sam_name"] = read_text(sam_length, sam_offset)
+        if sid_length:
+            if sid_offset < header_size or sid_length > len(data) - sid_offset:
+                raise PACDecodeError("invalid UPN_DNS_INFO SID span")
+            result["sid"] = decode_sid(data[sid_offset:sid_offset + sid_length])
+    return result
+
+
+def decode_client_info(data: bytes) -> dict:
+    if len(data) < 10:
+        raise PACDecodeError("truncated PAC_CLIENT_INFO")
+    filetime, length = struct.unpack_from("<QH", data)
+    if length & 1 or length > len(data) - 10:
+        raise PACDecodeError("invalid client name length")
+    try:
+        name = data[10:10 + length].decode("utf-16-le").rstrip("\x00")
+    except UnicodeDecodeError as exc:
+        raise PACDecodeError("invalid client name UTF-16") from exc
+    return {"client_name": name or None, "client_auth_time": filetime_to_iso(filetime)}
+
+
+def decode_attributes_info(data: bytes) -> dict:
+    if len(data) < 8:
+        raise PACDecodeError("truncated PAC_ATTRIBUTES_INFO")
+    nbits = struct.unpack_from("<I", data)[0]
+    if nbits > 256:
+        raise PACDecodeError("unsupported PAC flag length")
+    needed = ((nbits + 31) // 32) * 4
+    if needed > len(data) - 4:
+        raise PACDecodeError("truncated PAC_ATTRIBUTES_INFO flags")
+    flags = int.from_bytes(data[4:4 + needed], "little")
+    if nbits:
+        flags &= (1 << nbits) - 1
+    return {
+        "pac_attributes_flags": flags,
+        "pac_requested": bool(flags & 1),
+        "pac_given_implicitly": bool(flags & 2),
+    }
+
+
+def decode_signature_type(data: bytes) -> int:
+    if len(data) < 4:
+        raise PACDecodeError("truncated PAC_SIGNATURE_DATA")
+    return struct.unpack_from("<i", data)[0]

pac_decoder/claims.py

@@ -0,0 +1,130 @@
+"""MS-ADTS CLAIMS_SET_METADATA and CLAIMS_SET, bounded NDR32 decoding.
+
+No claims are returned unless the complete structure, including deferred
+pointers and every value, was decoded successfully. No cryptography here.
+"""
+import struct
+from .binary import PACDecodeError, MAX_PAC_ENTRIES, MAX_PAC_BYTES
+from .ndr import ndr_serialized_pointer
+from .compression import decompress_claims, MAX_CLAIMS_BYTES
+
+_TYPE_NAMES = {1: 'int64', 2: 'uint64', 3: 'string', 6: 'boolean'}
+_SOURCE_NAMES = {1: 'ad', 2: 'certificate'}
+
+
+def _array(r, pointer: int, count: int, *, bound=MAX_PAC_ENTRIES) -> bool:
+    if not 0 <= count <= bound:
+        raise PACDecodeError('excessive claims array count')
+    if not pointer:
+        if count:
+            raise PACDecodeError('nonempty null claims array')
+        return False
+    if r.u32() != count:
+        raise PACDecodeError('claims conformance count mismatch')
+    return True
+
+
+def _blob(r, pointer: int, count: int, *, bound=MAX_CLAIMS_BYTES) -> bytes:
+    return r.bytes(count) if _array(r, pointer, count, bound=bound) else b''
+
+
+def _string(r) -> str:
+    maximum, offset, actual = r.u32(), r.u32(), r.u32()
+    if (not actual or offset != 0 or actual > maximum
+            or maximum > MAX_CLAIMS_BYTES // 2):
+        raise PACDecodeError('invalid claims string bounds')
+    raw = r.bytes(actual * 2, 2)
+    if raw[-2:] != b'\0\0':
+        raise PACDecodeError('unterminated claims string')
+    try:
+        result = raw[:-2].decode('utf-16-le')
+    except UnicodeDecodeError as exc:
+        raise PACDecodeError('invalid UTF-16 claim') from exc
+    if '\0' in result:
+        raise PACDecodeError('embedded NUL in claim string')
+    return result
+
+
+def _finish(r) -> None:
+    if len(r.data) - r.offset > 7:
+        raise PACDecodeError('unconsumed claims payload')
+
+
+def decode_claims_set(data: bytes) -> list[dict]:
+    """Return source-tagged claim arrays from a serialized CLAIMS_SET."""
+    if not isinstance(data, bytes) or len(data) > MAX_CLAIMS_BYTES:
+        raise PACDecodeError('invalid claims input')
+    r = ndr_serialized_pointer(data)
+    count, arrays_ptr = r.u32(), r.u32()
+    r.u16()
+    reserved_size, reserved_ptr = r.u32(), r.u32()
+    arrays = []
+    total_entries = total_values = 0
+    if _array(r, arrays_ptr, count):
+        headers = [(r.u16(), r.u32(), r.u32()) for _ in range(count)]
+        for source, claim_count, entries_ptr in headers:
+            total_entries += claim_count
+            if total_entries > MAX_PAC_ENTRIES:
+                raise PACDecodeError('excessive total claims count')
+            entries = []
+            if _array(r, entries_ptr, claim_count):
+                fixed = []
+                for _ in range(claim_count):
+                    id_ptr, typ, discriminant = r.u32(), r.u16(), r.u16()
+                    if typ != discriminant or typ not in _TYPE_NAMES:
+                        raise PACDecodeError('unsupported claims union')
+                    n, value_ptr = r.u32(), r.u32()
+                    total_values += n
+                    if not id_ptr or not n or total_values > MAX_PAC_ENTRIES:
+                        raise PACDecodeError('invalid claim identifier/value count')
+                    fixed.append((typ, n, value_ptr))
+                for typ, n, value_ptr in fixed:
+                    identifier = _string(r)
+                    if not identifier:
+                        raise PACDecodeError('empty claim identifier')
+                    if not _array(r, value_ptr, n):
+                        raise PACDecodeError('null claim value array')
+                    if typ == 3:
+                        refs = [r.u32() for _ in range(n)]
+                        if not all(refs):
+                            raise PACDecodeError('null claim string pointer')
+                        values = [_string(r) for _ in refs]
+                    else:
+                        raw = r.bytes(n * 8, 8)
+                        values = list(struct.unpack('<' + ('q' if typ == 1 else 'Q') * n, raw))
+                        if typ == 6:
+                            if any(value not in (0, 1) for value in values):
+                                raise PACDecodeError('invalid boolean claim value')
+                            values = [bool(value) for value in values]
+                    entries.append({'id': identifier, 'type': _TYPE_NAMES[typ],
+                                    'type_id': typ, 'values': values})
+            arrays.append({'source': _SOURCE_NAMES.get(source, 'unknown'),
+                           'source_id': source, 'claims': entries})
+    _blob(r, reserved_ptr, reserved_size)
+    _finish(r)
+    return arrays
+
+
+def decode_claims_info(data: bytes) -> dict:
+    """Decode PAC buffers 13/15 (serialized CLAIMS_SET_METADATA).
+
+    Shape: {compression_format, uncompressed_size, arrays: [{source,
+    source_id, claims: [{id, type, type_id, values}]}]}. Unknown source IDs are
+    preserved numerically, never mislabeled as AD or certificate claims.
+    """
+    if not isinstance(data, bytes) or len(data) > MAX_PAC_BYTES:
+        raise PACDecodeError('invalid claims metadata input')
+    r = ndr_serialized_pointer(data)
+    size, claims_ptr, compression = r.u32(), r.u32(), r.u16()
+    uncompressed_size = r.u32()
+    r.u16()
+    reserved_size, reserved_ptr = r.u32(), r.u32()
+    if not claims_ptr or size == 0:
+        raise PACDecodeError('missing encoded CLAIMS_SET')
+    compressed = _blob(r, claims_ptr, size, bound=MAX_PAC_BYTES)
+    _blob(r, reserved_ptr, reserved_size)
+    _finish(r)
+    plain = decompress_claims(compressed, compression, uncompressed_size)
+    arrays = decode_claims_set(plain)
+    return {'compression_format': compression,
+            'uncompressed_size': uncompressed_size, 'arrays': arrays}

pac_decoder/compression.py

@@ -0,0 +1,229 @@
+"""Bounded MS-XCA decompression using only the Python standard library.
+
+Algorithms: NONE (0), LZNT1 (2), XPRESS/LZ77 (3), XPRESS_HUFF (4).
+The caller must provide the expected output size from CLAIMS_SET_METADATA.
+See SOURCES.md in the repository root for protocol references.
+"""
+import struct
+from .binary import PACDecodeError, MAX_PAC_BYTES
+
+MAX_CLAIMS_BYTES = 4 * 1024 * 1024
+
+
+class _Input:
+    def __init__(self, data: bytes):
+        self.data = data
+        self.pos = 0
+
+    def read(self, size: int) -> bytes:
+        if size < 0 or size > len(self.data) - self.pos:
+            raise PACDecodeError("truncated compressed claims")
+        result = self.data[self.pos:self.pos + size]
+        self.pos += size
+        return result
+
+    def u8(self) -> int:
+        return self.read(1)[0]
+
+    def u16(self) -> int:
+        return struct.unpack('<H', self.read(2))[0]
+
+    def u32(self) -> int:
+        return struct.unpack('<I', self.read(4))[0]
+
+
+def _match(out: bytearray, distance: int, length: int, limit: int,
+           window_start: int = 0) -> None:
+    if distance < 1 or distance > len(out) - window_start:
+        raise PACDecodeError("invalid compression back-reference")
+    if length < 3 or length > limit - len(out):
+        raise PACDecodeError("decompressed claims exceed expected size")
+    period = bytes(out[len(out) - distance:])
+    if length <= distance:
+        out.extend(period[:length])
+    else:
+        repetitions, remainder = divmod(length, distance)
+        out.extend(period * repetitions)
+        out.extend(period[:remainder])
+
+
+def _lznt1(data: bytes, expected: int) -> bytes:
+    src, out = _Input(data), bytearray()
+    while src.pos < len(data):
+        header = src.u16()
+        if header == 0:
+            if any(data[src.pos:]):
+                raise PACDecodeError("nonzero data after LZNT1 terminator")
+            break
+        if header & 0x7000 != 0x3000:
+            raise PACDecodeError("invalid LZNT1 chunk signature")
+        chunk = _Input(src.read((header & 0x0FFF) + 1))
+        start = len(out)
+        limit = min(expected, start + 4096)
+        if not header & 0x8000:
+            if len(chunk.data) > limit - len(out):
+                raise PACDecodeError("oversized uncompressed LZNT1 chunk")
+            out.extend(chunk.data)
+            continue
+        while chunk.pos < len(chunk.data):
+            flags = chunk.u8()
+            for bit in range(8):
+                if chunk.pos == len(chunk.data):
+                    break
+                if flags & (1 << bit):
+                    token = chunk.u16()
+                    shift, mask = 12, 0x0FFF
+                    position = len(out) - start - 1
+                    while position >= 16:
+                        mask >>= 1
+                        shift -= 1
+                        position >>= 1
+                    _match(out, (token >> shift) + 1, (token & mask) + 3,
+                           limit, start)
+                else:
+                    if len(out) >= limit:
+                        raise PACDecodeError("oversized LZNT1 chunk")
+                    out.append(chunk.u8())
+    return bytes(out)
+
+
+def _xpress(data: bytes, expected: int) -> bytes:
+    src, out = _Input(data), bytearray()
+    flags = bits = 0
+    pending_nibble = None
+    while len(out) < expected:
+        if bits == 0:
+            flags, bits = src.u32(), 32
+        bits -= 1
+        if not flags & (1 << bits):
+            out.append(src.u8())
+            continue
+        token = src.u16()
+        distance, length = (token >> 3) + 1, token & 7
+        if length == 7:
+            if pending_nibble is None:
+                packed = src.u8()
+                length, pending_nibble = packed & 15, packed >> 4
+            else:
+                length, pending_nibble = pending_nibble, None
+            if length == 15:
+                length = src.u8()
+                if length == 255:
+                    length = src.u16()
+                    if length == 0:
+                        length = src.u32()
+                    if length < 22:
+                        raise PACDecodeError("invalid extended XPRESS length")
+                    length -= 22
+                length += 15
+            length += 7
+        _match(out, distance, length + 3, expected)
+    if src.pos != len(data):
+        if not (bits == 0 and data[src.pos:] == b'\xff' * 4):
+            raise PACDecodeError("trailing XPRESS input")
+    return bytes(out)
+
+
+class _Bits:
+    """MS-XCA's two-word look-ahead, sharing input with long match lengths."""
+
+    def __init__(self, src: _Input):
+        self.src = src
+        self.register = (src.u16() << 16) | src.u16()
+        self.extra = 16
+
+    def take(self, count: int) -> int:
+        if not 0 <= count <= 15:
+            raise PACDecodeError("invalid Huffman bit count")
+        value = self.register >> (32 - count) if count else 0
+        self.register = (self.register << count) & 0xFFFFFFFF
+        self.extra -= count
+        if self.extra < 0:
+            self.register |= self.src.u16() << -self.extra
+            self.extra += 16
+        return value
+
+
+def _huffman_table(raw: bytes):
+    lengths = [n for byte in raw for n in (byte & 15, byte >> 4)]
+    table = []
+    for length in range(1, 16):
+        for symbol, nbits in enumerate(lengths):
+            if nbits != length:
+                continue
+            count = 1 << (15 - length)
+            if count > 32768 - len(table):
+                raise PACDecodeError("oversubscribed Huffman tree")
+            table.extend([symbol] * count)
+    if len(table) != 32768:
+        raise PACDecodeError("incomplete Huffman tree")
+    return lengths, table
+
+
+def _xpress_huff(data: bytes, expected: int) -> bytes:
+    src, out = _Input(data), bytearray()
+    while len(out) < expected:
+        lengths, table = _huffman_table(src.read(256))
+        bits = _Bits(src)
+        block_end = min(expected, len(out) + 65536)
+        while len(out) < block_end:
+            symbol = table[bits.register >> 17]
+            bits.take(lengths[symbol])
+            if symbol < 256:
+                out.append(symbol)
+                continue
+            code = symbol - 256
+            distance_bits, length = code >> 4, code & 15
+            if length == 15:
+                length = src.u8()
+                if length == 255:
+                    length = src.u16()
+                    if length == 0:
+                        length = src.u32()
+                    if length < 15:
+                        raise PACDecodeError("invalid extended Huffman length")
+                    length -= 15
+                length += 15
+            distance = (1 << distance_bits) + bits.take(distance_bits)
+            _match(out, distance, length + 3, expected)
+    if src.pos != len(data):
+        symbol = table[bits.register >> 17]
+        if symbol != 256:
+            raise PACDecodeError("missing Huffman end marker")
+        bits.take(lengths[symbol])
+        if src.pos != len(data):
+            raise PACDecodeError("trailing Huffman input")
+    return bytes(out)
+
+
+def decompress_claims(data: bytes, format_id: int, expected_size: int) -> bytes:
+    """Return exactly expected_size bytes or raise PACDecodeError.
+
+    This is a decoder, not an authentication function; never use its result
+    to trust an unsigned PAC.
+    """
+    if (not isinstance(data, bytes) or len(data) > MAX_PAC_BYTES
+            or type(expected_size) is not int
+            or not 0 <= expected_size <= MAX_CLAIMS_BYTES):
+        raise PACDecodeError("invalid claims decompression size")
+    if expected_size == 0:
+        # Avoid interpreting a nonempty compressed stream when no output is
+        # expected (the XPRESS-Huffman decoder would have no symbol table).
+        if format_id not in (0, 2, 3, 4):
+            raise PACDecodeError("unsupported claims compression format")
+        if data:
+            raise PACDecodeError("nonempty compressed input for zero-size claims")
+        return b''
+    if format_id == 0:
+        result = data
+    elif format_id == 2:
+        result = _lznt1(data, expected_size)
+    elif format_id == 3:
+        result = _xpress(data, expected_size)
+    elif format_id == 4:
+        result = _xpress_huff(data, expected_size)
+    else:
+        raise PACDecodeError("unsupported claims compression format")
+    if len(result) != expected_size:
+        raise PACDecodeError("claims decompression size mismatch")
+    return result

pac_decoder/gssapi_helpers.py

@@ -0,0 +1,97 @@
+"""Read an authenticated MS-PAC from a completed Kerberos GSSAPI acceptor.
+
+This module does not import python-gssapi at import time. GSSAPI performs the
+PAC verification; this parser must never be given unchecked attributes.
+"""
+from __future__ import annotations
+
+from . import PACDecodeError, decode_pac
+from .binary import MAX_PAC_BYTES
+
+_KERBEROS_MECH = "1.2.840.113554.1.2.2"
+
+
+class PACAttributeError(PACDecodeError):
+    """An acceptor context has no usable, authenticated PAC name attribute."""
+
+
+def _attribute_value(name: object, key: str, *, required: bool) -> bytes | None:
+    """Extract a *single* authenticated, complete RFC 6680 name attribute."""
+    try:
+        attributes = name.attributes
+        if attributes is None:
+            raise PACAttributeError("GSSAPI name attributes are unavailable")
+        # The public Name.attributes mapping may raise a native GSSAPI error
+        # rather than KeyError when fetching a missing attribute. Enumerate
+        # first so the absence of an optional attribute is unambiguous.
+        keys = list(attributes.keys())
+        if key in keys:
+            lookup_key = key
+        elif key.encode("ascii") in keys:
+            lookup_key = key.encode("ascii")
+        else:
+            if required:
+                raise PACAttributeError(f"missing GSSAPI name attribute: {key}")
+            return None
+        attribute = attributes[lookup_key]
+    except PACAttributeError:
+        raise
+    except Exception as exc:
+        raise PACAttributeError(f"unable to obtain GSSAPI name attribute: {key}") from exc
+    if not getattr(attribute, "authenticated", False):
+        raise PACAttributeError(f"unauthenticated GSSAPI name attribute: {key}")
+    if not getattr(attribute, "complete", False):
+        raise PACAttributeError(f"incomplete GSSAPI name attribute: {key}")
+    try:
+        values = list(attribute.values)
+    except (AttributeError, TypeError) as exc:
+        raise PACAttributeError(f"invalid GSSAPI name attribute values: {key}") from exc
+    if len(values) != 1 or type(values[0]) is not bytes:
+        raise PACAttributeError(f"expected exactly one binary GSSAPI attribute: {key}")
+    if not 0 < len(values[0]) <= MAX_PAC_BYTES:
+        raise PACAttributeError(f"invalid GSSAPI name attribute size: {key}")
+    return values[0]
+
+def decode_completed_context(context: object, *, errors: list[int] | None = None,
+                             require_logon: bool = True,
+                             ignore_invalid_claims: bool = False,
+                             include_resource_groups: bool = True) -> dict:
+    """Decode the PAC of a completed **Kerberos acceptor** context.
+    Rejects incomplete contexts, non-Kerberos mechanisms, unauthenticated or
+    incomplete PAC attributes and malformed or ambiguous PAC structures.
+    ``require_logon=True`` ensures the identity and group set are complete.
+    No PAC cryptography is implemented in this package; the verification is
+    delegated to the underlying GSSAPI / Kerberos implementation.
+
+    ``ignore_invalid_claims`` can preserve valid identity and groups when an
+    optional client/device claims buffer is malformed. Never authorize based
+    on claims whose decoded value is None.
+    ``include_resource_groups=False`` excludes only PAC_LOGON_INFO
+    resource groups from top-level authorization lists. Device groups
+    and ExtraSids are unaffected.
+    """
+    if not getattr(context, "complete", False):
+        raise PACAttributeError("GSSAPI security context is not complete")
+    if getattr(context, "locally_initiated", None) is not False:
+        raise PACAttributeError("expected a GSSAPI acceptor, not initiator")
+    try:
+        mechanism = context.mech
+    except Exception as exc:
+        raise PACAttributeError("unable to determine negotiated GSSAPI mechanism") from exc
+    if getattr(mechanism, "dotted_form", None) != _KERBEROS_MECH:
+        raise PACAttributeError("GSSAPI mechanism is not Kerberos")
+    try:
+        name = context.initiator_name
+    except Exception as exc:
+        raise PACAttributeError("GSSAPI initiator name is unavailable") from exc
+    if name is None:
+        raise PACAttributeError("GSSAPI initiator name is unavailable")
+    pac = _attribute_value(name, "urn:mspac:", required=True)
+    upn = _attribute_value(name, "urn:mspac:upn-dns-info", required=False)
+    return decode_pac(pac, upn_dns_attribute=upn,
+                      errors=errors, strict=True, require_logon=require_logon,
+                      ignore_invalid_claims=ignore_invalid_claims,
+                      include_resource_groups=include_resource_groups)
+
+
+__all__ = ["PACAttributeError", "decode_completed_context"]

pac_decoder/logon.py

@@ -0,0 +1,247 @@
+"""Specialized NDR32 decoders for PAC_LOGON_INFO and PAC_DEVICE_INFO."""
+
+from __future__ import annotations
+
+from .binary import PACDecodeError, filetime_to_iso, MAX_PAC_ENTRIES, MAX_GROUP_MEMBERSHIPS, MAX_SID_SUBAUTHS
+from .ndr import ndr_serialized_pointer
+
+_ENABLED = 0x00000004
+_DENY_ONLY = 0x00000010
+_NETLOGON_EXTRA_SIDS = 0x00000020
+_NETLOGON_RESOURCE_GROUPS = 0x00000200
+
+
+def _include(flags: int) -> bool:
+    return bool(flags & _ENABLED) and not bool(flags & _DENY_ONLY)
+
+
+def _valid_rid(rid: int) -> bool:
+    return 0 < rid <= 0xFFFFFFFF
+
+
+def _append_rid(domain_sid: str, rid: int) -> str:
+    if domain_sid.count("-") >= MAX_SID_SUBAUTHS + 2:
+        raise PACDecodeError("SID exceeds maximum subauthorities after appending RID")
+    return f"{domain_sid}-{rid}"
+
+
+def _rid_sids(domain_sid: str | None, memberships: list[tuple[int, int]]) -> list[str]:
+    if not domain_sid:
+        if memberships:
+            raise PACDecodeError("group RIDs without domain SID")
+        return []
+    if any(not _valid_rid(rid) for rid, _ in memberships):
+        raise PACDecodeError("invalid group RID")
+    if memberships and domain_sid.count("-") >= MAX_SID_SUBAUTHS + 2:
+        raise PACDecodeError("SID exceeds maximum subauthorities after appending RID")
+    return [f"{domain_sid}-{rid}" for rid, flags in memberships
+            if _include(flags)]
+
+
+def _extra_sids(entries: list[tuple[str | None, int]]) -> list[str]:
+    return [sid for sid, flags in entries if sid and _include(flags)]
+
+
+def _dedupe(*sublists: list[str]) -> list[str]:
+    unique = []
+    seen = set()
+    for sublist in sublists:
+        for value in sublist:
+            if value not in seen:
+                seen.add(value)
+                unique.append(value)
+                if len(unique) > MAX_GROUP_MEMBERSHIPS:
+                    raise PACDecodeError("too many combined authorization groups")
+    return unique
+
+
+def decode_logon_info(data: bytes, *, include_resource_groups: bool = True) -> dict:
+    """Decode KERB_VALIDATION_INFO, returning *no* session keys or secrets.
+
+    Results must only be used for authorization if the enclosing GSSAPI PAC
+    attribute was authenticated and this function returned successfully.
+    ``group_memberships`` preserves raw per-entry attributes; ``groups`` is
+    the filtered authorization list. The primary group has no PAC attributes.
+    ``include_resource_groups=False`` filters only ResourceGroupIds from
+    ``groups`` and ``resource_groups``, not ``extra_sids`` or raw metadata.
+    """
+    if type(include_resource_groups) is not bool:
+        raise TypeError("include_resource_groups must be a boolean")
+    r = ndr_serialized_pointer(data)
+    dates = [r.filetime() for _ in range(6)]
+    first_names = [r.unicode_header() for _ in range(6)]
+    logon_count, bad_password_count = r.u16(), r.u16()
+    rid, primary_gid, group_count, group_ref, user_flags = (
+        r.u32(), r.u32(), r.u32(), r.u32(), r.u32()
+    )
+    r.bytes(16)  # UserSessionKey: intentionally ignored.
+    server_name_hdr, domain_name_hdr = r.unicode_header(), r.unicode_header()
+    domain_sid_ref = r.u32()
+    r.bytes(8)  # LMKey / Reserved1: never expose.
+    account_flags = r.u32()
+    reserved3 = [r.u32() for _ in range(7)]
+    sid_count, extra_ref, resource_domain_ref, resource_count, resource_ref = (
+        r.u32(), r.u32(), r.u32(), r.u32(), r.u32()
+    )
+    if (sid_count or extra_ref) and not (user_flags & _NETLOGON_EXTRA_SIDS):
+        raise PACDecodeError("ExtraSids without NETLOGON_EXTRA_SIDS flag")
+    if ((resource_domain_ref or resource_count or resource_ref)
+            and not (user_flags & _NETLOGON_RESOURCE_GROUPS)):
+        raise PACDecodeError("resource groups without NETLOGON_RESOURCE_GROUPS flag")
+    names = [r.unicode_value(h) for h in first_names]
+    memberships = r.group_array(group_ref, group_count)
+    server_name = r.unicode_value(server_name_hdr)
+    domain_name = r.unicode_value(domain_name_hdr)
+    domain_sid = r.sid_pointer(domain_sid_ref)
+    extra_entries = r.sid_and_attributes_array(extra_ref, sid_count)
+    resource_domain_sid = r.sid_pointer(resource_domain_ref)
+    resource_entries = r.group_array(resource_ref, resource_count)
+    if memberships and not domain_sid:
+        raise PACDecodeError("group RIDs without account domain SID")
+    if resource_entries and not resource_domain_sid:
+        raise PACDecodeError("resource RIDs without resource domain SID")
+    if len(r.data) - r.offset > 7:
+        raise PACDecodeError("unconsumed LOGON_INFO payload")
+    if not domain_sid:
+        raise PACDecodeError("LOGON_INFO missing account domain SID")
+    if not _valid_rid(primary_gid):
+        raise PACDecodeError("LOGON_INFO invalid primary group RID")
+    if rid == 0 and not extra_entries:
+        raise PACDecodeError("LOGON_INFO zero user RID without account ExtraSID")
+    normal_groups = _rid_sids(domain_sid, memberships)
+    account_extra = extra_entries[0][0] if rid == 0 and extra_entries else None
+    group_extras = extra_entries[1:] if rid == 0 else extra_entries
+    extra_sids = _dedupe(_extra_sids(group_extras))
+    resource_groups = _dedupe(_rid_sids(resource_domain_sid, resource_entries))
+    primary_sid = _append_rid(domain_sid, primary_gid)
+    user_sid = _append_rid(domain_sid, rid) if _valid_rid(rid) else None
+    if rid == 0 and extra_entries:
+        user_sid = account_extra
+    if not user_sid:
+        raise PACDecodeError("LOGON_INFO missing account SID")
+    groups = _dedupe(
+        [primary_sid], normal_groups, extra_sids,
+        resource_groups if include_resource_groups else []
+    )
+    denied = {f"{domain_sid}-{item}" for item, flags in memberships
+              if domain_sid and flags & _DENY_ONLY}
+    denied.update(sid for sid, flags in group_extras if sid and flags & _DENY_ONLY)
+    if include_resource_groups:
+        denied.update(f"{resource_domain_sid}-{item}" for item, flags in resource_entries
+                      if resource_domain_sid and flags & _DENY_ONLY)
+    groups = [sid for sid in groups if sid not in denied]
+    extra_sids = [sid for sid in extra_sids if sid not in denied]
+    resource_groups = ([sid for sid in resource_groups if sid not in denied]
+                       if include_resource_groups else [])
+    return {
+        "sid": user_sid,
+        "sam_name": names[0],
+        "rid": rid,
+        "domain_sid": domain_sid,
+        "domain_name": domain_name,
+        "logon_server": server_name,
+        "full_name": names[1],
+        "logon_script": names[2],
+        "profile_path": names[3],
+        "home_directory": names[4],
+        "home_drive": names[5],
+        "groups": groups,
+        "group_memberships": (
+            [{"sid": f"{domain_sid}-{group_rid}", "attributes": attrs,
+              "source": "account_domain"} for group_rid, attrs in memberships]
+            + [{"sid": sid, "attributes": attrs, "source": "extra"}
+               for sid, attrs in group_extras]
+            + [{"sid": f"{resource_domain_sid}-{group_rid}", "attributes": attrs,
+                "source": "resource"} for group_rid, attrs in resource_entries]
+        ),
+        "primary_group_rid": primary_gid,
+        "extra_sids": extra_sids,
+        "resource_groups": resource_groups,
+        "group_count": len(groups),
+        "account_flags": account_flags,
+        "user_flags": user_flags,
+        "sub_auth_status": reserved3[0],
+        "last_logon": filetime_to_iso(dates[0]),
+        "logoff_time": filetime_to_iso(dates[1]),
+        "kickoff_time": filetime_to_iso(dates[2]),
+        "password_last_set": filetime_to_iso(dates[3]),
+        "password_can_change": filetime_to_iso(dates[4]),
+        "password_must_change": filetime_to_iso(dates[5]),
+        "last_successful_logon": filetime_to_iso(reserved3[1] | (reserved3[2] << 32)),
+        "last_failed_logon": filetime_to_iso(reserved3[3] | (reserved3[4] << 32)),
+        "failed_logon_count": reserved3[5],
+        "logon_count": logon_count,
+        "bad_password_count": bad_password_count,
+    }
+
+
+def decode_device_info(data: bytes) -> dict:
+    """Decode the PAC_DEVICE_INFO account, extra SID and domain-group lists."""
+    r = ndr_serialized_pointer(data)
+    rid, primary_gid, domain_sid_ref, group_count, group_ref = (
+        r.u32(), r.u32(), r.u32(), r.u32(), r.u32()
+    )
+    sid_count, sid_ref, domain_count, domains_ref = (
+        r.u32(), r.u32(), r.u32(), r.u32()
+    )
+    domain_sid = r.sid_pointer(domain_sid_ref)
+    normal = r.group_array(group_ref, group_count)
+    extras = r.sid_and_attributes_array(sid_ref, sid_count)
+    domains = r.domain_groups_array(domains_ref, domain_count)
+    if normal and not domain_sid:
+        raise PACDecodeError("device group RIDs without domain SID")
+    if any(groups and not sid for sid, groups in domains):
+        raise PACDecodeError("device resource RIDs without domain SID")
+    if len(r.data) - r.offset > 7:
+        raise PACDecodeError("unconsumed DEVICE_INFO payload")
+    if not domain_sid or not _valid_rid(rid) or not _valid_rid(primary_gid):
+        raise PACDecodeError("DEVICE_INFO missing or invalid account SID/group")
+    group_sids = _rid_sids(domain_sid, normal)
+    extra_sids = _dedupe(_extra_sids(extras))
+    resource_sids = _dedupe(*[_rid_sids(sid, groups) for sid, groups in domains])
+    primary_sid = _append_rid(domain_sid, primary_gid)
+    device_sid = _append_rid(domain_sid, rid)
+    return {
+        "sid": device_sid,
+        "rid": rid,
+        "domain_sid": domain_sid,
+        "primary_group_rid": primary_gid,
+        "extra_sids": extra_sids,
+        "resource_groups": resource_sids,
+        "group_memberships": (
+            [{"sid": f"{domain_sid}-{group_rid}", "attributes": attrs,
+              "source": "account_domain"} for group_rid, attrs in normal]
+            + [{"sid": sid, "attributes": attrs, "source": "extra"}
+               for sid, attrs in extras]
+            + [{"sid": f"{resource_domain_sid}-{group_rid}", "attributes": attrs,
+                "source": "resource"} for resource_domain_sid, entries in domains
+               for group_rid, attrs in entries]
+        ),
+        "groups": _dedupe(
+            [primary_sid] if primary_sid else [], group_sids, extra_sids, resource_sids
+        ),
+    }
+
+
+def decode_delegation_info(data: bytes) -> dict:
+    """Decode the S4U_DELEGATION_INFO target and transited service names."""
+    r = ndr_serialized_pointer(data)
+    proxy_header = r.unicode_header()
+    count, services_ref = r.u32(), r.u32()
+    if count > MAX_PAC_ENTRIES:
+        raise PACDecodeError("excessive transited services")
+    proxy = r.unicode_value(proxy_header)
+    if services_ref:
+        maximum = r.u32()
+        if maximum != count or count > (len(r.data) - r.offset) // 8:
+            raise PACDecodeError("invalid transited services array")
+        headers = [r.unicode_header() for _ in range(count)]
+        services = [r.unicode_value(header) for header in headers]
+    elif count:
+        raise PACDecodeError("null transited services pointer with nonzero count")
+    else:
+        services = []
+    return {
+        "delegation_proxy_target": proxy,
+        "delegation_transited_services": [name for name in services if name],
+    }

pac_decoder/ndr.py

@@ -0,0 +1,135 @@
+"""Small, strictly bounded NDR32 reader for MS-PAC structures.
+
+This is *not* a generic DCE/RPC unmarshalling implementation. Only the
+pointer/array/string forms used by PAC_LOGON_INFO and PAC_DEVICE_INFO are
+supported. Incoming lengths are bounded before allocation or iteration.
+"""
+
+from __future__ import annotations
+
+import struct
+from .binary import PACDecodeError, MAX_PAC_ENTRIES, MAX_PAC_GROUPS, MAX_SID_SUBAUTHS
+
+
+class NDRReader:
+    def __init__(self, data: bytes):
+        self.data = memoryview(data)
+        self.offset = 0
+
+    def align(self, n: int) -> None:
+        self.offset = (self.offset + n - 1) & ~(n - 1)
+        if self.offset > len(self.data):
+            raise PACDecodeError("NDR alignment exceeds buffer")
+
+    def bytes(self, size: int, alignment: int = 1) -> bytes:
+        self.align(alignment)
+        if size < 0 or size > len(self.data) - self.offset:
+            raise PACDecodeError("truncated NDR payload")
+        result = bytes(self.data[self.offset:self.offset + size])
+        self.offset += size
+        return result
+
+    def u16(self) -> int:
+        return struct.unpack("<H", self.bytes(2, 2))[0]
+
+    def u32(self) -> int:
+        return struct.unpack("<I", self.bytes(4, 4))[0]
+
+    def filetime(self) -> int:
+        low = self.u32()
+        return low | (self.u32() << 32)
+
+    def unicode_header(self) -> tuple[int, int, int]:
+        length, max_length, referent = self.u16(), self.u16(), self.u32()
+        if length & 1 or max_length & 1 or length > max_length:
+            raise PACDecodeError("invalid RPC_UNICODE_STRING length")
+        if length and not referent:
+            raise PACDecodeError("nonempty null RPC_UNICODE_STRING")
+        return length, max_length, referent
+
+    def unicode_value(self, header: tuple[int, int, int]) -> str | None:
+        length, max_length, referent = header
+        if not referent:
+            return None
+        maximum, offset, actual = self.u32(), self.u32(), self.u32()
+        if offset > maximum or actual > maximum - offset:
+            raise PACDecodeError("invalid NDR string conformance")
+        if maximum > len(self.data) // 2 or actual > len(self.data) // 2:
+            raise PACDecodeError("oversized NDR string")
+        if length > actual * 2 or length > max_length:
+            raise PACDecodeError("NDR string length mismatch")
+        raw = self.bytes(actual * 2, 2)
+        try:
+            return raw[:length].decode("utf-16-le").rstrip("\x00") or None
+        except UnicodeDecodeError as exc:
+            raise PACDecodeError("invalid NDR Unicode string") from exc
+
+    def group_array(self, referent: int, count: int) -> list[tuple[int, int]]:
+        if count > MAX_PAC_GROUPS:
+            raise PACDecodeError("excessive PAC group count")
+        if not referent:
+            if count:
+                raise PACDecodeError("null PAC group pointer with nonzero count")
+            return []
+        n = self.u32()
+        if n != count or count > (len(self.data) - self.offset) // 8:
+            raise PACDecodeError("invalid PAC group array count")
+        return [(self.u32(), self.u32()) for _ in range(count)]
+
+    def sid(self) -> str:
+        max_count = self.u32()
+        revision, count = self.bytes(2)
+        authority = int.from_bytes(self.bytes(6), "big")
+        if revision != 1 or not 1 <= count <= MAX_SID_SUBAUTHS or max_count != count:
+            raise PACDecodeError("invalid NDR RPC_SID")
+        parts = [self.u32() for _ in range(count)]
+        return f"S-{revision}-{authority}" + "".join(f"-{x}" for x in parts)
+
+    def sid_pointer(self, referent: int) -> str | None:
+        return self.sid() if referent else None
+
+    def sid_and_attributes_array(self, referent: int, count: int) -> list[tuple[str | None, int]]:
+        if count > MAX_PAC_GROUPS:
+            raise PACDecodeError("excessive extra SID count")
+        if not referent:
+            if count:
+                raise PACDecodeError("null ExtraSids pointer with nonzero count")
+            return []
+        maximum = self.u32()
+        if maximum != count or count > (len(self.data) - self.offset) // 8:
+            raise PACDecodeError("invalid ExtraSids array count")
+        entries = [(self.u32(), self.u32()) for _ in range(count)]
+        if any(not ptr for ptr, _ in entries):
+            raise PACDecodeError("null SID in ExtraSids array")
+        return [(self.sid_pointer(ptr), flags) for ptr, flags in entries]
+
+    def domain_groups_array(
+        self, referent: int, count: int
+    ) -> list[tuple[str | None, list[tuple[int, int]]]]:
+        if count > MAX_PAC_ENTRIES:
+            raise PACDecodeError("excessive domain group count")
+        if not referent:
+            if count:
+                raise PACDecodeError("null domain group pointer with nonzero count")
+            return []
+        maximum = self.u32()
+        if maximum != count or count > (len(self.data) - self.offset) // 12:
+            raise PACDecodeError("invalid domain group array count")
+        entries = [(self.u32(), self.u32(), self.u32()) for _ in range(count)]
+        return [
+            (self.sid_pointer(sid_ref), self.group_array(group_ref, n))
+            for sid_ref, n, group_ref in entries
+        ]
+
+
+def ndr_serialized_pointer(data: bytes) -> NDRReader:
+    """Extract a Microsoft NDR32 type-serialization envelope and root pointer."""
+    if len(data) < 20 or data[:4] != b"\x01\x10\x08\x00":
+        raise PACDecodeError("unsupported NDR type-serialization header")
+    object_length = struct.unpack_from("<I", data, 8)[0]
+    if object_length < 4 or object_length > len(data) - 16:
+        raise PACDecodeError("invalid NDR object length")
+    reader = NDRReader(data[16:16 + object_length])
+    if not reader.u32():
+        raise PACDecodeError("null NDR root pointer")
+    return reader

py_mspack_decoder-0.1.1.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: py-mspack-decoder
+Version: 0.1.1
+Summary: Pure-Python Microsoft Kerberos PAC decoder
+Author: Simon Fonteneau
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: gssapi
+Requires-Dist: gssapi>=1.8; extra == "gssapi"
+Dynamic: license-file
+
+# py-mspack-decoder
+
+Pure-Python decoder for Microsoft Kerberos PAC structures, including compressed claims (LZNT1, XPRESS and XPRESS Huffman). No third-party dependencies for PAC **decoding**.
+
+**AI-assisted development:** Most of the implementation was written with AI coding tools under human direction. It has not undergone an independent security audit.
+
+
+
+## Minimal Flask + Kerberos example
+
+See [examples/flask_gssapi.py](examples/flask_gssapi.py). It accepts an HTTP `Authorization: Negotiate` token using the service keytab, obtains a completed **Kerberos acceptor** context, and calls:
+
+```python
+from pac_decoder.gssapi_helpers import decode_completed_context
+
+pac_info = decode_completed_context(ctx)
+print(pac_info["sid"], pac_info["groups"])
+```
+
+The helper requires a completed Kerberos acceptor context and exactly one `urn:mspac:` attribute flagged `authenticated` and `complete` by GSSAPI. It then strictly decodes the PAC. The underlying GSSAPI/Kerberos implementation, **not this package**, verifies PAC authenticity; successful authentication alone is not enough if the authenticated PAC attribute is missing.
+
+### Run the example
+
+The server must have a valid `HTTP/<hostname>@REALM` principal in its keytab, and MIT Kerberos must support the authenticated `urn:mspac:` attribute.
+
+```bash
+export KRB5_KTNAME=/path/to/http.keytab
+export KERBEROS_HOSTNAME=service.example.com
+flask --app examples/flask_gssapi.py run --host 127.0.0.1
+```
+
+From a Kerberos-authenticated client, over your HTTPS reverse proxy:
+
+```bash
+curl --negotiate -u : https://service.example.com/pac
+```
+
+This is intentionally a **one-round-trip Kerberos HTTP** example. It rejects negotiations needing several GSSAPI exchanges instead of attempting to resume a lost context. Use TLS, a trusted reverse proxy and a production WSGI server for a real service. The endpoint returns identity information only as a demonstration; do not expose it publicly. PAC group membership reflects ticket issuance time, not necessarily current AD state.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

py_mspack_decoder-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pac_decoder/__init__.py,sha256=w-ZHIgijNEefKc-9xZlpW387g8oTIxaQ2KZ60wniues,11038
+pac_decoder/binary.py,sha256=a2Xg3alh7FLWdq21XzpO9T59aOK7-fr4mD4kmsq69SY,6301
+pac_decoder/claims.py,sha256=cOaS_KHjMSERXQOYDdEChKpGCpNZIYLCGRxCyEp-zZc,5764
+pac_decoder/compression.py,sha256=8u5uhXox_KiSpMVSGsp3e02rJvG16MF4OrsfnL8O_NM,8434
+pac_decoder/gssapi_helpers.py,sha256=jmLlEiyhyqfM_wPItThZYlftMd-YWFpCSUWGsFpMZ6w,4687
+pac_decoder/logon.py,sha256=goERew9wnMqhpPOg6FZRbQ-Xm3kjDP6a5ZcHAcyqZME,11218
+pac_decoder/ndr.py,sha256=4FEXoAupHKKNWw3f40VFbqSwMjUI3aMPR45dK1Fc3BM,5823
+py_mspack_decoder-0.1.1.dist-info/licenses/LICENSE,sha256=-pUD-qeYToufnRHt_nAzuNAkd1LbnqD_VIJahR5YrFw,1072
+py_mspack_decoder-0.1.1.dist-info/METADATA,sha256=bri5YIS-0FOXf0caV-jSsGgHU4JWPkt-I3aOzvApoGk,2411
+py_mspack_decoder-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+py_mspack_decoder-0.1.1.dist-info/top_level.txt,sha256=dzmBVQdhS1wx8GzugnotZmJgc9-Oi6PTb29S7P4HEy8,12
+py_mspack_decoder-0.1.1.dist-info/RECORD,,

py_mspack_decoder-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_mspack_decoder-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Simon Fonteneau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_mspack_decoder-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pac_decoder