ocf-containers 1.0.0__tar.gz

ocf_containers-1.0.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 OCF Contributors
+
+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.
+
+---
+
+Exception note (not legal advice): cryptography primitives are drawn from
+the `cryptography` and `argon2-cffi` distributions and remain under their
+respective licenses (Apache-2.0 with linking exceptions, MIT,
+Apache-2.0). This license governs this repository's code only. The
+no-commercial-code clean-room rule documented in CONTRIBUTING.md is an
+engineering policy of this project, not a license condition.

ocf_containers-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.2
+Name: ocf-containers
+Version: 1.0.0
+Summary: Open Container Format - encrypted, seekable media container with passwords, machine binding, expiry, play limits and Ed25519 signed policy
+Author: OCF Contributors
+License: MIT License
+        
+        Copyright (c) 2026 OCF Contributors
+        
+        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.
+        
+        ---
+        
+        Exception note (not legal advice): cryptography primitives are drawn from
+        the `cryptography` and `argon2-cffi` distributions and remain under their
+        respective licenses (Apache-2.0 with linking exceptions, MIT,
+        Apache-2.0). This license governs this repository's code only. The
+        no-commercial-code clean-room rule documented in CONTRIBUTING.md is an
+        engineering policy of this project, not a license condition.
+        
+Project-URL: Homepage, https://github.com/JustHackedOn/ocf-containers
+Project-URL: Documentation, https://github.com/JustHackedOn/ocf-containers/tree/main/docs
+Project-URL: Changelog, https://github.com/JustHackedOn/ocf-containers/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/JustHackedOn/ocf-containers/blob/main/docs/SECURITY.md
+Project-URL: Issues, https://github.com/JustHackedOn/ocf-containers/issues
+Keywords: encryption,container,media,drm,aead,aes-gcm,argon2,ed25519,watermark,clean-room
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography<47,>=42
+Requires-Dist: argon2-cffi<26,>=23
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: hypothesis<7,>=6; extra == "dev"
+Requires-Dist: build<2,>=1.2; extra == "dev"
+
+# OCF — Open Container Format
+
+[![CI](https://github.com/JustHackedOn/ocf-containers/actions/workflows/test.yml/badge.svg)](https://github.com/JustHackedOn/ocf-containers/actions)
+[![PyPI](https://img.shields.io/pypi/v/ocf.svg)](https://pypi.org/project/ocf/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+OCF is a **clean-room, open-source encrypted media container** with password
+gating, machine binding, expiry, play-count limits, watermarks, and Ed25519-signed
+policy. It is built from standard primitives only — AES-256-GCM, Argon2id,
+Ed25519, HMAC-SHA256 — with no proprietary dependencies and no embedded keys.
+
+**Status:** v1.0.0 · 99 tests green · ~540 fuzz examples with 0 crashes ·
+1 GB file streamed at 245 MB/s (peak memory ≈ file size).
+
+## What it does
+
+```
+plaintext ──chunked AES-256-GCM──► SEC_DATA
+password  ──Argon2id──► KEK ──wraps──► content_key (never stored in the clear)
+policy    ──Ed25519──► signed SEC_POLICY (open/play pw, machine bind,
+                        expiry, play count, watermark)
+everything┐
+header    ├─ HMAC-SHA256 footer MAC (tamper-evident, verified before decrypt)
+sections  ┘
+```
+
+## Features
+
+- **AEAD everywhere** — per-chunk AES-256-GCM tags; bit-flips are rejected,
+  seek is O(1) via chunk table (256 KiB default chunks)
+- **Key wrapping** — content key is wrapped under an Argon2id-derived KEK;
+  the derived key never touches disk
+- **Signed policy** — open/password flags, machine binding, expiry,
+  play-count limit, watermark, all in one Ed25519-signed `SEC_POLICY`
+  (pin the vendor pubkey for authenticity; embedded key gives integrity)
+- **Streaming** — `build_streaming()` writes O(chunk) memory for any size
+  (tested at 1 GB); reader is mmap-backed with zero-copy sections
+- **Machine binding** — weighted fingerprint from machine GUID, BIOS UUID,
+  CPU ID, disk serial, MAC (each source hashed before combining; no raw
+  serials in the digest)
+- **Play counting** — external state file keyed by signed `container_id`;
+  rewriting the container breaks the footer MAC, so counters can't be
+  reset by editing the file
+- **CLI + library** — `ocfctl` for scripts, clean Python API for apps
+
+## Honest scope (read before trusting this with anything)
+
+OCF protects **data at rest** and gates **player behavior**. Like every
+client-side DRM scheme (including commercial ones), it cannot defend an
+attacker who controls the running player: the unwrapped key must exist in
+process memory to play. OCF raises the cost of casual redistribution and
+tampering; it does not promise impossibility. See [docs/SECURITY.md](docs/SECURITY.md)
+for the full threat model.
+
+## Install
+
+```bash
+pip install ocf-containers  # from PyPI (when published)
+pip install .            # from a clone
+pip install -e ".[dev]"  # dev install with pytest/hypothesis/build
+```
+
+Python 3.11+ · Windows, Linux, macOS.
+
+## Quick start
+
+```bash
+# Encrypt a folder for this machine only, expiring 2026-12-31, 5 plays max
+ocfctl create movie.ocf video.mp4 --password openpw \
+    --machine-bind --expiry 2026-12-31 --play-count 5 \
+    --watermark "REVIEW COPY" --sign
+#    → prints the policy pubkey; PIN IT to verify signatures later
+
+ocfctl info movie.ocf --password openpw
+ocfctl authorize movie.ocf --password openpw --play-password REPLACEME
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for the 5-minute walkthrough and
+[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) for every flag.
+
+## Library example
+
+```python
+from ocf.container import ContainerWriter, ContainerReader, FileEntry, make_policy
+from ocf.primitives.signing import generate_signing_key
+
+policy = make_policy(signing_key=generate_signing_key(), watermark="TRIAL")
+blob = ContainerWriter(password=b"openpw", policy=policy).build(
+    [FileEntry("video.mp4", open("video.mp4", "rb").read())]
+)
+r = ContainerReader(blob, password=b"openpw")
+print(r.policy.watermark, r.files[0].name)
+data = r.read_file(0)
+```
+
+More in [`examples/`](examples/): basic, password, machine-bound, expiry,
+play-count, batch, and 1 GB streaming.
+
+## Benchmarks
+
+| Case | Encrypt | Decrypt |
+|---|---|---|
+| 100 MB (stream) | ~250 MB/s | ~290 MB/s |
+| 1 GB (stream) | 245 MB/s | 250 MB/s |
+| Password overhead | Argon2id ≈ 0.25 s fixed per open | |
+
+Details and methodology: [docs/BENCHMARK.md](docs/BENCHMARK.md).
+Parallel workers are off by default — measured to hurt on AES-NI.
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [QUICKSTART.md](QUICKSTART.md) | first container in 5 minutes |
+| [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | all commands and flags |
+| [docs/FORMAT_SPEC.md](docs/FORMAT_SPEC.md) | public container format spec |
+| [docs/SECURITY.md](docs/SECURITY.md) | threat model, disclosure |
+| [docs/BENCHMARK.md](docs/BENCHMARK.md) | numbers + recommendations |
+| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | dev setup, PRs, clean-room policy |
+| [docs/RELEASING.md](docs/RELEASING.md) | versioning, PyPI, tags |
+
+## Development
+
+```bash
+git clone https://github.com/JustHackedOn/ocf-containers && cd ocf-containers
+pip install -e ".[dev]"
+pytest -q          # 99 tests, including ~540 fuzz examples
+python tools/benchmark.py --quick
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ocf_containers-1.0.0/README.md

@@ -0,0 +1,133 @@
+# OCF — Open Container Format
+
+[![CI](https://github.com/JustHackedOn/ocf-containers/actions/workflows/test.yml/badge.svg)](https://github.com/JustHackedOn/ocf-containers/actions)
+[![PyPI](https://img.shields.io/pypi/v/ocf.svg)](https://pypi.org/project/ocf/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+OCF is a **clean-room, open-source encrypted media container** with password
+gating, machine binding, expiry, play-count limits, watermarks, and Ed25519-signed
+policy. It is built from standard primitives only — AES-256-GCM, Argon2id,
+Ed25519, HMAC-SHA256 — with no proprietary dependencies and no embedded keys.
+
+**Status:** v1.0.0 · 99 tests green · ~540 fuzz examples with 0 crashes ·
+1 GB file streamed at 245 MB/s (peak memory ≈ file size).
+
+## What it does
+
+```
+plaintext ──chunked AES-256-GCM──► SEC_DATA
+password  ──Argon2id──► KEK ──wraps──► content_key (never stored in the clear)
+policy    ──Ed25519──► signed SEC_POLICY (open/play pw, machine bind,
+                        expiry, play count, watermark)
+everything┐
+header    ├─ HMAC-SHA256 footer MAC (tamper-evident, verified before decrypt)
+sections  ┘
+```
+
+## Features
+
+- **AEAD everywhere** — per-chunk AES-256-GCM tags; bit-flips are rejected,
+  seek is O(1) via chunk table (256 KiB default chunks)
+- **Key wrapping** — content key is wrapped under an Argon2id-derived KEK;
+  the derived key never touches disk
+- **Signed policy** — open/password flags, machine binding, expiry,
+  play-count limit, watermark, all in one Ed25519-signed `SEC_POLICY`
+  (pin the vendor pubkey for authenticity; embedded key gives integrity)
+- **Streaming** — `build_streaming()` writes O(chunk) memory for any size
+  (tested at 1 GB); reader is mmap-backed with zero-copy sections
+- **Machine binding** — weighted fingerprint from machine GUID, BIOS UUID,
+  CPU ID, disk serial, MAC (each source hashed before combining; no raw
+  serials in the digest)
+- **Play counting** — external state file keyed by signed `container_id`;
+  rewriting the container breaks the footer MAC, so counters can't be
+  reset by editing the file
+- **CLI + library** — `ocfctl` for scripts, clean Python API for apps
+
+## Honest scope (read before trusting this with anything)
+
+OCF protects **data at rest** and gates **player behavior**. Like every
+client-side DRM scheme (including commercial ones), it cannot defend an
+attacker who controls the running player: the unwrapped key must exist in
+process memory to play. OCF raises the cost of casual redistribution and
+tampering; it does not promise impossibility. See [docs/SECURITY.md](docs/SECURITY.md)
+for the full threat model.
+
+## Install
+
+```bash
+pip install ocf-containers  # from PyPI (when published)
+pip install .            # from a clone
+pip install -e ".[dev]"  # dev install with pytest/hypothesis/build
+```
+
+Python 3.11+ · Windows, Linux, macOS.
+
+## Quick start
+
+```bash
+# Encrypt a folder for this machine only, expiring 2026-12-31, 5 plays max
+ocfctl create movie.ocf video.mp4 --password openpw \
+    --machine-bind --expiry 2026-12-31 --play-count 5 \
+    --watermark "REVIEW COPY" --sign
+#    → prints the policy pubkey; PIN IT to verify signatures later
+
+ocfctl info movie.ocf --password openpw
+ocfctl authorize movie.ocf --password openpw --play-password REPLACEME
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for the 5-minute walkthrough and
+[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) for every flag.
+
+## Library example
+
+```python
+from ocf.container import ContainerWriter, ContainerReader, FileEntry, make_policy
+from ocf.primitives.signing import generate_signing_key
+
+policy = make_policy(signing_key=generate_signing_key(), watermark="TRIAL")
+blob = ContainerWriter(password=b"openpw", policy=policy).build(
+    [FileEntry("video.mp4", open("video.mp4", "rb").read())]
+)
+r = ContainerReader(blob, password=b"openpw")
+print(r.policy.watermark, r.files[0].name)
+data = r.read_file(0)
+```
+
+More in [`examples/`](examples/): basic, password, machine-bound, expiry,
+play-count, batch, and 1 GB streaming.
+
+## Benchmarks
+
+| Case | Encrypt | Decrypt |
+|---|---|---|
+| 100 MB (stream) | ~250 MB/s | ~290 MB/s |
+| 1 GB (stream) | 245 MB/s | 250 MB/s |
+| Password overhead | Argon2id ≈ 0.25 s fixed per open | |
+
+Details and methodology: [docs/BENCHMARK.md](docs/BENCHMARK.md).
+Parallel workers are off by default — measured to hurt on AES-NI.
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [QUICKSTART.md](QUICKSTART.md) | first container in 5 minutes |
+| [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | all commands and flags |
+| [docs/FORMAT_SPEC.md](docs/FORMAT_SPEC.md) | public container format spec |
+| [docs/SECURITY.md](docs/SECURITY.md) | threat model, disclosure |
+| [docs/BENCHMARK.md](docs/BENCHMARK.md) | numbers + recommendations |
+| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | dev setup, PRs, clean-room policy |
+| [docs/RELEASING.md](docs/RELEASING.md) | versioning, PyPI, tags |
+
+## Development
+
+```bash
+git clone https://github.com/JustHackedOn/ocf-containers && cd ocf-containers
+pip install -e ".[dev]"
+pytest -q          # 99 tests, including ~540 fuzz examples
+python tools/benchmark.py --quick
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ocf_containers-1.0.0/ocf/__init__.py

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

ocf_containers-1.0.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_containers-1.0.0/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_containers-1.0.0/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_containers-1.0.0/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