EQTY LabDocs

PDFGen Overview

Role and responsibilities of PDFGen, the service that renders and signs policy reports.

View as Markdown

PDFGen renders the policy reports users export from Guardian. When a user exports a report, Governance Service fetches the applied policy’s manifest and attachments from Integrity Service and sends them to PDFGen. PDFGen lays out the report PDF, signs it through Auth Service, and returns a .zip by default, or the PDF alone. Reports describes what a report contains.

PDFGen is internal. Governance Service is its only caller, and the chart gives it no ingress. Any pod in the cluster can still reach it unless you turn on the chart’s network policy, and a request without a token gets an unsigned PDF. Integrators export reports through the Governance Service report endpoint, so PDFGen has no API reference of its own.

What PDFGen Owns

  • The report template, and the fonts it renders with: the brand faces, Noto fallbacks for CJK, Arabic, Hebrew, emoji and other scripts, and a last-resort font for characters none of them cover
  • Rendering the report as a PDF/A-3a document, each statement’s markdown included
  • Packaging the .zip: report.pdf, manifest.json, the attachments/ folder, and .parsed-manifest.json, the report data the PDF was rendered from
  • Signing the PDF: requesting the signature from Auth Service, adding an RFC 3161 timestamp, and embedding both in the PDF

What PDFGen Depends On

PDFGen keeps no state. It has no database or object storage: each request carries the whole manifest, and the pod’s disk holds a request’s attachments only until its response is sent.

Governance Service lets a caller export a project’s report only with Edit Project Settings, which Organization Owners and Project Owners hold. PDFGen then calls Auth Service to sign the report with the caller’s token, a user’s or an API key’s. Auth Service checks that permission again, and signs with the platform key, which stays in Auth Service’s key provider. It then calls a timestamp authority, http://timestamp.digicert.com by default, for a trusted signing time; installs without internet egress can turn this off. The report template’s packages ship in the image, so rendering itself never reaches the network.

A report Governance Service requests is always signed. If signing or timestamping fails, the export fails; PDFGen never falls back to an unsigned PDF.

Report Signatures

The signature is ECDSA with SHA-256 on the curve the platform key was created with. With the default, secp256k1, the signature is valid but Adobe Acrobat and other NSS-based verifiers, such as poppler’s pdfsig, report it as invalid, because NSS does not support that curve. Verifiers built on OpenSSL, such as pyHanko, accept it. A P-256 platform key verifies everywhere; see Key Configuration.

Where to Go Next

  • Use Reports to export a report from Guardian or from a script.
  • Use Chart Values for the eqty-pdfgen values the platform chart exposes.