PDF Settings - Rest PKI Core

The settings of the Pdf section are the instance defaults for how Rest PKI Core handles PDFs: whether and how the PDF gets validation marks before its first signature, and, when PDF/A conversion is available, how the conversion behaves.

Each organization can override the marking settings in the PDF settings page of the dashboard. A field left empty (or as Use system default, in the marking policy) uses the value of the instance, and the Reset configurations action returns the organization to the values of the instance. Restart the application after changing the settings described here.

Marking settings

In the Pdf section:

• MarkingPolicy (v1.10.0, default: WhenPossible): the instance's PDF marking policy, which decides whether a PDF gets validation marks before its first signature. The values are Never (the original PDF is signed, without marks), WhenPossible (tries to add the marks and, if the submitted PDF already has signatures, silently signs the original) and Always (the marks are mandatory: a PDF submitted already signed fails with PdfAlreadySigned). It applies to organizations that don't set the PDF marking policy in the dashboard (the Use system default option). As an environment variable: Pdf__MarkingPolicy.

Layout of the validation marks

The validation marks of a PDF have three elements:

• a watermark strip along the right margin, with an image over a background color, rotated to run along the edge of the page;
• the access text along the left margin, written vertically, with the link to validate the document, over a white box that keeps it legible;
• a QR code, at the top left.

The settings below change the colors, opacities, sizes and margins of these elements. The width of the watermark strip is fixed, at 1.8 cm. For the image of the watermark, see Watermark image.

In the Pdf section:

• WatermarkBackgroundColor (v1.10.0, default: F5F8FD): the color the watermark strip shows over a white page, as an HTML color: #RRGGBB or RRGGBB. As an environment variable: Pdf__WatermarkBackgroundColor.
• WatermarkBackgroundOpacity (v1.10.0, default: 0.25): the opacity of the background of the watermark strip, as a fraction from 0 (transparent) to 1. It decides how much of the page content under the strip shows through: over a white page, raising it doesn't darken the strip. As an environment variable: Pdf__WatermarkBackgroundOpacity. The equivalent WatermarkBackgroundOpacityPercent setting takes the opacity in percent, from 0 to 100: use one or the other, not both.
• WhiteOverlayOpacity (v1.10.0, default: 0.75): the opacity of the white box under the access text, as a fraction from 0 to 1. As an environment variable: Pdf__WhiteOverlayOpacity. It also has an equivalent in percent, WhiteOverlayOpacityPercent, from 0 to 100: use one or the other, not both.
• QRCodeSize (v1.10.0, default: 1.8): the width and height of the QR code, in centimeters. A bigger QR code also moves the access text down. As an environment variable: Pdf__QRCodeSize.
• QRCodeMargin (v1.10.0; optional, no default, since v1.11.0): the distance from the QR code to the top and left edges of the page, in centimeters. When it is not set, the QR code uses TopMargin and LeftMargin. As an environment variable: Pdf__QRCodeMargin.
• LeftMargin (v1.11.0, default: 0.5): the distance from the access text to the left edge of the page, in centimeters. It is also the distance of the QR code when QRCodeMargin is not set. As an environment variable: Pdf__LeftMargin.
• TopMargin (v1.11.0, default: 0.5): the distance from the QR code to the top edge of the page, in centimeters, when QRCodeMargin is not set. As an environment variable: Pdf__TopMargin.
• BottomMargin (v2.5.0, default: 0.5): the distance from the access text to the bottom edge of the page, in centimeters. There is no field for it in the dashboard: it is always the value of the instance. As an environment variable: Pdf__BottomMargin.

Dashboard fields

In the PDF settings page of the dashboard, each organization can set its own values. When the organization has no value for a field, the page shows Use system default: followed by the value of the instance. The opacities are shown in percent in the dashboard, and as fractions in the instance settings.

Instance setting	Dashboard field
MarkingPolicy	PDF marking policy
WatermarkBackgroundColor	Watermark background color
WatermarkBackgroundOpacity	Watermark background opacity (in percent)
WhiteOverlayOpacity	White overlay opacity (in percent)
QRCodeSize	QR code size
QRCodeMargin	QR code margin
LeftMargin	Left margin
TopMargin	Top margin
BottomMargin	None: only the instance setting
Watermark image	Watermark image (PNG)

Watermark image

The image of the watermark is chosen in this order:

1. the image that the organization uploaded in the PDF settings page of the dashboard;
2. the image of the instance, described below;
3. the image built into the application.

To define the image of the instance, put a PNG file named watermark.png in the assets folder of the Blob Storage configured for the instance. For instance, with the FileSystem type, the file is <Path>/assets/watermark.png, where <Path> is the Path of the Blob Storage. There is no setting for it. After adding or replacing the file, restart the application.

Use a PNG. The built-in one is 1120 x 126 pixels, with a transparent background: a wide and short image, since it is rotated and drawn along the right margin of the page, in the watermark strip. Use an image with similar proportions.

Configuration example

To move the access text and the QR code closer to the left edge of the page, in the configuration file:

[Pdf]
LeftMargin=0.2

As environment variables:

Pdf__LeftMargin=0.2

PDF/A settings

These settings only apply when the PDF/A conversion is available on the instance. They are in the Pdf section, in the nested section PdfA:

• PdfA:DefaultProfile (v4.2.0, default: PdfA2b): the PDF/A profile to convert to. The values are PdfA1a, PdfA1b, PdfA2a, PdfA2b, PdfA2u, PdfA3a, PdfA3b, PdfA3u, PdfA4, PdfA4e and PdfA4f. As an environment variable: Pdf__PdfA__DefaultProfile.
• PdfA:ProfileAcceptancePolicy (v4.2.0, default: Any): what to do with a PDF that is already PDF/A. With Any, a PDF that already complies with any PDF/A profile is accepted as it is. With StrictDefault, the PDF must comply with the DefaultProfile: a PDF that doesn't, even if it complies with another PDF/A profile, is converted to the DefaultProfile (if it is already signed, AcceptNonPdfASignedFiles decides). As an environment variable: Pdf__PdfA__ProfileAcceptancePolicy.
• PdfA:AcceptNonPdfASignedFiles (v4.2.0, default: true): what to do with a PDF that is already signed and doesn't pass the PDF/A check (with StrictDefault, doesn't comply with the DefaultProfile), since it can't be converted without invalidating its signatures. With true, the signature goes on without the conversion. With false, the PDF is rejected. As an environment variable: Pdf__PdfA__AcceptNonPdfASignedFiles.