Digitally sign the PDFs of Approval Path (manual export, PDF step, list and chart exports)

Description

Goal

Every PDF Approval Path creates is digitally signed, so whoever receives it can check that it comes from Approval Path and has not been changed.

Requested by Kamil on PR 6214 (AP-427, comment 904264307). Moved to its own ticket on 2026-11-17: the Warsaw Dynamics signing certificate has expired, and this ticket waits for its renewal (GEN-902).

Requirements

  • Sign in the shared PDF engine, so the manual export (AP-427), the PDF step's attachments and emails (AP-541) and the later list and chart exports (AP-2368, AP-2369) are all signed.

  • PKCS#7 signature with a key in Google Cloud KMS, an RFC 3161 timestamp and LTV data (long-term validation); Approval Path's own signer name; PDF metadata set; editing restricted.

  • A failed signing fails the export: no unsigned file is ever handed out.

Decisions

  • Variant 1, like Document Sign (Kamil, 2026-11-17): Contract Signatures' signing code, a KMS key, PKCS#7 with a timestamp, no browser.

  • Certificate (leader, 2026-11-17): production signs with the Warsaw Dynamics certificate from the Adobe-trusted certificate authority (GEN-902). It is issued to Warsaw Dynamics, so several apps can use it, and Adobe shows the signature as valid. Dev and QA sign with a test certificate from our own Warsaw Dynamics CA; Adobe shows those as signed by an unknown signer.

  • LTV is added when the certificate chain has revocation addresses (OCSP / CRL), as certificates from the authority do; the dev / QA test CA has none, so there it is skipped and that does not fail the export. Any other signing failure (KMS, timestamp, PKCS#7) fails the export.

  • Timestamp authority: http://timestamp.digicert.com, as Contract Signatures uses.

To confirm before implementing

  1. The lib module for the signing code moved out of document-sign, and whether Contract Signatures switches to it in the same PR (its tests must stay green).

  2. Signature name "Approval Path for Jira" / "Approval Path for Confluence" and reason "Approval record exported by Approval Path"; the certificate itself names Warsaw Dynamics.

  3. Permissions: printing, copying text and accessibility allowed; editing, annotations, form filling and page changes blocked; plus a certification signature that allows no changes.

  4. Signing not configured on QA / production: the backend refuses to start (recommended: the deploy then fails its health check and rolls back, instead of shipping exports that fail), or the export fails with a clear error.

Approach

  • Reuse Contract Signatures' signing code, moved to lib if it stays clean:

    • document-sign/src/main/java/ovh/atlasinc/pdf/ (PdfSigner, PdfSignRequest, PdfTweaker, PdfTweakRequest, about 750 lines including pki);

    • ovh/atlasinc/pki/ (GoogleCloudPkcs7Signer, LocalPrivateKeyPkcs7Signer, Pkcs7Signer, SimpleKeyStore, TimeStampingClient, TimeStampingHttpClient);

    • wiring and defaults: ovh/atlasinc/pe/GoogleCloudPkcs7SignerBuilder (SHA384_WITH_ECDSA, timestamp authority http://timestamp.digicert.com);

    • the KMS content signer GoogleCloudContentSigner is already in lib/google-encryptor;

    • tests PdfSignerTest, PdfTweakerTest.

  • Versions: document-sign uses pdfbox and pdfbox-examples 3.0.4 (LTV through AddValidationInformation) and bc*-jdk18on 1.80; Approval Path gets pdfbox 3.0.8 through openhtmltopdf. Align them (see also GEN-871).

  • Hook: ovh.atlasinc.ap.pdf.PdfRenderer.render, the one engine of every PDF of the epic. Sign the finished bytes and check the size limit after signing.

  • Callers:

    • ReferencePdfService.export (manual export): signing errors come back as 4xx / 5xx with a message.

    • ReferencePdfService.exportApproval with PdfStepRunner (PDF step): KMS and timestamp outages are temporary failures, retried through PdfAttempt.isTransient.

  • Outbound HTTP (the timestamp authority, the authority's OCSP / CRL servers) follows the app's egress rules (EgressGuard).

  • Locally and in tests: a self-signed test key (LocalPrivateKeyPkcs7Signer), so nobody needs KMS access.

  • Tests: the signature, the timestamp (stub timestamp authority) and the permissions verified with a test key; signing fails, so the export fails.

Acceptance criteria

  • Every PDF of the manual export and of the PDF step is signed and timestamped. On production, Adobe Acrobat Reader shows "Signed and all signatures are valid", with the timestamp and LTV.

  • Changing the PDF breaks the signature; editing is blocked, printing and copying text still work.

  • When signing fails, the manual export shows an error and the PDF step fails or retries; no unsigned PDF is handed out.

Manual tester notes

  • Jira: "..." > "Export approvals to PDF" > Export, open the PDF in Adobe Acrobat Reader. The signature panel shows a signature by "Approval Path for Jira" with a timestamp. On QA Adobe says the signer is unknown (test certificate); that is expected there.

  • In Acrobat, try to edit text or add a page: it is not allowed.

  • A definition with a PDF step that emails and attaches the PDF: both PDFs are signed the same way.

  • Confluence: the same, with "Approval Path for Confluence".

Before release

GEN-902 must be done first. On each environment (dev, QA, production), before the backend with signing is deployed:

  1. Key and certificate: dev and QA have the test key and the certificate from our CA, production the renewed Adobe-trusted certificate (steps and outputs in GEN-902).

  2. The service account that environment's backend uses for Google Cloud has roles/cloudkms.signerVerifier on that environment's key.

  3. Backend configuration: the key version name, the certificate chain PEM and the Google Cloud credentials file. The property names come with the implementation and are listed here then.

  4. The backend can reach timestamp.digicert.com and, on production, the authority's OCSP / CRL servers.

  5. After the deploy: export one PDF in Jira and one in Confluence and open them in Adobe Acrobat Reader. On production the signature must show as valid, with the timestamp and LTV.