Wednesday, January 26, 2011

Digital Signatures and PDF Documents

Digital signatures can be used to authenticate the source of a PDF document (who signed it?) and to provide the integrity of a PDF document (did the document change after it was signed?). In this article I will show how to apply one or more digital signatures and how to verify digital signatures using PDFKit.NET 3.0.

Signing

Consider the following form:

screenshot_form_editmode 

This form has two sections of form fields; one for the student and one for the teacher. Normally, first the student will fill out his portion and sign the document. This can be achieved programmatically as follows:

// -------------------------------------------
// STUDENT FILLS OUT FIELDS AND SIGNS DOCUMENT
// -------------------------------------------

using (FileStream sourceFile = new FileStream(
   "form.pdf", FileMode.Open, FileAccess.Read))
{
   // open the form
   Document document = new Document(sourceFile);

   // fill out the data fields
   TextField projectNr = document.Fields["projectNumber"] as TextField;
   projectNr.Value = "FF-235";

   TextField sName = document.Fields["studentName"] as TextField;
   sName.Value = "Bob Stapleton";

   TextField sDate = document.Fields["studentDate"] as TextField;
   sDate.Value = "April 18, 2007";

   // retrieve the signature field
   SignatureField sigField = document.Fields["studentSignature"] 
      as SignatureField;

   // open certicate store.
   Pkcs12Store store = null;
   using (FileStream storeFile = new FileStream(
      "BobStapleton.pfx", FileMode.Open, FileAccess.Read))
   {
      store = new Pkcs12Store(storeFile, "studentpassword");
   }

   // let the factory decide which type should be used.
   SignatureHandler handler = StandardSignatureHandler.Create(store);

   // associate the handler with the signature field
   sigField.SignatureHandler = handler;

   // set optional info.
   sigField.ContactInfo = "+31 (0)77 4748677";
   sigField.Location = "The Netherlands";
   sigField.Reason = "I hereby declare!";

   // save the signed document - while saving, the handler 
   // will be called to sign the saved content
   using (FileStream outFile = new FileStream(
      "signedByStudent.pdf", FileMode.Create, FileAccess.ReadWrite))
   {
      document.Write(outFile);
   }
}

After executing the code above and opening the PDF document in the PDF reader, the document looks as follows:


signedByStudent

Note the question mark as shown by the PDF reader. This means that the certificate has not yet been trusted by the client machine. This is simply a matter of adding the certificate to the trust store.

Next, the teacher will review the student's data and then fill out the final fields and sign it. This can be achieved programmatically as follows:


// -----------------------------------------------------
// TEACHER FILLS OUT FINAL FIELDS AND SIGNS THE DOCUMENT
// -----------------------------------------------------

using (FileStream sourceFile = new FileStream(
   "signedByStudent.pdf", FileMode.Open, FileAccess.Read))
{
   // open the form         
   Document document = new Document(sourceFile);

   // fill out the data fields
   TextField tName = document.Fields["teacherName"] as TextField;
   tName.Value = "Max Boulton";

   TextField tDate = document.Fields["teacherDate"] as TextField;
   tDate.Value = "April 18, 2007";

   // retrieve the signature field
   SignatureField sigField = document.Fields["teacherSignature"] 
      as SignatureField;

   // open certicate store.
   Pkcs12Store store = null;
   using (FileStream storeFile = new FileStream(
      "MaxBoulton.pfx", FileMode.Open, FileAccess.Read))
   {
      store = new Pkcs12Store(storeFile, "teacherpassword");
   }

   // let the factory decide which type should be used.
   SignatureHandler handler = StandardSignatureHandler.Create(store);

   // associate the handler with the signature field
   sigField.SignatureHandler = handler;

   // set optional info.
   sigField.ContactInfo = "+31 (0)77 4748677";
   sigField.Location = "The Netherlands";
   sigField.Reason = "I hereby declare!";

   // save the signed document - while saving, the handler 
   // will be called to sign the saved content
   using (FileStream outFile = new FileStream(
      "signedByTeacher.pdf", FileMode.Create, FileAccess.ReadWrite))
   {
      document.Write(outFile, DocumentWriteMode.AppendUpdate);
   }
}

If you look at the code, it is practically the same as the previous code sample. The only significant difference is that I pass an extra argument to the Document.Write method: DocumentWriteMode.AppendUpdate. This tells PDFKit.NET to save all changes as a so-called Update. I will discuss this in the next section.


After executing the code above and opening the PDF document in the PDF reader, the document looks as follows:


signedByTeacher

Note that the icon of the first signature has changed to a warning sign. This indicates that "the document has been updated since signed". This is exactly the case.


Updates


Note that when we saved the second signature, we passed an extra argument to Document.Write, namely DocumentWriteMode.AppendUpdate. This instructs PDFKit.NET to save the new field data and the signature as an Update. This means that the original PDF data is left entirely intact and the changes are concatenated. The figure below illustrates this.


saveAsUpdate

Consequently, the first signature remains valid because the exact data that was signed hasn't changed; we have just added an update.


So after saving the update there are now in fact two versions of the document; one that signed by the student and one that was signed by the teacher. It is useful to retrieve the exact document to which a given signature was applied. Obviously the signer only vows for that version and not for the versions that were created afterwards.


Given a document you can enumerate all updates or versions of the document and save a copy to disk as follows:


// ----------------------------------------------------
// ENUMERATE UPDATES IN DOCUMENT THAS BEEN SIGNED TWICE
// ----------------------------------------------------

using (FileStream sourceFile = new FileStream(
   "signedByTeacher.pdf", FileMode.Open, FileAccess.Read))
{
   // open the form
   Document document = new Document(sourceFile);

   // count the number of updates
   Console.WriteLine( "This document has {0} updates.",
      document.Updates.Count );
         
   // save each update as a new PDF document
   foreach (Update update in document.Updates)
   {
      string name = string.Format(
         "signedByTeacher_{0}.pdf", update.Index );
      using (FileStream updateFile = new FileStream(
         name, FileMode.Create, FileAccess.Write))
      {
         update.Write(updateFile);
      }
   }
}

But perhaps even more interesting, you can open a signed document and per signature field you can retrieve the signed update. The following code sample enumerates all signature fields and saves the signed update.


// -----------------------------------------------------------
// ENUMERATE SIGNATURE FIELDS AND SAVE SIGNED UPDATE PER FIELD
// -----------------------------------------------------------

using (FileStream sourceFile = new FileStream(
   "signedByTeacher.pdf", FileMode.Open, FileAccess.Read))
{
   // open the form
   Document document = new Document(sourceFile);

   foreach (Field field in document.Fields)
   {
      // is this a signature field?
      SignatureField sigField = field as SignatureField;
      if (null != sigField)
      {
         // has it been signed?
         if (sigField.IsSigned)
         {
            // save the update and name it after the field
            string name = string.Format(
               "{0}.pdf", sigField.FullName);
            using (FileStream updateFile = new FileStream(
               name, FileMode.Create, FileAccess.Write))
            {
               sigField.SignedUpdate.Write(updateFile);
            }
         }
      }
   }
}

After executing this code, two new PDF documents have been saved: studentSignature.pdf and teacherSignature.pdf. Each document shows the version that was signed by the respective field.


Verifying

Until now we have discussed signing documents. The verification was left to the PDF reader application. But PDFKit.NET also allows you to verify signatures programmatically. This is extremely simple as shown in the next code sample. The sample opens the PDF document that was signed by the student and the teacher and enumerates the signature fields. Per signature, information about the signature state is written to the console.


// ----------------------------------
// DUMP STATE OF EACH SIGNATURE FIELD
// ----------------------------------

using (FileStream inFile = new FileStream(
   "signedByTeacher.pdf", FileMode.Open, FileAccess.Read))
{
   // open form
   Document document = new Document(inFile);

   foreach (Field field in document.Fields)
   {
      // is this a signature field?
      SignatureField sigField = field as SignatureField;
      if (null != sigField)
      {
         Console.WriteLine("Field '{0}'", sigField.FullName);

         // has it been signed?
         if (sigField.IsSigned)
         {
            // verify, based on the default handlers.
            bool verified = sigField.Verify();
            Console.WriteLine("  -- {0}", verified ? 
               "Verified" : "Not verified");

            if (verified)
            {
               // has the document been modified after signing?
               bool modified = sigField.DocumentModifiedAfterSigning;
               Console.WriteLine("  -- {0}", modified ? 
                  "Modified after signing" : 
                  "Not modified after signing");
            }
         }
         else
         {
            Console.WriteLine("  -- Not signed", sigField.FullName);
         }
      }
   }
}

After executing the above code, the following is written to the console:


verify

By the way, Adobe has changed the icons for the different signature states across its Acrobat versions. The screenshots in this article are from Acrobat 8.0.

2 comments:

  1. Good article. With the help of this article I have learn a lot about digital signatures and PDF documents. In this article you have nicely explained how to apply one or more digital signatures to a PDF document and how to verify them. Thanks for sharing this informative article.
    PDF signature

    ReplyDelete
  2. Great article - too bad the content of the example document is so ridiculously silly... borderline wierd.

    ReplyDelete