Skip to content

Signing

Kertas Perakuan, SIGL, and Surat Sokongan carry regulatory weight and must verify in standard PDF readers. signing-svc is deliberately small and isolated so its surface area is auditable.

Shape

  • Format — PAdES (PDF Advanced Electronic Signatures). Signed PDFs verify in standard readers and embed the signer cert chain, timestamp, and revocation info.
  • Library — pyHanko for PAdES baseline-B signing.
  • Key custody — private keys stored in Google Cloud KMS / HSM. Signing is an authenticated asymmetricSign call; keys never enter application memory.
  • Timestamping — RFC 3161 TSA, using a recognised Malaysian TSA once the trust anchor is chosen (see below).
  • Verification — every signed PDF embeds a public verify URL; any recipient can confirm authenticity without installing anything.

Multi-signer flow

workflow-svc signals signing-svc once all signatories have consented; the document is composed, signed, counter-signed, and sealed. Each signature is a separate KMS call bound to the signer's identity, and each one requires step-up authentication.

sequenceDiagram
  autonumber
  participant WF as workflow-svc
  participant SIGN as signing-svc
  participant CORE as core-svc
  participant KMS as Cloud KMS
  participant TSA as RFC 3161 TSA

  WF->>SIGN: POST /v1/perakuan/sign<br/>{submission_id, signers[], pdf_url}
  loop each signer
    SIGN->>CORE: check perakuan.sign permission
    CORE-->>SIGN: step-up required
    SIGN-->>WF: prompt signer (SPA)
    WF-->>SIGN: consent received
    SIGN->>KMS: asymmetricSign
    KMS-->>SIGN: signature
    SIGN->>TSA: RFC 3161 timestamp
    TSA-->>SIGN: timestamp token
  end
  SIGN->>SIGN: seal + embed verify URL
  SIGN-->>WF: perakuan.signed
  SIGN-->>Storage: upload to siss-signed

Trust anchor — open issue

Decision required before M2 production cutover

The trust anchor is the single largest open issue on the signing path. The architecture spec flags two candidate paths:

  1. Malaysian Digital Signature Act 1997 compliance via a licensed CA (MSC Trustgate, Pos Digicert).
  2. Interim self-signed organisational certs, upgraded to a licensed CA before M6 go-live.

Both paths are workable for M2 dev / UAT. Production cutover cannot happen without this decision. Tracked in Open issues.

Why signing-svc is isolated

  • Tightest compliance surface in the platform — any key-handling mistake is catastrophic.
  • Keeping the service minimal makes the entire KMS-adjacent code path auditable in one sitting.
  • Separate deployment means rotation of signing cert chains or KMS keys doesn't require a platform-wide release.

Verification endpoint

GET /v1/verify/{cert_id} is public and rate-limited. It returns the signer chain and validity status for a given signed certificate — this is the URL embedded in the PDF itself so recipients never have to install tooling.