Pharmaceutical Cold Chain

Exporting Tamper-Evident Audit Trails to PDF/A

A hash-chained audit trail is only inspection-ready if a regulator can open it years later without your production system, read it, and check it. That is the job of the archival document produced here: a PDF/A rendering of the trail that a human can read and a machine can verify, produced as one deliverable of audit trail export for regulatory submissions. This guide renders the human-readable pages, embeds the machine-readable chain and a verification manifest as an attachment, and stamps the file so the document itself becomes tamper-evident rather than a disposable printout.

Regulatory hook

21 CFR Part 11 §11.10(b) requires that electronic records be reproducible for inspection in both human-readable and electronic form. A plain print-to-PDF fails the durability half of that obligation: it may reference fonts by name, omit a colour profile, and rely on features that a future viewer cannot render faithfully, so the “human-readable” copy degrades over the retention period. PDF/A — specifically PDF/A-3 — is the ISO 19005 archival profile that forbids those hazards and permits embedding the source data as a file attachment, letting one document carry both the readable rendering (§11.10(b) human-readable form) and the exact hash chain (§11.10(b) electronic form) alongside the §11.10(e) audit-trail evidence.

The choice of PDF/A-3 over the older PDF/A-2 is deliberate. PDF/A-2 permits attachments only if those attachments are themselves PDF/A, which rules out embedding a JSON chain; PDF/A-3 lifts that restriction and allows an arbitrary associated file, which is exactly what a machine-readable audit chain needs to be. The reproduction obligation is therefore satisfied by a single self-describing object rather than a folder of loosely related files that a future custodian might separate. Retention makes this concrete: EU GDP practice and EMA guidance commonly hold cold chain records for years beyond product expiry, and an inspector opening the file in that far-future window must be able to read the pages and re-run the integrity check without any part of your current toolchain. An archival profile is what guarantees the document is still that inspector’s evidence and not a corrupted artifact.

Prerequisites

  • Python 3.11 or newer.
  • Rendering and post-processing libraries:
bash
pip install "reportlab>=4.1,<5" "pikepdf>=9,<10"
  • Input: a verified list of audit records — the output of the pre-export chain check in verifying hash-chain integrity before export. This guide assumes the chain has already recomputed cleanly; it renders, it does not re-mint integrity.
  • Fonts: an embeddable font file (for example a licensed OpenType face) available on the render host. PDF/A forbids unembedded fonts, so a system font referenced by name is not acceptable.
  • Access control: the render job runs as a service identity permitted to read the retained store; the signing secret for the file-level stamp comes from a KMS or secrets manager, never from source.

Step-by-Step Implementation

Step 1 — Reduce each record to a stable render row

The document must display exactly what the chain committed to, so the render row is derived from the same fields the record hash covers. No reformatting of timestamps, no rounding of values — the page shows the stored strings verbatim.

python
from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class RenderRow:
    # §11.10(b): the rendered row mirrors the hashed fields verbatim, so the
    # human-readable page and the electronic chain cannot disagree.
    record_id: str
    device_id: str
    event_utc: str
    summary: str
    record_hash: str


def to_render_rows(records) -> list[RenderRow]:
    rows: list[RenderRow] = []
    for r in records:
        rows.append(
            RenderRow(
                record_id=r.record_id,
                device_id=r.device_id,
                event_utc=r.event_utc,        # stored ISO-8601 string, never re-parsed
                summary=str(r.payload.get("disposition", r.payload.get("event", ""))),
                record_hash=r.record_hash,
            )
        )
    return rows

Verify the row count matches the input so nothing is silently dropped during shaping:

python
assert len(to_render_rows(records)) == len(records)

Step 2 — Render the human-readable pages with an embedded font

reportlab draws the trail as a paginated table. Registering and embedding the font is mandatory: PDF/A rejects a document that references a font it does not carry.

python
from reportlab.lib.pagesizes import A4
from reportlab.lib.units import mm
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont
from reportlab.pdfgen import canvas


def render_pages(rows: list[RenderRow], out_path: str, font_path: str, export_id: str) -> None:
    # §11.10(b) durable reproduction: embed the font so the page renders identically
    # for the full retention period, independent of the viewer's installed fonts.
    pdfmetrics.registerFont(TTFont("Archive", font_path))
    c = canvas.Canvas(out_path, pagesize=A4)
    width, height = A4
    y = height - 25 * mm
    c.setFont("Archive", 13)
    c.drawString(20 * mm, y, f"Cold Chain Audit Trail — Export {export_id}")
    c.setFont("Archive", 8)
    y -= 10 * mm
    for row in rows:
        if y < 25 * mm:                 # paginate; never overflow a page silently
            c.showPage()
            c.setFont("Archive", 8)
            y = height - 25 * mm
        # §11.10(e): show the record's own digest so a reader can spot-check the
        # printed row against the attached electronic chain.
        line = f"{row.event_utc}  {row.device_id}  {row.summary}  {row.record_hash[:16]}…"
        c.drawString(20 * mm, y, line)
        y -= 6 * mm
    c.showPage()
    c.save()

Step 3 — Attach the electronic chain and manifest

PDF/A-3 permits arbitrary file attachments. Embed the full chain as JSON and the verification manifest so the single document carries both forms §11.10(b) requires. pikepdf writes the attachments and converts the file to the archival profile.

python
import json

import pikepdf


def embed_chain_and_manifest(pdf_path: str, records, manifest: dict) -> None:
    # §11.10(b) electronic form: attach the exact chain the pages render, so the
    # document is self-verifying without access to the production database.
    chain_json = json.dumps(
        [
            {
                "record_id": r.record_id,
                "device_id": r.device_id,
                "event_utc": r.event_utc,
                "payload": r.payload,
                "prev_hash": r.prev_hash,
                "record_hash": r.record_hash,
            }
            for r in records
        ],
        sort_keys=True,
        separators=(",", ":"),
    ).encode("utf-8")

    with pikepdf.open(pdf_path, allow_overwriting_input=True) as pdf:
        pdf.attachments["audit_chain.json"] = chain_json          # electronic form
        pdf.attachments["manifest.json"] = json.dumps(            # §11.10(c) integrity manifest
            manifest, sort_keys=True, separators=(",", ":")
        ).encode("utf-8")
        # Declare the archival conformance level so downstream validators accept it.
        with pdf.open_metadata() as meta:
            meta["pdfaid:part"] = "3"
            meta["pdfaid:conformance"] = "B"
        pdf.save(pdf_path)

Confirm both attachments are present after embedding:

python
with pikepdf.open(pdf_path) as pdf:
    assert {"audit_chain.json", "manifest.json"}.issubset(set(pdf.attachments))

Step 4 — Stamp a file-level seal so the document is tamper-evident

A digest of the finished bytes, recorded in the manifest, lets an inspector confirm the document has not changed since release by recomputing one SHA-256.

python
import hashlib


def seal_document(pdf_path: str) -> str:
    # §11.10(c): the file digest is the tamper-evidence for the whole document,
    # checkable by anyone with the manifest and the file.
    digest = hashlib.sha256()
    with open(pdf_path, "rb") as fh:
        for block in iter(lambda: fh.read(65536), b""):
            digest.update(block)
    return digest.hexdigest()

Prove that any edit to the file changes the seal:

python
before = seal_document(pdf_path)
with open(pdf_path, "ab") as fh:
    fh.write(b"%%tamper")          # append one byte
assert seal_document(pdf_path) != before

Step 5 — Validate archival conformance in the pipeline

Rendering that is not conformance-checked drifts: a template change can quietly break PDF/A validity. Run a validator (for example verapdf) as a gate before the bundle is released.

bash
# Fail the export if the document is not valid PDF/A; a broken profile is a §11.10(b) defect.
verapdf --flavour 3b audit_trail.pdf

Treat a validator failure as a release-blocking defect, not a warning. A document that renders correctly on the engineer’s screen but fails conformance carries a latent risk: the fonts, transparency, or metadata that the current viewer tolerates may be exactly what a future archival reader cannot resolve, at which point the human-readable copy is unreadable and the §11.10(b) obligation is unmet with no opportunity to re-render from a decommissioned system. Because the conformance check is deterministic, it belongs in the same CI stage that runs the chain re-verification, so a single pipeline run proves both that the data is intact and that the document carrying it will endure. Where a validator reports a specific rule violation — an unembedded glyph, a disallowed blend mode — fix the renderer rather than suppressing the rule, since the profile exists precisely to forbid the features that compromise longevity.

Compliance Validation Checklist

Run these as part of computerized-system validation; each is something an auditor can independently confirm for this document.

Troubleshooting

Symptom Root cause Fix
PDF/A validator rejects the file Font referenced but not embedded Register and embed a licensed font with TTFont; re-run the validator
Attachments missing after render reportlab output not post-processed by pikepdf Run embed_chain_and_manifest after render_pages; assert attachment names
Printed hash differs from attached chain Timestamp or value reformatted during render Draw the stored strings verbatim; never re-parse event_utc to local time
File seal changes on every run Non-deterministic metadata (creation date) written by the library Pin document metadata; digest only after the final pdf.save
Document opens but validator flags transparency A rendering feature disallowed in PDF/A was used Remove transparency/blend features; keep to flat table drawing

For architectural context, this guide sits under audit trail export for regulatory submissions.