Skip to main content
Version: 1.3

Certify a PDF document

The Pdftools SDK lets you apply a document certification signature, also known as a Modification Detection and Prevention (MDP) signature, to a PDF document. This type of signature records the identity of the document author. It also allows users to make specific changes to the document, such as filling form fields, without invalidating the signature.

There can be at most one document certification signature in a document, and it must be added before any other signatures are added to the document.

Quick start

Download the full sample now in C# and Java.

Interested in C or other language samples? Let us know on the contact page and we'll add it to our samples backlog.

In this example, the Built-in cryptographic provider is used to digitally certify a PDF document. The permissions allow a user to fill form fields. Any other changes to the document cause the signature to be rejected.

note

Any of the cryptographic providers supported by the Pdftools SDK can be used to apply a document certification signature.

Steps to certify a document:

  1. Initialize the cryptographic provider.
  2. Read the PFX or P12 certificate.
  3. (Optional) Add long-term validation information
  4. (Optional) Add user modification permissions
  5. Open and sign the document.
Before you begin

You need to initialize the library.

Initializing the cryptographic provider​

When using the Built-in cryptographic provider, you start the digital signing process by instantiating the Provider object. The Provider object exposes the methods of the cryptographic provider. The cryptographic provider manages certificates and private keys, and implements cryptographic algorithms.

// Create a session to the built-in cryptographic provider
using var session = new BuiltIn.Provider();

Reading the PFX or P12 certificate​

Using the Built-in cryptographic provider, PFX certificate files can be loaded directly into the cryptographic provider from the file system. The certificate file is opened as a stream and loaded into the provider to prepare it to apply a digital signature.

// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);

Adding long-term validation information​

As an optional step, long-term validation information can be added to the output document. It embeds revocation information such as online certificate status response and certificate revocation lists. Revocation information is provided by a validation service at the time of signing and acts as proof that the certificate was valid at the time of signing.

// Embed validation information to enable the long-term validation (LTV) of the signature
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;

Adding user modification permissions​

As an optional step, the author may permit users to make specific modifications to the document without the signature being revoked. In this example, the user is permitted to fill form fields.

// Assign Form Filling user permissions to the document
var permissions = new MdpPermissionOptions(MdpPermissions.FormFilling);

Opening and signing the document​

After instantiating the Provider and preparing the signature configuration, you are ready to digitally certify a document.

The input and output PDF documents are created as streams (in this example, as file streams). The Signer object is used to apply the digital certification.

Non-critical processing errors raise a Warning event. It is recommended to listen for these events, and review the WarningCategory to determine if further action is needed.

// Open the input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

// Create a stream for the output file
using var outStr = File.Create(outPath);

// Create the Signer object
Signer signer = new Signer();

// (optional) Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);

// Certify the output document
using var outDoc = signer.Certify(inDoc, signature, outStr, permissions);

Full example​

// Create a session to the built-in cryptographic provider
using var session = new PdfTools.Crypto.Providers.BuiltIn.Provider();

// Create signature configuration from PFX (or P12) file
using var pfxStr = File.OpenRead(certificateFile);
var signature = session.CreateSignatureFromCertificate(pfxStr, password);

// Embed validation information to enable the long-term validation (LTV) of the signature (default)
signature.ValidationInformation = PdfTools.Crypto.ValidationInformation.EmbedInDocument;

// Assign Form Filling user permissions to the document
var permissions = new MdpPermissionOptions(MdpPermissions.FormFilling);

// Open input document
using var inStr = File.OpenRead(inPath);
using var inDoc = Document.Open(inStr);

// Create stream for output file
using var outStr = File.Create(outPath);

// Create the Signer object
Signer signer = new Signer();

// Create an event listener to listen for warning events that are raised and write them to console
signer.Warning += (s, e) => Console.WriteLine("Warning - {0}: {1}: {2}", e.Category, e.Context, e.Message);

// Certify the output document
using var outDoc = signer.Certify(inDoc, signature, outStr, permissions);
Signature visual appearance

You can also apply a visual appearance to the signatures. For more information, see Create a signature visual appearance page.

Signing PDF/A documents

During the conversion process from PDF to PDF/A, any signatures are removed from the file before it is converted to PDF/A for archiving. Therefore, files that require archiving should be archived to PDF/A format before any digital signatures are applied.