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 will display 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, it 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 then 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, and the TSA module can be used 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 will help validate the signature even after the signer's certificate is expired. (Though it will 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 and/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 | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
REASON | The reason included in the PDF signature and displayed by the PDF reader. Default: "Signed by SignServer". | ||||||||||||
LOCATION | The location included in the PDF signature and displayed by the PDF reader. Default: "SignServer". | ||||||||||||
ADD_VISIBLE_SIGNATURE | Controls whether the signature to be added should be visible or invisible. Possible values: True or False. Default: False. | ||||||||||||
VISIBLE_SIGNATURE_PAGE | Specifies the page on which the visible signature will be drawn. This property is ignored if ADD_VISIBLE_SIGNATURE is set to False. Possible values:
Default: First. | ||||||||||||
VISIBLE_SIGNATURE_RECTANGLE | Specifies the rectangle that the signature is going to be drawn in. Default: "400,700,500,800". | ||||||||||||
VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 & VISIBLE_SIGNATURE_CUSTOM_IMAGE_PATH | 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.
| ||||||||||||
VISIBLE_SIGNATURE_CUSTOM_IMAGE_RESIZE_TO_RECTANGLE | If you want the custom image to be resized 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 will be resized to the specified image's sizes. | ||||||||||||
CERTIFICATION_LEVEL | 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. Default: "NOT_CERTIFIED". | ||||||||||||
TSA_URL | If you want to timestamp the document signature, specify the timestamp authority URL.
Default: not set (no timestamping). | ||||||||||||
TSA_WORKER | Specify a worker ID or worker name for a time stamp signer
Default: Not set (no timestamping). | ||||||||||||
TSA_USERNAME & TSA_PASSWORD | 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). Default: not set (tsa does not require authentication). | ||||||||||||
EMBED_CRL | If you want to embed the CRL for the signer certificate inside the signature package, set to True, otherwise set to False. Default: False. | ||||||||||||
TSA_DIGESTALGORITHM | Algorithm for timestamp digests. Optional, default: SHA-256. | ||||||||||||
EMBED_OCSP_RESPONSE | To embed the OCSP response for the signer certificate inside the signature package, set to True, otherwise set to False.
Default: False. | ||||||||||||
ARCHIVETODISK | 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. Default: False. | ||||||||||||
ARCHIVETODISK_PATH_BASE | The file path to the folder to store the signed documents. Required if ARCHIVETODISK is True. | ||||||||||||
ARCHIVETODISK_PATH_PATTERN | 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 fields are:
Default: "${DATE:yyyy/MM/dd}". | ||||||||||||
ARCHIVETODISK_FILENAME_PATTERN | Pattern used for creating the filename. The same fields and syntax as for the ARCHIVETODISK_PATH_PATTERN property can be used. | ||||||||||||
REFUSE_DOUBLE_INDIRECT_OBJECTS | True if PDF documents containing multiple indirect objects with the same name should be refused. Used to mitigate a collision signature vulnerability described in http://pdfsig-collision.florz.de/. Default: False. | ||||||||||||
REJECT_PERMISSIONS | Reject signing of the document if any of the permissions in the comma-separated list would be in the document.
Default: Unset/empty (no permissions are rejected) | ||||||||||||
SET_PERMISSIONS | Replace the current permissions (if any) with the permissions specified in this comma-separated list of permissions. Available permissions: The same permission names as for the property REJECT_PERMISSIONS.![]() ![]() ![]() Default: Unset (permissions are not set by this property) | ||||||||||||
REMOVE_PERMISSIONS | Remove all permissions specified in this comma-separated list from the document. Available permissions: The same permission names as for the property REJECT_PERMISSIONS. This property cannot be specified if SET_PERMISSIONS is used. ![]() See ![]() Removing only ALLOW_DEGRADED_PRINTING has no effect, as degraded printing is implicitly allowed if printing is allowed. Default: Unset/empty (no permissions are removed) | ||||||||||||
SET_OWNERPASSWORD | Sets the specified password as the owner password in the document. The same permissions as before will be used (unless other properties will change them). The same encryption algorithm as the original document will be used. If the original document did not use any encryption then the default encryption algorithm will be used. Default: unset (if the permissions are changed, the existing owner password will be used or if no such password is used in the document a semi-random password will be created) | ||||||||||||
DIGESTALGORITHM | Sets the hash algorithm used for the message digest and signature hash.
Default setting is SHA256. | ||||||||||||
ALLOW_PROPERTY_OVERRIDE | 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. Default: not set (no properties are allowed to be overridden). | ||||||||||||
ALLOW_SIGNING_WITHOUT_OWNERPASSWORD | 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 | Set to FALSE if the document has no signature and the PDF Signer should not use the appended signature. The PDF Signer will then instead rewrite the document and use an embedded signature in it. 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. This setting is by default not set. Setting this property to TRUE or to an invalid value is the same as leaving this property unset. |
Request Metadata Properties
The following properties can be sent by the client with the request:
Property | Description |
---|---|
pdfPassword | User/open password to use for reading the PDF if it is password protected. |
REASON | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
LOCATION | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
CERTIFICATION_LEVEL | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
SIGNERCERTCHAIN | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
DIGESTALGORITHM | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
ADD_VISIBLE_SIGNATURE | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
VISIBLE_SIGNATURE_PAGE | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
VISIBLE_SIGNATURE_RECTANGLE | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
VISIBLE_SIGNATURE_NAME | Sets the visible signature in the existing empty signature filed with this name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
VISIBLE_SIGNATURE_CUSTOM_IMAGE_RESIZE_TO_RECTANGLE | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
USE_TIMESTAMP | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
EMBED_CRL | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
EMBED_OCSP_RESPONSE | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
REJECT_PERMISSIONS | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
SET_PERMISSIONS | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
REMOVE_PERMISSIONS | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |
SET_OWNERPASSWORD | Overrides the worker property with the same name. Only allowed if listed in ALLOW_PROPERTY_OVERRIDE. |