A PDF document can be signed with a digital signature. Digital signatures allow for the detection and prevention of unauthorized changes to a document, as well as authentication of the signer. Also, digital signatures allow you to define the permissions to changes that are to be permitted, such as adding annotations or filling in and signing forms.

Signatures

There are three types of signatures in PDF: certification signatures, approval signatures and usage rights signature.

• Certification signatures are used to mark the integrity of a document after its first creation, as well as the authenticity of the signer. Also, it defines the permissions that allow certain changes to the document after signing, like adding annotations, or filling in and signing forms. This type of signature, if present, is always the first signature in the document and it may have a visible representation in the document or be hidden. There can be a maximum of one certification signature per document.
• Approval signatures are used to mark the integrity of the document at the time of signing and to authenticate the signer. Such a signature just marks the current state of the document for future verification. Various approval signatures may be present in a document, possibly one for each person that needs to sign.
• Usage rights signatures have a completely different kind of use than the previous two types. It can be used to signal a PDF viewer to give an end-user access to certain features in the viewer, and they are not associated with a SignatureField. The usage rights signature is rarely used and is not currently supported by ImageGear.

ImageGear makes working with signatures simple. It allows for both signing and verification. After signing and saving a document, it will contain the signature(s) inside the file. After loading a signed PDF document, its signatures may be verified and the result will indicate whether the document was changed after signing and whether the signatures can be authenticated.

Signature Fields

Certification and approval signatures are associated with a SignatureField through the field's Signature property. You can assign a signature to this property in order to prepare the actual signing or read it for verification purposes. If the field has not been signed, the Signature property is null.

Signature Handlers

A signature handler is used to specify the algorithm that is used to encode the signature. ImageGear provides a readily available implementation of the most common type of algorithm: PKCS7SignatureHandler. This implementation uses the PKCS#7 detached method (SubFilter adbe.pkcs7.detached) and takes a digital certificate from file or directly as a parameter. Although this sounds complicated, it is really easy to use (see the sample in Signing a Document below).

Signing a Document

Signing a document is subject to the following restrictions:

• You can add only one certification signature per document. An exception is thrown if you attempt to add a second certification signature.
• When attempting to add multiple signatures in a single save, an exception is thrown.
• Currently, ImageGear only supports creation of Approval Signatures for signing.
• When creating a new signature field, it will currently have no appearance. See ImageGear.PDF.Forms.Form.CreateSignatureField.

In order to sign a PDF document, create an instance of an ApprovalSignature and fill out the properties. The most important and required property is the Handler property, which defines the type of algorithm used when signing the document.

When the signature is created, it must be assigned to the SignatureField that is to be signed. The document will not actually be signed until the document is saved. At that moment, the signature's handler will be called to calculate the actual signature data, which then is stored directly into the file to obtain the signed PDF document.

The following example illustrates the functionality of signing a PDF document with an approval signature.

using System;
using System.IO;
using ImageGear.Formats;
using ImageGear.Formats.PDF;
using ImageGear.Formats.PDF.Forms;
using ImageGear.Formats.PDF.Signatures;

static void Main(string[] args)
{
    // PDF initialization.
    ImGearFileFormats.Filters.Add(ImGearPDF.CreatePDFFormat());
    ImGearPDF.Initialize();

    using (Stream stream = new FileStream(@"C:\UnsignedFile.pdf", FileMode.Open, FileAccess.Read))
    {
        using (ImGearPDFDocument pdfDocument = ImGearFileFormats.LoadDocument(stream) as ImGearPDFDocument)
        {
            // Create form if it does not exist.
            if (pdfDocument.Form == null)
                pdfDocument.CreateForm();

            // Create new signature field for keeping the signature.
            SignatureField signatureField = pdfDocument.Form.CreateSignatureField(
                    "my_signature", pdfDocument.Pages[0] as ImGearPDFPage, new ImGearPDFFixedRect(0, 0, 0, 0));

            // Add new approval signature to the signature field.
            // The Handler property must be specified.
            signatureField.Signature = new ApprovalSignature(pdfDocument)
            {
                SignerName = "George Williams",
                SigningReason = "I have read and agree to this document",
                Handler = new PKCS7SignatureHandler(@"C:\my_certificates.pfx", "password")
            };

            // The signature is applied to the document when saving.
            pdfDocument.Save(@"C:\Signed.pdf", ImGearSavingFormats.PDF, 0, 0,
                    pdfDocument.Pages.Count, ImGearSavingModes.OVERWRITE);
        }
    }

    // Free PDF engine.
    ImGearPDF.Terminate();
}

Imports System.IO
Imports ImageGear.Formats
Imports ImageGear.Formats.PDF
Imports ImageGear.Formats.PDF.Forms
Imports ImageGear.Formats.PDF.Signatures

Public Shared Sub Main(args As String())

    ' PDF initialization.
    ImGearFileFormats.Filters.Add(ImGearPDF.CreatePDFFormat())
    ImGearPDF.Initialize()

    ' Load existing unsigned PDF document.
    Using stream As Stream = New FileStream("C:\UnsignedFile.pdf", FileMode.Open, FileAccess.Read)

        Using pdfDocument As ImGearPDFDocument = DirectCast(ImGearFileFormats.LoadDocument(stream), ImGearPDFDocument)

            ' Create form if it does not exist.
            If pdfDocument.Form Is Nothing Then
                pdfDocument.CreateForm()
            End If

            ' Create new signature field for keeping the signature.
            Dim signatureField As SignatureField = pdfDocument.Form.CreateSignatureField("cert_signature",
                DirectCast(pdfDocument.Pages(0), ImGearPDFPage), New ImGearPDFFixedRect(0, 0, 0, 0))

            ' Add New approval signature to the signature field.
            ' The Handler property must be specified.
            signatureField.Signature = New ApprovalSignature(pdfDocument) With {
                .SignerName = "George Williams",
                .SigningReason = "I have read and agree to this document",
                .Handler = New PKCS7SignatureHandler("C:\my_certificates.pfx", "password")
            }

            ' The signature is applied to the document when saving.
            pdfDocument.Save("C:\SignedFile.pdf", ImGearSavingFormats.PDF, 0, 0,
                                pdfDocument.Pages.Count, ImGearSavingModes.OVERWRITE)
        End Using
    End Using

    ' Free PDF engine.
    ImGearPDF.Terminate()
End Sub

Verifying a Document

Before verifying signatures, it is necessary to tell ImageGear.NET which certificates are trusted by the user via the ImGearPDF.TrustedCertificates property. Because certificate validity and document integrity are checked, if the certificate used to sign the PDF is not trusted, an error will occur upon verification.

Signatures in a document can be verified quickly by using the ImGearPDFDocument.VerifySignatures method. It will try to verify all signatures present in the document, and will return either SignatureVerificatonResult.OK or the result for the first signature that fails verification.

To verify each signature separately, it it possible to loop through all the signatures listed in ImGearPDFDocument.Signatures. This is illustrated in the example below.

using System;
using System.IO;
using ImageGear.Formats;
using ImageGear.Formats.PDF;
using ImageGear.Formats.PDF.Forms;
using ImageGear.Formats.PDF.Signatures;

static void Main(string[] args)
{
    // PDF initialization.
    ImGearFileFormats.Filters.Add(ImGearPDF.CreatePDFFormat());
    ImGearPDF.Initialize();

    // Trust any user-specified certificates (DER or PEM format) to verify a signer's identity when signing.
    // If the certificate used to sign the PDF is not trusted, an error will occur upon verification.
    ImGearPDF.TrustedCertificates.Import(@"C:\my_signing_certificate.der");

    using (Stream stream = new FileStream(@"C:\Signed.pdf", FileMode.Open, FileAccess.Read))
    {
        using (ImGearPDFDocument pdfDocument = ImGearFileFormats.LoadDocument(stream) as ImGearPDFDocument)
        {
            // Enumerate and check all signatures.
            foreach (Signature signature in pdfDocument.Signatures)
            {
                SignatureVerificationResult result = signature.Verify();
                if (result != SignatureVerificationResult.OK)
                    throw new Exception("Signature verification failed!");
            }
        }
    }

    // Free PDF engine.
    ImGearPDF.Terminate();
}

Imports System.IO
Imports ImageGear.Formats
Imports ImageGear.Formats.PDF
Imports ImageGear.Formats.PDF.Forms
Imports ImageGear.Formats.PDF.Signatures

Public Shared Sub Main(args As String())

    ' Add PDF file format filter to the list of used file formats.
    ImGearFileFormats.Filters.Add(ImGearPDF.CreatePDFFormat())

    ' PDF initialization.
    ImGearPDF.Initialize()

    '' Trust any user-specified certificates (DER Or PEM format) to verify a signer's identity when signing.
    '' If the certificate used to sign the PDF Is Not trusted, an error will occur upon verificaton.
    ImGearPDF.TrustedCertificates.Import("C:\my_signing_certificate.der")

    ' Load existing unsigned PDF document.
    Using stream As Stream = New FileStream("C:\Signed.pdf", FileMode.Open, FileAccess.Read)

        Using pdfDocument As ImGearPDFDocument = DirectCast(ImGearFileFormats.LoadDocument(stream), ImGearPDFDocument)

            ' Enumerate and check all signatures.
            For Each signature As Signature In pdfDocument.Signatures

                Dim result As SignatureVerificationResult = signature.Verify()
                If result <> SignatureVerificationResult.OK Then
                    Throw New Exception("Signature verification failed!")
                End If
            Next
        End Using
    End Using

    ' Free PDF engine.
    ImGearPDF.Terminate()
End Sub

Caveats

A signature only covers the part of the document that exists at the moment it is signed. Any additions or modifications that are added to the document by incremental saving at a later time are not covered by that signature.

In order to detect any additions to the document after the signature was added, you can use the signature's property CoversWholeDocument.