PDF stamps - Rest PKI Core

A stamp is a PAdES document timestamp that Rest PKI Core adds to a PDF: a timestamp from one of the instance's timestamp tiers, embedded in the PDF as a signature field, which proves that the document existed in that exact form at that time. It doesn't involve a signer's certificate, so no user takes part. Optionally, the stamp has a visible appearance, with text and an image, on one page of the PDF.

tip

From this point on we'll describe calls to Rest PKI Core. Make sure you've read the Get Started article to be able to keep up. The application's API key needs a role that allows stamping PDFs, such as Worker (see Choosing roles).

Stamping a PDF

On .NET, call IRestPkiService.StampPdfAsync() with the PDF, as a file reference, and the options:

var result = await restPkiService.StampPdfAsync(FileReference.FromFile(@"C:\AppData\Documents\document.pdf"), new StampPdfOptions() {
	TimestampTier = "PkiBrazil",
});

// result.File is a reference to the stamped PDF

Pass the options even if you set none of them: StampPdfAsync() doesn't accept null.

If calling the API directly, do:

POST {endpoint}/api/pdf/stamp
{
	"file": {
		"content": "JVBERi0xLjcK...",
		"name": "document.pdf"
	},
	"timestampTier": "PkiBrazil"
}

The request has these fields (in .NET, the properties of StampPdfOptions, with the same names):

Field	Description
`file`	The PDF. Required
`timestampTier`	The ID or name of the timestamp tier, such as `PkiBrazil`. If omitted, Rest PKI Core uses the instance's default tier: on the SaaS instance, always name the tier (see Requesting timestamps)
`customSignatureFieldName`	The name of the signature field of the stamp in the PDF. Up to 100 characters, without dots
`reason`	The reason recorded in the stamp. Up to 1024 characters
`visualRepresentation`	The visible appearance of the stamp: see below. Without it, the stamp is not visible on the pages
`forceBlobResult`	Return the stamped PDF as a temporary link even when it is small (see The result)

The call fails with TimestampTierNotFound when the tier doesn't exist, with TimestampTierDisabled when it is disabled, and with TimestampTierRestricted when your subscription can't use it. A page number beyond the last page fails with InvalidPage.

On Node.js, the restpki-core-client library calls this route with stampPdf(), and on Python, restpki-ng-python-client with PdfApi.api_pdf_stamp_post(). The Java and PHP libraries have no working method for it: call the route directly, as described in Calling the API directly.

Each stamp is counted as a PDF stamp transaction. The call fails when the subscription has reached its limit of PDF stamp or of timestamp transactions.

The visible appearance

visualRepresentation takes the same model as the visual representation of a PAdES signature, with text, image and position. For instance, the stamp drawn by the dashboard's demo, at the bottom of the first page:

"visualRepresentation": {
	"text": {
		"text": "Lacuna Software",
		"fontSize": 13.0,
		"includeSigningTime": true,
		"horizontalAlign": "Left",
		"container": { "left": 0.2, "top": 0.2, "right": 0.2, "bottom": 0.2 }
	},
	"image": {
		"resource": { "url": "https://cdn.lacunasoftware.com/img/pdf-stamp.png", "mimeType": "image/png" },
		"horizontalAlign": "Right",
		"verticalAlign": "Center"
	},
	"position": {
		"pageNumber": 1,
		"measurementUnits": "Centimeters",
		"auto": {
			"container": { "left": 1.0, "right": 1.0, "bottom": 1.0, "height": 4.94 },
			"signatureRectangleSize": { "width": 8.0, "height": 4.94 },
			"rowSpacing": 0.3,
			"horizontalDirection": "LeftToRight",
			"verticalDirection": "BottomUp"
		}
	}
}

The text is drawn as given: tags such as {{name}}, which a signature replaces with data of the signer's certificate, are not replaced on a stamp, since there is no signer.

The result

The result is the stamped PDF, as a file reference: in content, in Base64, when it has up to 5 MB, or else as a url from which you can download it for a limited time. With forceBlobResult = true, it always comes as a url. In .NET, result.File is a FileReference.

Inspecting the stamped PDF with signature inspection lists the stamp as a signer with isDocumentTimestamp = true.

Signed PDFs

You can stamp a PDF that is already signed. Rest PKI Core doesn't validate the signatures already in it when stamping, and the stamp is added the way a new signature is, as the PKI SDK does to add LTV to a signed PDF.

Trying it on the dashboard

On instances that issue timestamps, the dashboard has a demo: on the left menu, click Demos, then PDF Stamp. Choose a Timestamp tier, upload a PDF and click Stamp: the dashboard opens the stamped PDF, with the appearance shown above.

Stamps and PDF marks

A stamp is not the newer form of the PDF marks of Rest PKI (PdfMarker, POST Api/Pdf/AddMarks), which draw text, images and QR codes on the pages, for instance to make the printer-friendly version of a signed document. Rest PKI Core still serves the marks route with the Rest PKI models (see Moving from Rest PKI), and the two do different things:

	PDF marks (`Api/Pdf/AddMarks`)	Stamp (`api/pdf/stamp`)
What it adds	Drawings on the pages, without cryptography	A document timestamp, with an optional appearance
What it can draw	Several elements per mark, with styled text, images, QR codes, borders, backgrounds and rotation	One appearance, with a text and an image
Where	Every page, one page (counted from the start or the end) or a new page	One page
On a signed PDF	Invalidates the signatures, unless `abortIfSigned` makes the call fail with `CannotApplyPdfMarks` instead	Stamps it (see Signed PDFs)
Timestamp	None	Issued by a timestamp tier
On Rest PKI	`PdfMarker`	No equivalent

Stamping a PDF​

The visible appearance​

The result​

Signed PDFs​

Trying it on the dashboard​

Stamps and PDF marks​

See also​