PDF Signer

The PDF signer has the class name: org.signserver.module.pdfsigner.PDFSigner.

Overview

The main purpose of the PDF signer is to add digital signatures to PDF documents.

The signer supports the addition of visible or invisible signatures. Both visible and invisible signatures serve the same purpose of signing a document, and technically are equivalent in that sense. The difference is that when a visible signature is applied to a document, a signature image (in the shape of a rectangle) is placed at the specified place in the document. Clicking the signature image displays the properties of the signature (Adobe Acrobat Reader).

In contrast, when applying an invisible signature, the signature properties are accessed via menu items. For visible signatures, properties such as custom signature image, signature rectangle, page at which the signature rectangle will be drawn, and so on can be specified (see Worker Properties).

PDF Signer can also apply a timestamp to a signature. If the signature is timestamped, the timestamp can be viewed through signature properties in Adobe Acrobat Reader. Timestamping is used to prove that the document was signed before the time specified by the timestamp token. If the signature is not timestamped, the signature time specified in the signature properties is not considered to be trusted.

It is strongly advised to apply a timestamp to a signature. You can use the TSA module for this purpose.

Also, the CRL or OCSP Response of the signer's certificate can be embedded inside the signature package. Embedding the CRL or OCSP response with the package helps validate the signature even after the signer's certificate is expired. However, embedding the response does not guarantee long-term signature preservation. The topic of long-term signature preservation for archival purposes is a large one and is discussed to be implemented in future versions of SignServer.

The PDF Signer can also be configured to enforce that certain PDF permissions are not available in the signed document or that certain permissions should be removed.

PDF Passwords

PDF documents can optionally be protected by a password. There are two different types of passwords:

User Password: Also sometimes referred to as "open password" or "document password". Can be used for reading an encrypted document.
Owner Password: Also sometimes referred to as "permission password" or "security restriction password". It can be used for reading an encrypted document and making changes to a document that has permissions.

If a document is protected by an Owner password, it has to be supplied with the request for SignServer to sign the document. If the document is protected by a User password, either the User password or the Owner password has to be supplied with the request for SignServer to sign the document.

PDFSigner Requests

PDF signing requests can be served using either web services or the web server interface (HTTP). See SignServer Integration for general information about the different interfaces.

For the web server interface, the GenericProcessServlet can be used. The PDFSigner supports the extra request field "pdfPassword" letting the client supply a PDF password to be used for opening the PDF for signing (not required unless the PDF is already password protected).

For the old web services interface, the request should contain an encoded GenericProcessesRequest and the response will be a GenericProcessResponse. It is possible to supply a PDF password by including it in the requestMetaData with the key "pdfPassword".

Worker Properties

The following properties can be configured with the signer:

Property

Default

Description

ADD_VISIBLE_SIGNATURE

False

Controls whether the signature to be added should be visible (true) or invisible (false).

ALLOW_PROPERTY_OVERRIDE

Not set (no properties are allowed to be overridden)

Comma-separated list of worker properties that are allowed to be overridden by request metadata properties with the same names.

See Request Metadata Properties for a list of properties that can be added to this property.

ALLOW_SIGNING_WITHOUT_OWNERPASSWORD

False

By default, the PDF Signer requires the owner's password to sign a PDF that has PDF permissions set.

Setting ALLOW_SIGNING_WITHOUT_OWNERPASSWORD to true allows signing a protected PDF without providing the owner's password. The property is by default set to false for backward compatibility.

APPEND_SIGNATURE

Not set

Set to false if the document has no signature and the PDF Signer should not use the appended signature. The PDF Signer then instead rewrites the document and uses an embedded signature. Setting to false resolves a potential issue with PDFs in format versions 1.6-1.7 and ensures that the PDF is rewritten and that the previous signature is not invalidated.

Setting this property to true or to an invalid value is the same as leaving this property unset.

ARCHIVETODISK

False

If you want the produced signed document to be stored in the local file system, set this property to true and add the ARCHIVETODISK_PATH_BASE property explained below.

ARCHIVETODISK_FILENAME_PATTERN

${WORKERID}-${REQUESTID}-${DATE:HHmmssSSS}.pdf

Pattern used for creating the filename. You can use the same fields and syntax as for the ARCHIVETODISK_PATH_PATTERN property.

ARCHIVETODISK_PATH_BASE

The file path to the folder to store the signed documents.
Required if ARCHIVETODISK is True.

To be able to use this property, you must ensure that the directory where archived documents are written is on the allowlist. See Deploy-time Configuration.

ARCHIVETODISK_PATH_PATTERN

${DATE:yyyy/MM/dd}

Pattern used for creating sub-folders under the ARCHIVETODISK_PATH_BASE folder.
The current date can be specified by adding ${DATE:yyyy} where yyyy can be replaced by the same syntax as defined in the class java.text.SimpleDateFormat.

Other Field Options:

${WORKERID}: ID of the worker processing the request.
${WORKERNAME}: Name of the worker processing the request.
${REMOTEIP}: IP address of requestor.
${REQUESTID}: ID of the request (number).
${TRANSACTIONID}: Transaction ID of the request (number and dashes).
${USERNAME}: User name if username/password authentication has been used.
${CUSTOMHEADER1}: Value of the custom HTTP request header X-SignServer-Custom-1.

CERTIFICATION_LEVEL

NOT_CERTIFIED

Set this property to have the document certified with a certifying signature.

Possible Values:

NOT_CERTIFIED: The document is not certified.
FORM_FILLING: The document is certified but the form can be filled in without invalidating the signature.
FORM_FILLING_AND_ANNOTATIONS: The document is certified but the form can be filled in and annotations added without invalidating the signature.
NO_CHANGES_ALLOWED: The document is certified and no changes can be made.

DIGESTALGORITHM

SHA256

Sets the hash algorithm used for the message digest and signature hash.

Supported hash algorithms	Algorithm PDF version
SHA1	1.3
SHA256	1.6
SHA384	1.7
SHA512	1.7
RIPEMD160	1.7

Setting the DIGESTALGORITHM property also implies a minimum PDF version depending on the hash used. The resulting PDF will be upgraded to this version if it is higher than the version used in the original PDF. Since upgrading the version requires re-creating the file (thus not appending the new signature), DIGESTALGORITHM is not supported on an already signed document (that is, using a hash algorithm requiring a higher version than the original document). Attempting to sign such a document will result in a failure.

EMBED_CRL

False

To embed the CRL for the signer certificate inside the signature package, set to True. Otherwise, set to False.

EMBED_OCSP_RESPONSE

False

To embed the OCSP response for the signer certificate inside the signature package, set to True. Otherwise, set to False.

Issuer certificate (of signing certificate) should be in the certificate chain.

OCSP responses must contain a nextUpdate field in order for offline validation to work with Adobe Reader. For EJBCA OCSP Responder, see configuration of ocsp.untilNextUpdate in ocsp.properties.

LOCATION

SignServer

The location included in the PDF signature and displayed by the PDF reader.

REASON

Signed by SignServer

The reason included in the PDF signature and displayed by the PDF reader.

REFUSE_DOUBLE_INDIRECT_OBJECTS

False

True if PDF documents containing multiple indirect objects with the same name should be refused. Use to mitigate a collision signature vulnerability described in http://pdfsig-collision.florz.de/ .

REJECT_PERMISSIONS

Unset/empty (no permissions are rejected)

Reject signing of the document if any of the permissions in the comma-separated list would be in the document.

Available permissions (from the PDF reference, version 1.6, page 99, TABLE 3.20):

ALLOW_ASSEMBLY

Assemble the document (insert, rotate, or delete pages and create bookmarks or thumbnail images), even if ALLOW_MODIFY_CONTENTS is not set.

ALLOW_COPY

Copy or otherwise extract text and graphics from the document, including extracting text and graphics (in support of accessibility to users with disabilities or for other purposes).

ALLOW_DEGRADED_PRINTING

Print the document (possibly not at the highest quality level, depending on whether ALLOW_PRINTING is also set).

ALLOW_FILL_IN

Fill in existing interactive form fields (including signature fields), even if ALLOW_MODIFY_ANNOTATIONS is not set.

ALLOW_MODIFY_ANNOTATIONS

Add or modify text annotations, fill in interactive form fields, and, if ALLOW_MODIFY_CONTENTS is also set, create or modify interactive form fields (including signature fields)

ALLOW_MODIFY_CONTENTS

Modify the contents of the document by operations other than those controlled by ALLOW_MODIFY_ANNOTATIONS, ALLOW_FILL_IN, and ALLOW_SCREENREADERS.

ALLOW_PRINTING

Print the document to a representation from which a faithful digital copy of the PDF content could be generated. When this is not set (and ALLOW_DEGRADED_PRINTING is set), printing is limited to a low-level representation of the appearance, possibly of degraded quality.

ALLOW_SCREENREADERS

Extract text and graphics (in support of accessibility to users with disabilities or for other purposes).

REMOVE_PERMISSIONS

Unset/empty (no permissions are removed)

Remove all permissions specified in this comma-separated list from the document. See the available permissions in REJECT_PERMISSIONS.

This property cannot be specified if you use SET_PERMISSION.

This property only removes the permissions listed even if some permissions (such as ALLOW_PRINTING) by the standard give more permissions (such as also ALLOW_DEGRADED_PRINTING). To remove all permissions to print, remove both ALLOW_PRINTING and ALLOW_DEGRADED_PRINTING. To still have ALLOW_DEGRADED_PRINTING, it is possible to specify to only remove ALLOW_PRINTING. See notes for REMOVE_PERMISSIONS which also applies to this setting. Removing only ALLOW_DEGRADED_PRINTING has no effect, as degraded printing is implicitly allowed if printing is allowed.

SET_OWNERPASSWORD

Unset

Sets the specified password as the owner password in the document.

The SET_OWNERPASSWORD property uses the same permissions as before (unless other properties change the permissions). The property uses the same encryption algorithm as the original document. If the original document did not use any encryption, the property uses the default encryption algorithm.

If the permissions are changed, the existing owner password is used. If no such password is used in the document, a semi-random password is created.

SET_PERMISSIONS

Unset (permissions are not set by this property)

Replace the current permissions (if any) with the permissions specified in this comma-separated list of permissions. See the available permissions in REJECT_PERMISSIONS.

This property cannot be specified if REMOVE_PERMISSIONS is used.

This property and the REMOVE_PERMISSIONS property only set the permissions setting in the document. All permissions might not be enforced by the PDF reader, and some permissions specified to be allowed by this property, might not be allowed when opening the final document (that is, if that would invalidate the signature and/or certification).

If the document is not already protected by an owner password and the SET_OWNERPASSWORD is not specified, a random password will be used as the owner password.

TSA_DIGESTALGORITHM

SHA-256

(Optional) Algorithm for timestamp digests.

TSA_URL

Not set (no timestamping)

If you want to timestamp the document signature, specify the timestamp authority URL.
This will cause time stamp requests to be issued via HTTP requests. Under high load, this can lead to thread deadlocks in the application server if using a localhost URL (using a time stamp signer running in the same server). In this case, use the internal mechanism described below. To not timestamp the document signature, do not set the property.

If path contains characters "\" or "=" , these characters should be escaped (thus "\" = "\\", "=" =>"\=").

Cannot be set at the same time as TSA_WORKER.

TSA_USERNAME & TSA_PASSWORD

Not set (TSA does not require authentication)

If the TSA requires authentication for timestamping, specify username and password. If the TSA does not require authentication, do not set these properties. These properties are ignored if TSA_URL is not set (no timestamping).

TSA_WORKER

Not set (no timestamping)

Specify a worker ID or worker name for a time stamp signer.
This uses internal calls and can only be used for a time stamp authority running in the same SignServer instance.

Use instead of TSA_URL when using a time stamp signer running in the same SignServer instance to avoid thread deadlocks under high load.

Cannot be set at the same time as TSA_URL.

VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 & VISIBLE_SIGNATURE_CUSTOM_IMAGE_PATH

Not set (no custom image)

If you want the visible signature to contain a custom image, specify the image as base64 encoded byte array. Alternatively, the custom image can be specified by giving a path to the image on the file system.

If both properties are set, VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 will take priority. To disable the feature, do not set the properties.

If specifying a path to an image, "\" should be escaped (C:\photo.jpg => "C:\\photo.jpg").
If specifying image as base64 encoded byte array, "=" should be escaped ("BBCXMI==" => "BBCXMI\=\=").

This property is ignored if ADD_VISIBLE_SIGNATURE is set to False.

In a clustered environment, it is advised to specify the image as a base64 string, since image data will be stored in a central database. Otherwise, each node should contain a copy of the image, and each image managed separately (such as on image updates, or insertion of a new image for a different worker).

In order to use the VISIBLE_SIGNATURE_CUSTOM_IMAGE_PATH, ensure that the paths to the folders containing the images to be used are on the allowlist. For more information, see Deploy-time Configuration.

VISIBLE_SIGNATURE_CUSTOM_IMAGE_RESIZE_TO_RECTANGLE

True

To resize a custom image to a specified rectangle (set by VISIBLE_SIGNATURE_RECTANGLE), then set to True. If set to True, the image might look different than the original, as an effect of resizing. If set to False, the rectangle drawn is resized to the size of the specified image.
If set to False, the llx and lly coordinates specified by the VISIBLE_SIGNATURE_RECTANGLE property are used for drawing the rectangle (urx and ury are calculated from the specified image size).

This property is ignored if ADD_VISIBLE_SIGNATURE is set to False, or if the custom image to use is not specified.

VISIBLE_SIGNATURE_RECTANGLE

400,700,500,800

Specifies the rectangle that the signature is going to be drawn in.
Syntax is: (llx,lly,urx,ury).

llx =left lower x coordinate
lly=left lower y coordinate
urx =upper right x coordinate
ury = upper right y coordinate

This property is ignored if ADD_VISIBLE_SIGNATURE is set to False.

VISIBLE_SIGNATURE_PAGE

First

Specifies the page on which the visible signature will be drawn. Possible values:

First: Signature drawn on the first page of the document.
Last: Signature drawn on the last page of the document.
page_number: Signature is drawn on a page specified by a numeric argument. If the specified page number exceeds the page count of the document, the signature is drawn on the last page. If the page_number specified is not numeric (or negative number), the signature will be drawn on the first page.

This property is ignored if ADD_VISIBLE_SIGNATURE is set to False.

Request Metadata Properties

The following properties can be sent by the client with the request:

With the exception of pdfPassword, these Metadata properties are only allowed if listed in ALLOW_PROPERTY_OVERRIDE.

Property	Description
ADD_VISIBLE_SIGNATURE	Overrides the worker property with the same name.
CERTIFICATION_LEVEL	Overrides the worker property with the same name.
DIGESTALGORITHM	Overrides the worker property with the same name.
EMBED_CRL	Overrides the worker property with the same name.
EMBED_OCSP_RESPONSE	Overrides the worker property with the same name.
LOCATION	Overrides the worker property with the same name.
pdfPassword	User/open password to use for reading the PDF if it is password protected. Does not need to be listed in `ALLOW_PROPERTY_OVERRIDE`.
REASON	Overrides the worker property with the same name.
REJECT_PERMISSIONS	Overrides the worker property with the same name.
REMOVE_PERMISSIONS	Overrides the worker property with the same name.
SET_OWNERPASSWORD	Overrides the worker property with the same name.
SET_PERMISSIONS	Overrides the worker property with the same name.
SIGNERCERTCHAIN	Overrides the worker property with the same name.
USE_TIMESTAMP	Overrides the worker property with the same name.
VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64	Overrides the worker property with the same name.
VISIBLE_SIGNATURE_CUSTOM_IMAGE_RESIZE_TO_RECTANGLE	Overrides the worker property with the same name.
VISIBLE_SIGNATURE_NAME	Sets the visible signature in the existing empty signature filed with this name.
VISIBLE_SIGNATURE_PAGE	Overrides the worker property with the same name.
VISIBLE_SIGNATURE_RECTANGLE	Overrides the worker property with the same name.