PDF validation marks - Rest PKI Core
Before the first signature of a PDF, Rest PKI Core can produce a copy of it with validation marks: visual elements, such as the link to verify the document, that help whoever reads the PDF check its signature. How the marks look comes from the marking options of the organization (subscription). That copy is the marked file, and it is the one that gets signed when the PDF is marked.
The marked file appears as markedFile in the document summary (GET api/documents/{id}) and in the webhook notifications. It only
exists when the original file is a PDF and was marked; otherwise it is null. Applications that perform CMS signatures of PDFs can hand the marked file
to users instead of the .p7s file: it is a PDF that anyone can open. In detached CMS signatures, the marked file is the data file that corresponds
to the .p7s.
A co-signature of a document that was already signed in the system never gets marks. Marking only applies to signatures made through api/signature (two-step) and signature sessions; the legacy Rest PKI-compatible APIs never mark the PDF.
Marking policy
The PDF marking policy decides whether the PDF is marked before being signed and what happens when the marks can't be added. Adding marks to a PDF that already has signatures would invalidate them, and that is where the policies differ:
| Value | In the dashboard | Behavior |
|---|---|---|
Never | Never | No marks are added: the original PDF is signed. |
WhenPossible (default) | When possible | Rest PKI Core tries to add the marks. If the submitted PDF already has signatures (for example, it was signed elsewhere), the marked file is silently discarded and the original PDF is signed. |
Always | Always | The marks are mandatory. If the submitted PDF already has signatures, the two-step signature fails with the PdfAlreadySigned code and, in a signature session, the signer sees a file-already-signed error. |
Configuration
The policy is set per organization, in the PDF marking policy option of the dashboard. The Use system default option leaves the organization
without its own policy, so the instance setting Pdf:MarkingPolicy applies, whose default is WhenPossible. See
PDF Settings. The policy is not chosen per request.
Don't confuse it with the custom marks of a PAdES signature (PdfSignatureOptions.Marks) or with the marks of api/pdf/AddMarks: those are
different features, described in PDF stamps.