ocf-containers 1.0.0__py3-none-any.whl

ocf/__init__.py

@@ -0,0 +1,3 @@
+"""OCF — Open Container Format."""
+
+__version__ = "0.1.0"

ocf/binding/__init__.py

@@ -0,0 +1,13 @@
+from .machine import (
+    FingerprintResult,
+    WEIGHTED_SOURCES,
+    collect_components,
+    fingerprint_from,
+    get_fingerprint,
+    get_partial_fingerprint,
+)
+
+__all__ = [
+    "FingerprintResult", "WEIGHTED_SOURCES", "collect_components",
+    "fingerprint_from", "get_fingerprint", "get_partial_fingerprint",
+]

ocf/binding/machine.py

@@ -0,0 +1,125 @@
+"""Local machine fingerprinting (Windows-first, injectable for tests)."""
+
+import hashlib
+import platform
+import subprocess
+import uuid
+from dataclasses import dataclass
+
+WEIGHTED_SOURCES: dict[str, int] = {
+    "machine_guid": 4,
+    "bios_uuid": 3,
+    "cpu_id": 2,
+    "disk_serial": 2,
+    "mac_address": 1,
+}
+
+_FP_DOMAIN = b"ocf-mb:v1"
+
+
+def _ps_first_line(cmd: str) -> str:
+    try:
+        out = subprocess.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", cmd],
+            capture_output=True, text=True, timeout=15,
+        )
+        for line in out.stdout.splitlines():
+            line = line.strip()
+            if line and line != "SerialNumber":
+                return line
+    except Exception:
+        pass
+    return ""
+
+
+def _collect_machine_guid() -> str:
+    if platform.system() != "Windows":
+        return ""
+    try:
+        import winreg
+        with winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\Microsoft\Cryptography"
+        ) as key:
+            return str(winreg.QueryValueEx(key, "MachineGuid")[0])
+    except Exception:
+        return ""
+
+
+def _collect_bios_uuid() -> str:
+    if platform.system() != "Windows":
+        return ""
+    return _ps_first_line("(Get-CimInstance Win32_ComputerSystemProduct).UUID")
+
+
+def _collect_cpu_id() -> str:
+    if platform.system() != "Windows":
+        return platform.processor()
+    return _ps_first_line(
+        "(Get-CimInstance Win32_Processor | Select-Object -First 1).ProcessorId"
+    )
+
+
+def _collect_disk_serial() -> str:
+    if platform.system() != "Windows":
+        return ""
+    return _ps_first_line(
+        "(Get-PhysicalDisk | Select-Object -First 1).SerialNumber"
+    )
+
+
+def _collect_mac_address() -> str:
+    node = uuid.getnode()
+    return ":".join(f"{(node >> (8 * i)) & 0xFF:02x}" for i in reversed(range(6)))
+
+
+_COLLECTORS = {
+    "machine_guid": _collect_machine_guid,
+    "bios_uuid": _collect_bios_uuid,
+    "cpu_id": _collect_cpu_id,
+    "disk_serial": _collect_disk_serial,
+    "mac_address": _collect_mac_address,
+}
+
+
+def collect_components() -> dict[str, str]:
+    return {name: fn().strip() for name, fn in _COLLECTORS.items()}
+
+
+@dataclass(frozen=True)
+class FingerprintResult:
+    digest: bytes
+    sources: dict[str, str]
+    weights: dict[str, int]
+
+
+def fingerprint_from(
+    components: dict[str, str], include: set[str] | None = None
+) -> FingerprintResult:
+    names = [
+        n for n in WEIGHTED_SOURCES
+        if n in components and components[n].strip()
+        and (include is None or n in include)
+    ]
+    h = hashlib.sha256(_FP_DOMAIN)
+    h.update(bytes([len(names)]))
+    used, weights = {}, {}
+    for n in names:
+        value = components[n].strip()
+        weight = WEIGHTED_SOURCES[n]
+        digest = hashlib.sha256(f"{n}|{value}".encode()).digest()
+        h.update(n.encode() + b"\x00" + bytes([weight]) + digest)
+        used[n] = value
+        weights[n] = weight
+    return FingerprintResult(h.digest(), used, weights)
+
+
+def get_fingerprint(components: dict[str, str] | None = None) -> bytes:
+    comps = components if components is not None else collect_components()
+    return fingerprint_from(comps).digest
+
+
+def get_partial_fingerprint(
+    include: set[str], components: dict[str, str] | None = None
+) -> FingerprintResult:
+    comps = components if components is not None else collect_components()
+    return fingerprint_from(comps, include=include)

ocf/container/__init__.py

@@ -0,0 +1,20 @@
+from .layout import (
+    CHUNK_SIZE_DEFAULT, MAGIC_FOOTER, MAGIC_HEADER, SEC_DATA, SEC_END,
+    SEC_INDEX, SEC_KEYS, SEC_META, SEC_POLICY,
+)
+from .policy import (
+    Policy, PolicyError, check_play_password, enforce_policy, make_policy,
+    pack_policy, sign_policy, unpack_policy, verify_policy_signature,
+)
+from .reader import ContainerError, ContainerReader
+from .state import PlayStateStore
+from .writer import ContainerWriter, FileEntry
+
+__all__ = [
+    "ContainerWriter", "ContainerReader", "ContainerError", "FileEntry",
+    "Policy", "PolicyError", "make_policy", "pack_policy", "unpack_policy",
+    "sign_policy", "verify_policy_signature", "enforce_policy",
+    "check_play_password", "PlayStateStore",
+    "MAGIC_HEADER", "MAGIC_FOOTER", "SEC_META", "SEC_KEYS", "SEC_POLICY",
+    "SEC_INDEX", "SEC_DATA", "SEC_END", "CHUNK_SIZE_DEFAULT",
+]

ocf/container/layout.py

@@ -0,0 +1,60 @@
+import struct
+
+MAGIC_HEADER = b"OCF1"
+MAGIC_FOOTER = b"OCFf"
+
+HEADER_SIZE = 32
+FOOTER_SIZE = 32
+
+SEC_META = 0x0001
+SEC_KEYS = 0x0002
+SEC_INDEX = 0x0003
+SEC_DATA = 0x0004
+SEC_LICENSE = 0x0005
+SEC_POLICY = 0x0006
+SEC_PADDING = 0x00FE
+SEC_END = 0x00FF
+
+CRITICAL_BIT = 0x8000
+
+CHUNK_SIZE_DEFAULT = 262144
+
+KEY_PURPOSE_CONTENT = 1
+KEY_PURPOSE_OPEN = 2
+KEY_PURPOSE_PLAY = 3
+
+HEADER_STRUCT = struct.Struct("<4sHHIIQQ")
+FOOTER_STRUCT = struct.Struct("<4sIQ16s")
+TLV_STRUCT = struct.Struct("<HI")
+
+
+def build_header(section_count: int, part_index: int = 0, flags: int = 0) -> bytes:
+    return HEADER_STRUCT.pack(
+        MAGIC_HEADER, 1, 0, flags, section_count, part_index, 0
+    )
+
+
+def parse_header(data: bytes) -> dict:
+    if len(data) < HEADER_SIZE:
+        raise ValueError("header truncated")
+    magic, maj, minr, flags, count, part, _ = HEADER_STRUCT.unpack(data[:HEADER_SIZE])
+    if magic != MAGIC_HEADER:
+        raise ValueError("bad magic")
+    if maj != 1:
+        raise ValueError(f"unsupported major version {maj}")
+    return dict(flags=flags, section_count=count, part_index=part)
+
+
+def tlv(sec_type: int, payload: bytes) -> bytes:
+    return TLV_STRUCT.pack(sec_type, len(payload)) + payload
+
+
+def iter_tlvs(buf: bytes):
+    off = 0
+    while off + TLV_STRUCT.size <= len(buf):
+        sec_type, length = TLV_STRUCT.unpack_from(buf, off)
+        off += TLV_STRUCT.size
+        if off + length > len(buf):
+            raise ValueError("tlv overruns buffer")
+        yield sec_type, buf[off:off + length]
+        off += length

ocf/container/policy.py

@@ -0,0 +1,204 @@
+"""SEC_POLICY: access rules + optional Ed25519 policy signature."""
+
+import struct
+import time
+from dataclasses import dataclass, field
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from ..binding.machine import get_fingerprint
+from ..primitives.kdf import hash_password, verify_password_hash
+
+POLICY_VERSION = 1
+
+FLAG_OPEN_PW = 0x01
+FLAG_PLAY_PW = 0x02
+FLAG_MACHINE_BIND = 0x04
+
+FIXED_LEN = 1 + 1 + 2 + 4 + 8 + 16 + 32  # before variable fields
+SIG_LEN = 64
+PUB_LEN = 32
+
+
+class PolicyError(Exception):
+    pass
+
+
+@dataclass
+class Policy:
+    open_password_required: bool = False
+    play_password_required: bool = False
+    machine_binding: bool = False
+    play_count_limit: int = 0
+    expiry_unix: int = 0
+    container_id: bytes = field(default_factory=lambda: b"\x00" * 16)
+    machine_fingerprint: bytes = field(default_factory=lambda: b"\x00" * 32)
+    watermark: str = ""
+    play_password_hash: str = ""
+    signing_pubkey: bytes = field(default_factory=lambda: b"\x00" * PUB_LEN)
+    signature: bytes = field(default_factory=lambda: b"\x00" * SIG_LEN)
+
+    @property
+    def flags(self) -> int:
+        f = 0
+        if self.open_password_required:
+            f |= FLAG_OPEN_PW
+        if self.play_password_required:
+            f |= FLAG_PLAY_PW
+        if self.machine_binding:
+            f |= FLAG_MACHINE_BIND
+        return f
+
+
+def make_policy(
+    *,
+    signing_key: Ed25519PrivateKey | None = None,
+    open_password_required: bool = False,
+    play_password: bytes | None = None,
+    machine_fingerprint: bytes | None = None,
+    play_count_limit: int = 0,
+    expiry_unix: int = 0,
+    watermark: str = "",
+    container_id: bytes | None = None,
+) -> Policy:
+    p = Policy(
+        open_password_required=open_password_required,
+        play_password_required=play_password is not None,
+        machine_binding=machine_fingerprint is not None,
+        play_count_limit=play_count_limit,
+        expiry_unix=expiry_unix,
+        watermark=watermark,
+        container_id=container_id or _random_cid(),
+    )
+    if machine_fingerprint is not None:
+        if len(machine_fingerprint) != 32:
+            raise ValueError("machine_fingerprint must be 32 bytes")
+        p.machine_fingerprint = machine_fingerprint
+    if play_password is not None:
+        p.play_password_hash = hash_password(play_password)
+    if signing_key is not None:
+        sign_policy(p, signing_key)
+    return p
+
+
+def _random_cid() -> bytes:
+    from ..primitives.rng import random_bytes
+    return random_bytes(16)
+
+
+def pack_policy(p: Policy, *, include_signature: bool = True) -> bytes:
+    wm = p.watermark.encode("utf-8", "surrogatepass")
+    ph = p.play_password_hash.encode("utf-8", "surrogatepass")
+    body = struct.pack(
+        "<BBHIQ16s32s",
+        POLICY_VERSION, p.flags, 0, p.play_count_limit,
+        p.expiry_unix, p.container_id, p.machine_fingerprint,
+    )
+    body += struct.pack("<I", len(wm)) + wm
+    body += struct.pack("<I", len(ph)) + ph
+    body += p.signing_pubkey
+    if include_signature:
+        body += p.signature
+    return body
+
+
+def unpack_policy(buf: bytes | memoryview) -> Policy:
+    if len(buf) < FIXED_LEN + 8:
+        raise PolicyError("policy section too short")
+    try:
+        ver, flags, _, limit, exp, cid, fp = struct.unpack_from("<BBHIQ16s32s", buf)
+    except struct.error as e:
+        raise PolicyError("policy header malformed") from e
+    if ver != POLICY_VERSION:
+        raise PolicyError(f"unsupported policy version {ver}")
+    off = FIXED_LEN
+    (wlen,) = struct.unpack_from("<I", buf, off); off += 4
+    if off + wlen + 4 > len(buf):
+        raise PolicyError("watermark overruns")
+    try:
+        wm = bytes(buf[off:off + wlen]).decode("utf-8", "surrogatepass")
+    except UnicodeDecodeError as e:
+        raise PolicyError("watermark not valid UTF-8") from e
+    off += wlen
+    try:
+        (plen,) = struct.unpack_from("<I", buf, off); off += 4
+    except struct.error as e:
+        raise PolicyError("password hash length malformed") from e
+    if off + plen + PUB_LEN + SIG_LEN > len(buf):
+        raise PolicyError("password hash overruns")
+    try:
+        ph = bytes(buf[off:off + plen]).decode("utf-8", "surrogatepass")
+    except UnicodeDecodeError as e:
+        raise PolicyError("password hash not valid UTF-8") from e
+    off += plen
+    pubkey = buf[off:off + PUB_LEN]; off += PUB_LEN
+    sig = buf[off:off + SIG_LEN]; off += SIG_LEN
+    if off != len(buf):
+        raise PolicyError("trailing policy bytes")
+    return Policy(
+        open_password_required=bool(flags & FLAG_OPEN_PW),
+        play_password_required=bool(flags & FLAG_PLAY_PW),
+        machine_binding=bool(flags & FLAG_MACHINE_BIND),
+        play_count_limit=limit,
+        expiry_unix=exp,
+        container_id=cid,
+        machine_fingerprint=fp,
+        watermark=wm,
+        play_password_hash=ph,
+        signing_pubkey=pubkey,
+        signature=sig,
+    )
+
+
+def sign_policy(p: Policy, key: Ed25519PrivateKey) -> None:
+    p.signing_pubkey = key.public_key().public_bytes_raw()
+    body = pack_policy(p, include_signature=False)
+    p.signature = key.sign(body)
+
+
+def verify_policy_signature(p: Policy, pinned_pubkey: bytes | None = None) -> str:
+    """Return 'pinned' or 'embedded' on success; raise PolicyError on failure."""
+    key_bytes = pinned_pubkey if pinned_pubkey is not None else p.signing_pubkey
+    if key_bytes == b"\x00" * PUB_LEN:
+        raise PolicyError("policy has no signature and no pinned key given")
+    if p.signature == b"\x00" * SIG_LEN:
+        raise PolicyError("policy unsigned")
+    body = pack_policy(p, include_signature=False)
+    try:
+        Ed25519PublicKey.from_public_bytes(key_bytes).verify(p.signature, body)
+    except InvalidSignature as e:
+        raise PolicyError("policy signature invalid (tampered?)") from e
+    return "pinned" if pinned_pubkey is not None else "embedded"
+
+
+def enforce_policy(
+    p: Policy,
+    *,
+    now: float | None = None,
+    machine_fp: bytes | None = None,
+    pinned_pubkey: bytes | None = None,
+) -> None:
+    verify_policy_signature(p, pinned_pubkey)
+    ts = time.time() if now is None else now
+    if p.expiry_unix and ts > p.expiry_unix:
+        raise PolicyError("container expired")
+    if p.machine_binding:
+        fp = machine_fp if machine_fp is not None else get_fingerprint()
+        if len(fp) != 32:
+            raise PolicyError("machine fingerprint unavailable")
+        import hmac as _hmac
+        if not _hmac.compare_digest(fp, p.machine_fingerprint):
+            raise PolicyError("machine binding mismatch")
+
+
+def check_play_password(p: Policy, password: bytes) -> None:
+    if not p.play_password_required:
+        return
+    if not p.play_password_hash:
+        raise PolicyError("play password required but no hash in policy")
+    if not verify_password_hash(password, p.play_password_hash):
+        raise PolicyError("wrong play password")

ocf/container/reader.py

@@ -0,0 +1,233 @@
+import hashlib
+import hmac
+import mmap
+import struct
+from dataclasses import dataclass
+from typing import BinaryIO
+
+from ..primitives.aead import chunk_nonce, open_sealed, unwrap_key
+from ..primitives.kdf import derive_kek, k_mac
+from . import layout as L
+from .policy import Policy, PolicyError, check_play_password, enforce_policy, unpack_policy
+from .state import PlayStateStore
+
+
+@dataclass
+class ParsedFile:
+    file_id: bytes
+    name: str
+    size: int
+    chunk_size: int
+    chunk_count: int
+    table: list[tuple[int, int, int]]
+
+
+class ContainerError(Exception):
+    pass
+
+
+class ContainerReader:
+    def __init__(
+        self,
+        blob: bytes | mmap.mmap,
+        password: bytes | None = None,
+        *,
+        now: float | None = None,
+        machine_fp: bytes | None = None,
+        policy_pubkey: bytes | None = None,
+        state_store: PlayStateStore | None = None,
+        enforce: bool = True,
+    ):
+        self.blob = blob
+        self._mv = memoryview(blob)
+        try:
+            self.header = L.parse_header(bytes(self._mv[:L.HEADER_SIZE]))
+        except ValueError as e:
+            raise ContainerError(str(e)) from e
+        self.sections: dict[int, bytes | memoryview] = {}
+        self._parse_tlvs()
+        self.policy: Policy | None = None
+        if L.SEC_POLICY in self.sections:
+            self.policy = unpack_policy(bytes(self.sections[L.SEC_POLICY]))
+            if enforce:
+                enforce_policy(
+                    self.policy,
+                    now=now,
+                    machine_fp=machine_fp,
+                    pinned_pubkey=policy_pubkey,
+                )
+        self._state = state_store
+        self._play_authorized = False
+        self.content_key = self._unwrap_key(password)
+        self._verify_mac()
+        self.files = self._parse_index()
+
+    @classmethod
+    def from_path(cls, path, **kw) -> "ContainerReader":
+        f = open(path, "rb")
+        try:
+            size = f.seek(0, 2)
+            if size < L.HEADER_SIZE + L.FOOTER_SIZE:
+                f.close()
+                raise ContainerError("file too small")
+            f.seek(0)
+            mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
+        except Exception:
+            f.close()
+            raise
+        try:
+            reader = cls(mm, **kw)
+        except BaseException:
+            mm.close()
+            f.close()
+            raise
+        reader._keepalive = (f, mm)
+        return reader
+
+    def close(self) -> None:
+        ka = getattr(self, "_keepalive", None)
+        if ka:
+            for v in self.sections.values():
+                if isinstance(v, memoryview):
+                    v.release()
+            self.sections.clear()
+            mv = getattr(self, "_mv", None)
+            if isinstance(mv, memoryview):
+                mv.release()
+            f, mm = ka
+            mm.close()
+            f.close()
+            self._keepalive = None
+
+    def __enter__(self) -> "ContainerReader":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    @property
+    def watermark(self) -> str:
+        return self.policy.watermark if self.policy else ""
+
+    def authorize_play(self, play_password: bytes | None = None) -> int:
+        if self.policy is None:
+            self._play_authorized = True
+            return 0
+        if self.policy.play_password_required:
+            if play_password is None:
+                raise PolicyError("play password required")
+            check_play_password(self.policy, play_password)
+        limit = self.policy.play_count_limit
+        if limit:
+            store = self._state or PlayStateStore()
+            self._state = store
+            used = store.plays(self.policy.container_id)
+            if used >= limit:
+                raise PolicyError(f"play limit exhausted ({limit})")
+            store.record_play(self.policy.container_id)
+            self._play_authorized = True
+            return limit - used - 1
+        self._play_authorized = True
+        return 0
+
+    def _play_gate_active(self) -> bool:
+        return bool(
+            self.policy
+            and (self.policy.play_password_required or self.policy.play_count_limit)
+        )
+
+    def _parse_tlvs(self) -> None:
+        off = L.HEADER_SIZE
+        end = len(self.blob) - L.FOOTER_SIZE
+        for _ in range(self.header["section_count"]):
+            if off + L.TLV_STRUCT.size > end:
+                raise ContainerError("section header overruns file")
+            sec_type, length = L.TLV_STRUCT.unpack_from(self._mv, off)
+            off += L.TLV_STRUCT.size
+            if off + length > end:
+                raise ContainerError("section payload overruns file")
+            self.sections[sec_type] = self._mv[off:off + length]
+            off += length
+        if L.SEC_END not in self.sections:
+            raise ContainerError("missing SEC_END")
+
+    def _unwrap_key(self, password: bytes | None) -> bytes:
+        keys = bytes(self.sections.get(L.SEC_KEYS, b""))
+        if len(keys) < 33:
+            raise ContainerError("SEC_KEYS malformed")
+        purpose = keys[16]
+        kdf_id = keys[17]
+        if purpose != L.KEY_PURPOSE_CONTENT:
+            raise ContainerError("no content key record")
+        if kdf_id == 0:
+            return keys[34 + 12:]
+        if password is None:
+            raise ContainerError("password required")
+        salt = keys[18:34]
+        kek = derive_kek(password, salt)
+        key_id = keys[:16]
+        try:
+            return unwrap_key(kek, keys[34:], key_id)
+        except Exception as e:
+            raise ContainerError("wrong password") from e
+
+    def _verify_mac(self) -> None:
+        if len(self.blob) < L.FOOTER_SIZE:
+            raise ContainerError("footer missing")
+        magic, count, total, mac = L.FOOTER_STRUCT.unpack(
+            bytes(self.blob[-L.FOOTER_SIZE:])
+        )
+        if magic != L.MAGIC_FOOTER:
+            raise ContainerError("bad footer magic")
+        if total != len(self.blob):
+            raise ContainerError("size mismatch")
+        body = self._mv[: len(self.blob) - L.FOOTER_SIZE]
+        expect = hmac.new(k_mac(self.content_key), body, hashlib.sha256).digest()[:16]
+        if not hmac.compare_digest(mac, expect):
+            raise ContainerError("footer MAC mismatch (tampered?)")
+
+    def _parse_index(self) -> list[ParsedFile]:
+        buf = bytes(self.sections.get(L.SEC_INDEX, b""))
+        files, off = [], 0
+        try:
+            while off < len(buf):
+                file_id = buf[off:off + 16]; off += 16
+                (nlen,) = struct.unpack_from("<I", buf, off); off += 4
+                name = buf[off:off + nlen].decode("utf-8", "surrogatepass"); off += nlen
+                size, chunk_size, nchunks = struct.unpack_from("<QII", buf, off); off += 16
+                (tlen,) = struct.unpack_from("<I", buf, off); off += 4
+                table = [struct.unpack_from("<QQI", buf, off + i * 20) for i in range(nchunks)]
+                off += tlen
+                files.append(ParsedFile(file_id, name, size, chunk_size, nchunks, table))
+        except (struct.error, UnicodeDecodeError) as e:
+            raise ContainerError(f"SEC_INDEX malformed: {e}") from e
+        return files
+
+    def iter_chunks(self, index: int = 0):
+        if self._play_gate_active() and not self._play_authorized:
+            raise PolicyError("authorize_play() required before read_file()")
+        f = self.files[index]
+        data = self.sections.get(L.SEC_DATA, b"")
+        for idx, (_, data_off, stored_len) in enumerate(f.table):
+            stored = bytes(data[data_off:data_off + stored_len])
+            if len(stored) < 4:
+                raise ContainerError("chunk truncated")
+            (pt_len,) = struct.unpack_from("<I", stored)
+            nonce = chunk_nonce(f.file_id, idx)
+            aad = f.file_id + struct.pack("<Q", idx)
+            try:
+                pt = open_sealed(self.content_key, nonce, stored[4:], aad)
+            except Exception as e:
+                raise ContainerError(f"chunk {idx} failed authentication") from e
+            yield pt[:pt_len]
+
+    def read_file(self, index: int = 0) -> bytes:
+        f = self.files[index]
+        return b"".join(self.iter_chunks(index))[: f.size]
+
+    def extract_to(self, index: int, out: BinaryIO) -> int:
+        n = 0
+        for pt in self.iter_chunks(index):
+            out.write(pt)
+            n += len(pt)
+        return n