Digital Signatures for PDF documents

A White Paper by Bruno Lowagie (iText Software)

Introduction
The main rationale for PDF used to be viewing and printing documents in a reliable way. The technology was conceived with the goal to provide a collection of utilities, applications, and system software so that a corporation can effectively capture documents from any application, send electronic versions of these documents anywhere, and view and print these documents on any machines. (Warnock, 1991)

Why we need PDF

In the years that followed, an abundance of new tools from Adobe as well as from third party software vendors emerged, and the PDF specification was and still is very much alive. Plenty of functionality has been added to the PDF format over the years. Because of this, PDF has become the preferred document format of choice in many professional sectors and industries. In this paper well focus on one specific aspect of PDF files that makes the choice for PDF over any other document format a no-brainer: digital signatures.

Why we need digital signatures

Imagine a document that has legal value. Such a document may contain important information about rights and obligations, in which case you need to ensure its authenticity. You dont want people to deny the commitments theyve written down. Furthermore, this document probably has to be mailed to, viewed and stored by different parties. On different places in the workflow, at different moments in time, the document can be altered, be it involuntary, for instance due to a transmission error, or deliberately, if somebody wants to create a forgery from the original document. For centuries, weve tried to solve this problem by putting a so -called wet ink signature on paper. Nowadays, we can use digital signatures to ensure: The integrity of the document we want assurance that the document hasnt been changed somewhere in the workflow. The authenticity of the document we want assurance that the author of the document is who we think it is (and not somebody else) Non-repudiation we want assurance that the author cant deny his or her authorship.

In this paper, well focus on documents in the portable document format (PDF).

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

This mission was set forth in the Camelot paper, and it was accomplished with the first publication of the Portable Document Format Reference (Adobe, 1993) and the availability of the first PDF software products created by Adobe. PDF became renowned as the format that could be trusted to ensure a consistent output, be it on screen or in print.

Digital Signatures for PDF documents 2012

Table of Contents
Introduction ........................................................................................................................................... 1 Why we need PDF .............................................................................................................................. 1 Why we need digital signatures ......................................................................................................... 1 Table of Contents ................................................................................................................................... 2 1. Understanding the concept of digital signatures ................................................................................ 5 1.1 A simple PDF example .................................................................................................................. 5 1.1.1 How to forge the content of a PDF document ....................................................................... 6 1.1.2 A digitally signed PDF document ........................................................................................... 7 1.1.3 Inspecting the syntax of the digital signature ........................................................................ 8

1.2.1 How to check a password .................................................................................................... 10 1.2.2 What is a digest algorithm? ................................................................................................. 11 1.2.3 Java SDKs default MessageDigest implementation ............................................................ 13 1.2.4 The BouncyCastle library ..................................................................................................... 13 1.3 Encrypting a message using a public-key encryption ................................................................. 14 1.3.1 Creating a key store ............................................................................................................. 15 1.3.2 Encrypting and decrypting messages .................................................................................. 15 1.3.3 Inspecting our self-signed certificate ................................................................................... 17 1.3.4 Using a public-key algorithm for authentication and non-repudiation................................ 18 1.4 Overview of cryptography Acronyms and Standards ................................................................. 19 1.4.1 Acronyms ............................................................................................................................. 19 1.4.2 Public-Key Cryptography Standards (PKCS) ......................................................................... 20 1.4.3 The PDF ISO Standard .......................................................................................................... 21 1.4.4 CAdES, XAdES and PAdES..................................................................................................... 21 1.5 Summary .................................................................................................................................... 22 2. PDF and digital signatures ................................................................................................................ 23 2.1 Digital signatures in PDF ............................................................................................................. 23 2.1.1 The signature handler and the sub filters ............................................................................ 23 2.1.2 The byte range covered by the digital signature ................................................................. 24 2.1.3 How to compose a signature ............................................................................................... 25 2.1.4 Algorithms supported in PDF ............................................................................................... 26 2.2 The Hello World of digital signing using iText ......................................................................... 27

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

2

1.2 Creating a message digest .......................................................................................................... 10

1.1.4 Making the signature invalid ................................................................................................. 9

Digital Signatures for PDF documents 2012

2.2.1 A simple example adding a visible signature to a document ............................................... 27 2.2.2 Manage trusted identities ................................................................................................... 30 2.2.3 Adding a certificate to the Contacts list in Adobe Reader ................................................... 33 2.2.4 Signing large PDF files .......................................................................................................... 34 2.3 Creating and signing signature fields .......................................................................................... 35 2.3.1 Adding a signature field using Adobe Acrobat ..................................................................... 35 2.3.2 Creating a signature field programmatically using iText ...................................................... 36 2.3.3 Adding an empty signature field to an existing document using iText ................................ 38 2.4 Creating different signature appearances .................................................................................. 39 2.4.1 Defining a custom PdfSignatureAppearance ....................................................................... 39

2.4.4 Ordinary and Certifying signatures ...................................................................................... 46 2.4.5 Adding content after a document was signed ..................................................................... 48 2.5 Signatures in PDF and workflow ................................................................................................. 51 2.5.1 Sequential signatures in PDF ............................................................................................... 51 2.5.2 Creating a form with placeholders for multiple signatures ................................................. 52 2.5.3 Signing a document multiple times ..................................................................................... 53 2.5.4 Signing and filling out fields multiple times ......................................................................... 56 2.5.5 Locking fields and documents after signing ......................................................................... 60 2.6 Summary .................................................................................................................................... 63 3 Certificate Authorities, certificate revocation and time stamping..................................................... 64 3.1 Certificate authorities ................................................................................................................. 64 3.1.1 Signing a document with a p12 file from a Certificate Authority ......................................... 65 3.1.2 Trusting the root certificate of the Certificate Authority ..................................................... 66 3.1.3 Best practices in signing ...................................................................................................... 68 3.2 Adding Certificate Revocation information ................................................................................ 68 3.2.1 Finding the URL of a Certificate Revocation List .................................................................. 68 3.2.2 Getting the CRL online ......................................................................................................... 69 3.2.3 Creating a CrlClient using an offline copy of the CRL ........................................................... 74 3.2.4 Using the Online Certificate Status Protocol (OCSP) ............................................................ 75 3.2.5 Which is better: embedding CRLs or an OCSP response? .................................................... 77 3.3 Adding a timestamp ................................................................................................................... 78 3.3.1 Dealing with expiration and revocation dates ..................................................................... 78

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

3

2.4.3 Adding metadata to the signature dictionary ...................................................................... 44

2.4.2 Creating signature appearances using convenience methods ............................................. 41

Digital Signatures for PDF documents 2012

3.3.2 Connecting to a timestamp server ...................................................................................... 79 3.4 How to get a green check mark .................................................................................................. 81 3.4.1 Trust certificates stored elsewhere ..................................................................................... 82 3.4.2 Adobe Approved Trust List (AATL) ....................................................................................... 83 3.4.3 Signing a document using a USB token (part 1: MSCAPI) .................................................... 84 3.5 Estimating the size of the signature content .............................................................................. 89 3.6 Summary .................................................................................................................................... 90 4 Creating signatures externally ........................................................................................................... 91 4.1 Signing a document using PKCS#11 ............................................................................................ 91 4.1.1 Signing a document using an HSM ...................................................................................... 91

4.3 Client/server architectures for signing ....................................................................................... 94 5. Validation of signed documents ....................................................................................................... 94 5.1 Validating signed PDFs................................................................................................................ 94 5.2 PAdES 4: Long-Term Validation .................................................................................................. 94 Appendix .............................................................................................................................................. 94 A. How to protect the integrity of a paper document? .................................................................... 94 B. Electronic signatures and digital signatures: are they the same thing?........................................ 94 C. Digital signatures on Android example ......................................................................................... 94

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

4

4.2 Signing a document with a Smart Card using javax.smartcardio ................................................ 94

4.1.2 Signing a document using a USB token (part 2: PKCS#11) ................................................... 92

Digital Signatures for PDF documents 2012

1. Understanding the concept of digital signatures
First lets take a look at a PDF file, and identify the problem regarding document integrity.

1.1 A simple PDF example

Figure 1 shows a simple PDF document, containing nothing but the words Hello World.

Figure 1: A simple Hello World file

If we look inside the PDF file shown in figure 1, we see the following PDF syntax: Code sample 1: A PDF file inside-out

%PDF-1.4 % 2 0 obj <</Length 73 >>stream BT 36 806 Td 0 -18 Td /F1 12 Tf (Hello World)Tj 0 0 Td ET Q endstream endobj 4 0 obj <</Parent 3 0 R/Contents 2 0 R/Type/Page/Resources<</ProcSet [/PDF /Text /ImageB /ImageC /ImageI]/Font<</F1 1 0 R>>>>/MediaBox[0 0 595 842]>> endobj 1 0 obj <</BaseFont/Helvetica/Type/Font/Encoding/WinAnsiEncoding/Subtype/Type1>> endobj 3 0 obj <</ITXT(5.3.0)/Type/Pages/Count 1/Kids[4 0 R]>> endobj 5 0 obj <</Type/Catalog/Pages 3 0 R>> endobj 6 0 obj <</Producer(iText 5.3.0 2000-2012 1T3XT BVBA)/ModDate(D:20120613102725+02'00')/CreationDate(D:20120613102725+02'00')>> endobj

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

5

Digital Signatures for PDF documents 2012

xref 0 7 0000000000 65535 f 0000000311 00000 n 0000000015 00000 n 0000000399 00000 n 0000000154 00000 n 0000000462 00000 n 0000000507 00000 n trailer <</Root 5 0 R/ID [<0f6bb651c0480213fbbd13449b40fe8f><e77fb3c3c64c30ea2a908cd181c5f500>]/Info 6 0 R/Size 7>> startxref 643 %%EOF

1.1.1 How to forge the content of a PDF document Suppose we know how to apply some small changes to the file. For instance: lets change the content, the dimensions, and the metadata of the document. See the parts marked in red in Code sample 2. Code sample 2: A manually altered PDF file

%PDF-1.4 % 2 0 obj <</Length 73 >>stream BT 36 806 Td 0 -18 Td /F1 12 Tf (Hello Bruno)Tj 0 0 Td ET Q endstream endobj 4 0 obj <</Parent 3 0 R/Contents 2 0 R/Type/Page/Resources<</ProcSet [/PDF /Text /ImageB /ImageC /ImageI]/Font<</F1 1 0 R>>>>/MediaBox[0 0 120 806]>> endobj 1 0 obj <</BaseFont/Helvetica/Type/Font/Encoding/WinAnsiEncoding/Subtype/Type1>> endobj 3 0 obj <</ITXT(5.3.0)/Type/Pages/Count 1/Kids[4 0 R]>> endobj 5 0 obj <</Type/Catalog/Pages 3 0 R>> endobj 6 0 obj

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

6

Every PDF file starts with %PDF- followed by a version number, and it ends with %%EOF. Inbetween, you can find different PDF objects that somehow define the document. Explaining the meaning of these objects is outside the scope of this paper.

Digital Signatures for PDF documents 2012

<</Producer(iText 1.0.0 2000-2012 1T3XT BVBA)/ModDate(D:20120613102725+02'00')/CreationDate(D:20120613102725+02'00')>> endobj xref 0 7 0000000000 65535 f 0000000311 00000 n 0000000015 00000 n 0000000399 00000 n 0000000154 00000 n 0000000462 00000 n 0000000507 00000 n trailer <</Root 5 0 R/ID [<0f6bb651c0480213fbbd13449b40fe8f><e77fb3c3c64c30ea2a908cd181c5f500>]/Info 6 0 R/Size 7>> startxref 643 %%EOF

I manually replaced the word World with Bruno, I changed the dimensions of the page from 595 x 842 to 120 x 806, and I changed the version number of iText in the producer line. Figure 2 shows the result.

Figure 2: an altered Hello World file Dont ever do this yourself! Changing a PDF manually will corrupt your file in 99.9% of the cases. I m only doing this to prove that, although PDF isnt a word processing format, although PDF isnt meant for editing a document, and although its not recommended to do so, you can change the content of a document. This is exactly what we try to avoid by introducing a digital signature. 1.1.2 A digitally signed PDF document Figure 3 shows a Hello World document that has been digitally signed. The blue banner tells us the document is Signed and all signatures are valid. The Signature panel informs us that the file was Signed by Bruno Specimen, and it gives you more signature details.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

7

Digital Signatures for PDF documents 2012

The green check mark means that the Document hasnt been modified since the signature was applied and that the Signers identity is valid. 1.1.3 Inspecting the syntax of the digital signature Now lets take a look inside this PDF file. Code sample 3: snippets of a signed PDF file

%PDF-1.4 % 3 0 obj <</F 132/Type/Annot/Subtype/Widget/Rect[0 0 0 0]/FT/Sig /DR<<>>/T(signature)/V 1 0 R/P 4 0 R/AP<</N 2 0 R>>>> endobj 1 0 obj <</Contents <0481801e6d931d561563fb254e27c846e08325570847ed63d6f9e35 ... b2c8788a5> /Type/Sig/SubFilter/adbe.x509.rsa_sha1/Location(Ghent) /Name(Bruno Specimen)/M(D:20120613133437+02'00')/ByteRange [0 159 423 2408 ] /Cert(0...)/Filter/Adobe.PPKLite/Reason(Demo purposes.)/R 65541>> endobj ... 9 0 obj <</Length 73>>stream BT 36 806 Td 0 -18 Td /F1 12 Tf (Hello World)Tj 0 0 Td ET Q endstream endobj ... 11 0 obj <</Type/Catalog/AcroForm<</Fields[3 0 R]/DR<</Font<</Helv 5 0 R /ZaDb 6 0 R>>>>/DA(/Helv 0 Tf 0 g )/SigFlags 3>>/Pages 10 0 R>>

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

8

Figure 3: a signed Hello World file

Digital Signatures for PDF documents 2012

endobj xref 0 12 0000000000 65535 f ... 0000002299 00000 n trailer <</Root 11 0 R/ID [<5c799e8403676a13617fbb7b14596f66><10882e96fe166c320418063b58b15248>]/Info 7 0 R/Size 12>> startxref 2442 %%EOF

Note that Ive slightly altered the file, removing bytes that arent relevant when explai ning the concept of a digital signature. First lets inspect the root object of the PDF (aka the Catalog object). Its marked in green in code sample 3 (the object with number 11). The Catalog is always represented as a PDF dictionary. Dictionaries can easily be recognized in a PDF file. They start with << and end with >>. In-between youll find a series of key-value pairs. The key is always a name object. Note that names always start with a /. For example: if the PDF contains a form, youll find an /AcroForm key in the catalog dictionary. Its value will be (a reference to) a dictionary. In turn, this dictionary will contain a /SigFlags value if the form contains a digital signature. Theres one field in the form. Its referred to from the /Fields array: see object 3 (marked in red). The field named signature (/T(signature)) is a field of type signature (/FT/Sig). We didnt see any visual representation of the signature in figure 3. Thats because Bruno Specimen decided to use an invisible signature. The rectangle (/Rect) defining the widget annotation (/Type/Annot /SubType/Widget) has a zero width and zero height ([0 0 0 0]). The actual signature can be found in the signature dictionary (marked in blue). This dictionary is referred to from the value (/V) of the signature field. The signature is the value of the /Contents entry. This signature covers all the bytes of the PDF file, except for the signature bytes itself. See the /ByteRange entry: the signature covers bytes 0 to 159 and bytes 423 to 2408. The signature itself takes bytes 160 to 422. 1.1.4 Making the signature invalid Now when I change one of the bytes inside the byte range covered by the signature, Adobe Reader will show a red cross instead of a green check mark. Figure 4 shows what happens if I manually replace World by Bruno.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

9

Digital Signatures for PDF documents 2012

In this case, the Signers identity is valid, but the Document has been altered or corrupted since it was signed. How does Adobe Reader know that the document has been altered? To understand this, we need to understand the concept of hashing and we need to know how encryption works.

1.2 Creating a message digest

I have a confession to make: I cant remember all the passwords Im using to log in into different sites such as Twitter, Facebook, LinkedIn, and so on. I am one of the frequent users of the Lost your password? functionality. Usually, I get a link that allows me to reset my password, but once in a while I get a mail containing my original password in clear text. You cant image how much this worries me! The fact that a service can provide me with my password, means that my actual password can be found somewhere in a database, on a server. Thats a dangerous situation: it means that whoever hacks the system can obtain the passwo rds of all the users. 1.2.1 How to check a password A simple way to check a password is to store a digest of the password instead of the actual password. Lets create a simple class that demonstrates how its done: Code sample 4: an example showing how to use the MessageDigest class
public class DigestDefault { protected byte[] digest; protected MessageDigest md; protected DigestDefault(String password, String algorithm, String provider) throws GeneralSecurityException {

if (provider == null) md = MessageDigest.getInstance(algorithm); else md = MessageDigest.getInstance(algorithm, provider);

digest = md.digest(password.getBytes()); }

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

10

Figure 4: Invalidated signature

Digital Signatures for PDF documents 2012

public static DigestDefault getInstance(String password, String algorithm) throws GeneralSecurityException { return new DigestDefault(password, algorithm, null); }
public int getDigestSize() { return digest.length; }

public String getDigestAsHexString() { return new BigInteger(1, digest).toString(16); }

public boolean checkPassword(String password) { return Arrays.equals(digest, md.digest(password.getBytes())); } public static void showTest(String algorithm) { try {

DigestDefault app = getInstance("password", algorithm); System.out.println("Digest using " + algorithm + ": " + app.getDigestSize());

System.out.println("Digest: " + app.getDigestAsHexString());

System.out.println("Is the password 'password'? " + app.checkPassword("password")); System.out.println("Is the password 'secret'? " + app.checkPassword("secret")); } catch (NoSuchAlgorithmException e) { System.out.println(e.getMessage()); } } }

Take a look at the showTest() method in code sample 4. We create a DigestDefault object named app, passing a password password and an algorithm as parameters. An instance of the java.security.MessageDigest object is created and stored as a member variable. The password isnt stored in the DigestDefault class. Instead we store the result of the digest() method. Out of curiosity, we send some info about this result to the System.out: its length and its value as a hexadecimal String. When we test the password with the checkPassword() method, we use the same digest() method, and we compare the result with the digest that was stored. If the result is identical, the password was correct; otherwise it was wrong. How does this work? What is a digest algorithm? 1.2.2 What is a digest algorithm? When we create a digest, were using a cryptographic hash function to turn an arbitrary block of data into a fixed-size bit string. The block of data is often called the message, and the hash value is referred to as the message digest. In the previous example, the message was a password. In the context of PDF documents, the block of data could be the byte range of a PDF file.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

11

Digital Signatures for PDF documents 2012

The result of this hash function is always identical. Any accidental or intentional change to the data will result in a different hash value. Its also a one-way algorithm. When you create a hash of a password, it shouldnt be possible to calculate the password based on the message digest . If a database is compromised, the hacker has a collection of message digests, but he cant convert this to a list of passwords. NOTE: If a hacker obtains a database containing hashes of passwords, he can still use brute force to recover passwords. Also some older hashing algorithms have flaws that can be exploited. Nowadays, at least salting the hash and applying multiple iterations is necessary for security, but thats outside the scope of this paper. When making a hash, you can choose among different algorithms. Code sample 5 shows some of them. Code sample 5: testing different Hashing algorithms

MD5, SHA, and RIPEMD are implementations of different cryptographic hash algorithms. MD5 one in a series of message digest algorithms designed by Professor Ron Rivest of MIT. It was designed in 1991. Its still widely used, but its no longer considered secure, because it allows different messages resulting in the same 128-bit (16-byte) digest. This is known as a hash collision. SHA stands for Secure Hash Algorithm. o SHA-1 was designed by the US National Security Agency (NSA). The 160-bit (20 bytes) hash was considered safer than MD5, but in 2005 a number of security flaws were identified. o SHA-2 fixes these flaws. SHA-2 is a set of hash functions: SHA-224, SHA-256, SHA384, and SHA-512. The length of the message digest in SHA-2 can be 224 bits (28 bytes), 256 bits (32 bytes), 384 bits (48 bytes), or 512 bits (64 bytes). RIPEMD stands for RACE Integrity Primitives Evaluation Message Digest. It was developed at the Katholieke Universiteit Leuven1. In our example, we use a 128, 160 and 256 bit version (16, 20 and 32 bytes).

In section 2.1.1, well see that not all of these digest algorithms can be used in the context of PDF, but lets not get ahead of ourselves.

1 2

http://www.esat.kuleuven.be/ http://www.bouncycastle.org/ 3 http://en.wikipedia.org/wiki/Bob_and_Alice

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

12

public static void testAll() { showTest("MD5"); showTest("SHA-1"); showTest("SHA-224"); showTest("SHA-256"); showTest("SHA-384"); showTest("SHA-512"); showTest("RIPEMD128"); showTest("RIPEMD160"); showTest("RIPEMD256"); }

Digital Signatures for PDF documents 2012

1.2.3 Java SDKs default MessageDigest implementation If we look at the output of code sample 5, we discover that not all algorithms are supported by Oracles implementation of the abstract java.security.MessageDigest class. The output for MD5 and SHA-1 looks like this:
Digest using MD5: 16 Digest: 5f4dcc3b5aa765d61d8327deb882cf99 Is the password 'password'? true Is the password 'secret'? false Digest using SHA-1: 20 Digest: 5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8 Is the password 'password'? true Is the password 'secret'? false

But the output for SHA-224 and the RIPEMD algorithms looks like this:

We can fix this by using another security provider.

1.2.4 The BouncyCastle library Bouncy Castle is a collection of APIs used in cryptography2. Its available in both Java and C#. We could extend the class in code sample 4 by defining a BouncyCastleProvider instance (named BC) as security provider. This is done in code sample 6. Code sample 6: using a different crypto provider

public class DigestBC extends DigestDefault { public static final BouncyCastleProvider PROVIDER = new BouncyCastleProvider(); static { Security.addProvider(PROVIDER); } protected DigestBC(String password, String algorithm) throws GeneralSecurityException { super(password, algorithm, PROVIDER.getName()); }

public static DigestBC getInstance( String password, String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException {

return new DigestBC(password, algorithm);

} }

Note that we create a BouncyCastleProvider instance, and we add it to the Security class (in the java.security package). This class centralizes all security properties. One of its primary uses is to manage security providers. Now the output for SHA-224 and RIPEMD128 looks like this:

http://www.bouncycastle.org/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

13

SHA-224 MessageDigest not available RIPEMD128 MessageDigest not available

Digital Signatures for PDF documents 2012

Digest using SHA-224: 28 Digest: d63dc919e201d7bc4c825630d2cf25fdc93d4b2f0d46706d29038d01 Is the password 'password'? true Is the password 'secret'? false Digest using RIPEMD128: 16 Digest: c9c6d316d6dc4d952a789fd4b8858ed7 Is the password 'password'? true Is the password 'secret'? false

Weve already mentioned that the message could be any block of bytes, including the bytes of a specific byte range of a PDF file. To detect whether or not a PDF file has been altered, we could create a message digest of those bytes and store it inside the PDF. Then when somebody changes the PDF, the message digest taken from the changed bytes in the byte range will no longer correspond with the message digest in the PDF. Does this solve our problems of data integrity, authenticity and non-repudiation? Not yet. One could easily change the bytes of the PDF file, guess the digest algorithm that was used, and store a new message digest inside the PDF. To avoid this, we need to introduce the concept of asymmetric key algorithms.

1.3 Encrypting a message using a public-key encryption

Suppose that Bob want to send Alice a private message3, but Bob doesnt trust the channel used to transmit the message. If it falls in the wrong hands, Bob wants to avoid that the message meant for Alices eyes only, can be read by anyone else. Bob could use an algorithm to encrypt his message, and then Alice would need to use an algorithm to decrypt it. If the same key can be used for encryption as well as decryption (or if the key for decryption can be derived from the key used for encryption), Bob and Alice are using a symmetric key algorithm. The problem with such an algorithm is that Bob and Alice need to exchange that algorithm in a safe way first. Anybody with access to the key can decrypt your message. To avoid this, Bob and Alice can choose an asymmetric key algorithm. In this case two different keys are used: one key to encrypt, the other one to decrypt the message. One key cannot be derived from the other. Now if Bob wants to send Alice a private message, Alice can send her public key to Bob. Anybody can use this key to encrypt messages meant for Alice. When Bob sends Alice such an encrypted message, Alice will use her private key to decrypt it. Suppose that Chuck intercepts the message, he wont be able to read it as long as he doesnt have access to Alices private key. The most commonly used public-key encryption system is RSA, named after Ron Rivest, Adi Shamir, and Leonard Adleman, its inventors. When you create a key pair, you can specify a key length in bits. The higher the number of bits, the stronger the encryption will be. Theres also a downside: with every doubling of the RSA key length, decryption is 6 to 7 times slower. Lets create such a public and private key pair.

http://en.wikipedia.org/wiki/Bob_and_Alice

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

14

Digital Signatures for PDF documents 2012

1.3.1 Creating a key store The Java SDK contains a tool named keytool. You can use this tool to create a key store. This key store will contain your private key, and a digital certificate containing information about you as well as your public key. See code sample 7 to find out how keytool is used. Code sample 7: creating a key store using keytool
$ keytool -genkey -alias demo -keyalg RSA keysize 2048 -keystore ks Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: Bruno Specimen What is the name of your organizational unit? [Unknown]: IT What is the name of your organization? [Unknown]: iText Software What is the name of your City or Locality? [Unknown]: Ghent What is the name of your State or Province? [Unknown]: OVL What is the two-letter country code for this unit? [Unknown]: BE Is CN=Bruno Specimen, OU=IT, O=iText Software, L=Ghent, ST=OVL, C=BE correct? [no]: yes Enter key password for <demo> (RETURN if same as keystore password):

A key store can contain more than one private key, and we could define a password that is different from the key store password for every key, but for the sake of simplicity, we used only one password password. Now we can use this file from our Java program to encrypt and decrypt messages. 1.3.2 Encrypting and decrypting messages Code sample 8 shows a simple class containing an encrypt() and a decrypt() method: Code sample 8: A simple class to encrypt and decrypt messages
public class EncryptDecrypt { protected KeyStore ks;

public EncryptDecrypt(String keystore, String ks_pass) throws GeneralSecurityException, IOException {

initKeyStore(keystore, ks_pass); }
public void initKeyStore(String keystore, String ks_pass) throws GeneralSecurityException, IOException { ks = KeyStore.getInstance(KeyStore.getDefaultType()); ks.load(new FileInputStream(keystore), ks_pass.toCharArray()); } public X509Certificate getCertificate(String alias) throws KeyStoreException { return (X509Certificate) ks.getCertificate(alias); } public Key getPublicKey(String alias) throws GeneralSecurityException, IOException {

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

15

Digital Signatures for PDF documents 2012

return getCertificate(alias).getPublicKey(); } public Key getPrivateKey(String alias, String pk_pass) throws GeneralSecurityException, IOException { return ks.getKey(alias, pk_pass.toCharArray()); } public byte[] encrypt(Key key, String message) throws GeneralSecurityException { Cipher cipher = Cipher.getInstance("RSA"); cipher.init(Cipher.ENCRYPT_MODE, key); byte[] cipherData = cipher.doFinal(message.getBytes()); return cipherData; } public String decrypt(Key key, byte[] message) throws GeneralSecurityException { Cipher cipher = Cipher.getInstance("RSA"); cipher.init(Cipher.DECRYPT_MODE, key); byte[] cipherData = cipher.doFinal(message); return new String(cipherData); }

public static void main(String[] args) throws GeneralSecurityException, IOException { EncryptDecrypt app = new EncryptDecrypt("src/main/resources/ks", "password"); Key publicKey = app.getPublicKey("demo"); Key privateKey = app.getPrivateKey("demo", "password"); System.out.println("Let's encrypt 'secret message' with a public key"); byte[] encrypted = app.encrypt(publicKey, "secret message"); System.out.println("Encrypted message: " + new BigInteger(1, encrypted).toString(16)); System.out.println("Let's decrypt it with the corresponding private key"); String decrypted = app.decrypt(privateKey, encrypted); System.out.println(decrypted); System.out.println("You can also encrypt the message with a private key"); encrypted = app.encrypt(privateKey, "secret message"); System.out.println("Encrypted message: " + new BigInteger(1, encrypted).toString(16)); System.out.println("Now you need the public key to decrypt it"); decrypted = app.decrypt(publicKey, encrypted); System.out.println(decrypted); }

Feel free to experiment with this example, but dont panic if you get an InvalidKeyException saying that the key size is invalid. Due to import control restrictions by the governments of a few countries, the encryption libraries shipped by default with the Java SDK restrict the length, and as a result the strength, of encryption keys.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

16

Digital Signatures for PDF documents 2012

If you want to avoid this problem, you need to replace the default security JARs in your Java installation with the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. These JARs are available for download from http://java.oracle.com/ in eligible countries. 1.3.3 Inspecting our self-signed certificate As you can see, we create a KeyStore object in the constructor. From this key store, we can obtain the public certificate that contains the public key to be used to decrypt a message that was encrypted with the corresponding private key. A public certificate also contains information about the owner of the key, its validity period, and so on. The information in this certificate is signed by an issuer. In this case, weve created the certificate ourselves, so were owner and issuer at the same time, and we refer to the certificate a s being self-signed. Well learn more about other certificates in chapter 3. Code sample 9 shows the result of the toString() method of the Certificate object:
[ [

Version: V3 Subject: CN=Bruno Specimen, OU=IT, O=iText Software, L=Ghent, ST=OVL, C=BE Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5 Key: Sun RSA public key, 2048 bits modulus: 27706646249437583578501322921252037659324960984454438650274096621513733947318221232 90092536075175589409888251417041849614639606544370595805501222639942552792696182924 19557917502293557528812483868420880765808333319067679184013346901221838396913865166 99015383461952441725262486245434952426855074038516834028858534816117097190264270919 71970499616689684012198665415564791592761123642686002605100319784405598279465396131 52730660815729426764990600604032553721917074418187300648866487699179740248069790221 86704383972995455717886346330217224211116969013795163606127880980836981725138593346 185822803712134120722258642329810193 public exponent: 65537 Validity: [From: Sat Aug 04 15:40:30 CEST 2012, To: Tue Nov 17 14:40:30 CET 2015] Issuer: CN=Bruno Specimen, OU=IT, O=iText Software, L=Ghent, ST=OVL, C=BE SerialNumber: [ 501d264e] ] Algorithm: [SHA1withRSA] Signature: 0000: 12 ED EA 66 FE 6C 2C 0010: CF 9E 66 D3 DC 62 85 0020: E8 F6 61 42 02 F9 36 0030: 78 2F CA F0 53 76 41 0040: 8E 44 55 31 14 D3 AB 0050: DE 2C 1E F5 F9 E3 19 0060: EC AF CB 86 22 B8 F0 0070: 98 8E 37 34 7E AD 76 0080: 5D 21 0A A6 CD 57 70 0090: A1 BF 61 02 12 D1 3D 00A0: E1 0B 3C 1F 22 CF 11 00B0: 40 C2 59 C1 19 8B 86 00C0: D3 CF FD 8C 3B F4 6D

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

FC F1 A9 F4 3F EF D0 78 C1 5F 18 61 1D 0F D5 8B 47 59 7D 94 99 A4 D8 AA 79 F2 F4 62 12 B7 6C 92 EC 63 23 2E 2D 12 25 59 76 6F 5A 53 67 37 21 5E C5 CF 4F C3 19 07 8B 2B E7 66 97 0D 85 5C 75 F2 7F 44 F6 4B F7 04 56 D1 06 1E 16 C1 3E 69 40 F2 B6 A1 C4 73 23 C3 B9 A2 F6 EC B1 FE 67 14 A9 2E 22 DA 1D 80 6D C2 61 B7 BF 04 9B 73 36 18 43 47 DC 8D E8 1B D2

Code sample 9: an example of a public certificate

17

w
...f.l,...Y.D@.. ..f..b...bv...g. ..aB..6...o.K... x/..SvA.G.Z+...s .DU1...?YlS....6 .,........gfVs". ....".....7..#.C ..74..vx.c!....G ]!...Wp..#^..... ..a...=_...\..m. ..<."....-.u.... @.Y....ay.O.>.a. ....;.m..%..i...

Digital Signatures for PDF documents 2012

00D0: 49 96 61 B2 50 2B 70 74 00E0: 96 67 A4 0B 70 62 63 A8 00F0: 0E 72 55 0B A2 EC 3F CE ] AA 8E DC 18 6A 22 FC 00 49 D6 E1 36 92 60 FF 0C 2E B4 BE E8 42 2C F0 73 I.a.P+pt....j".. .g..pbc.I..6.`.. .rU...?.....B,.s

In code sample 8, we obtain the public key from the Certificate object and we get the private key from the KeyStore object. The public and the private key objects can be used as parameters for the encrypt() and decrypt() method. These methods are almost identical. The only difference is the Cipher mode: were using either ENCRYPT_MODE or DECRYPT_MODE. 1.3.4 Using a public-key algorithm for authentication and non-repudiation When we run this class, we get the following output:
Let's encrypt 'secret message' with a public key Encrypted message: 66e7a06a40e5092aa0e70b4d57f2dd139e1902ddc012aa6d75deb6ecc9727fb9219d9aae98c054ebd53 8bfb002d31314c9fa6990d25cb528cf7516bbe3c8923c6670ba1b3673eb40a908a12146369f98fba36c 6beee04479411af7a6226e122a04d119dd9648a5d1be5cb3c52584f42fdffc6719f4d4b1e593a85c377 97d025b60f88d1ad19ad985911768bbb511c732761adace642dc8634925a8e197265ccadf07dd3a6185 50ffaf8dff13b44c91a3f9063d51f33ebd6d896321a795c34c6905f0e227253f3f86da4ca1d5f0da818 010621e1a88d4dc6cc4567d0fbc5461dbd696799f89da26b8eebcb4b4ac72115f021c2519e7036a5902 74f52ddde8d57d Let's decrypt it with the corresponding private key secret message You can also encrypt the message with a private key Encrypted message: 14d5a453baeb584a5c979ebcc142535684ce9503d1db01aa0bed0a3991dd5c6818ddf6f89bca94e24d8 dd02038564c42168c764d4d1f18fcf5e98f8da92b721add388e1971b63db841c8ddec1ae27b2f100f43 6e1f0a5294a9d2fb641b03a9aed412a4257c46f8b71700255b98a8d406a6daeb65bf64b28f85c786a67 2c56c95fa7dd539c8bfffa960a4d75ec16166088362dc1dbf0cb11ca6e7eb9d2730d885cc28abcd7d9b 56b179350d1975de16ec6c2c9ac2978cf2baa5da4b7d5b650ad5195a7fc5437072c05af55ab106f1231 c75c1a498ed83c113e4d008ee5710f32120641ea9ce7895e9f8c304ef6e8d169a9b0e0b155c91ae5f90 7978cd88e6e0f8 Now you need the public key to decrypt it secret message

Do you see what happens here? First you take a public key and use it to encrypt a message so that only somebody with the corresponding key can decrypt it. Thats what encryption is about. But in the next few lines, you do the inverse: you encrypted a message using your private key. Now when you share your public key which is usually the intention the whole world can decrypt your message. In this case, youre not using the encryption mechanism to make sure a third party cant read your message, but to make it absolutely clear that youre the author. If I can decrypt a message using your public key, Im 100% sure that it was encrypted using your private key. As only you have access to your private key, Im 100% sure that youre the author. Thats why the concept of encryption using an asymmetric key algorithm can be used for digital signing. Figure 5 shows the two different concepts. For encryption the public key (the green key) is used to encrypt, the private key (the red key) to decrypt. For digital signatures, its the other way round.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

18

Digital Signatures for PDF documents 2012

Figure 5: asymmetric key algorithms Does this solve our problems of data integrity, authenticity and non-repudiation? Yes, it does, because as soon as anybody tampers an encrypted message sent from me to you, you wont be able to decrypt it using my public key. On the other hand: if you succeed in decrypting it, youre certain that I was the author. I cant claim that I didnt sign the message while also claiming that my private key isnt compromised. However, thats not how its done in practice: encrypting and decrypting large messages requires plenty resources. If my goal is not to protect the message from being read by anybody but you, we both could save valuable time and CPU on our machines, if I encrypt only a digest of the message, and attach this signed digest to the actual message. When you receive my message, you can decrypt the digest and hash the message for comparison. If theres a match, the message is genuine. If there isnt, the message was tampered with. We havent solved all possible problems, though. Many questions remain. For instance: how can you be sure that the public key youre using is mine, and not a public key from somebody pretending hes me? What happens if my private key is compromised? Well answer these questions in the next chapters. First, we need to get acquainted with some acronyms and standards.

1.4 Overview of cryptography Acronyms and Standards

Understanding the terminology was one of the most important thresholds I encountered when I was first confronted with cryptography and digital signing. Heres a list of acronyms and standards, youll meet in the next couple of chapters. Youll also need to understand their meaning when using the PDF library iText to add digital signatures to PDF documents. 1.4.1 Acronyms PKI stands for Public Key Infrastructure. Its a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates. ASN.1 stands for Abstract Syntax Notation One. Its a standard and flexible notation that describes rules and structures for representing, encoding, transmitting, and decoding data in telecommunications and computer networking. BER stands for Basic Encoding Rules. They were the original rules laid out by the ASN.1 standard for encoding abstract information into a concrete data stream.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

19

Digital Signatures for PDF documents 2012

DER stands for Distinguished Encoding Rules. DER is a subset of BER providing for exactly one way to encode an ASN.1 value. Its drawn from the constraints placed on BER encodings by X.509. X.509 is a standard for a public key infrastructure (PKI) and privilege management infrastructure. It specifies, amongst other things, standard formats for public key certificates and certificate revocation lists. IETF stands for the Internet Engineering Task Force 4. They develop and promote internet standards, cooperating closely with the World Wide Web Consortium (W3C), the International Standards Organization (ISO) and the International Electrotechnical Commission (IEC). RFC stands for Request for Comments. An RFC is a memorandum published by the Internet Engineering Task Force (IETF) describing methods, behaviors, research, or innovations applicable to the working of the Internet and Internet-connected systems. FIPS stands for Federal Information Processing Standard5. Its a publicly announced standardization developed by the US federal government for use in computer systems. 1.4.2 Public-Key Cryptography Standards (PKCS) Apart from an encryption algorithm, RSA is also the name of an American computer and network security company. Just like the algorithm, it was named after the initials of its co-founders Rivest, Shamir and Adleman. The RSA Company has devised and published a group of public-key cryptography standards numbered from #1 to #15. Some of these standards are no longer in use. In the context of this paper, were mostly interested in PKCS#7, the Cryptographic Message Syntax (CMS), but well also take a look at a couple of other standards. PKCS#1: RSA Cryptography Standard This standard is published as RFC 3447. It defines the mathematical properties and format of RSA public and private keys (ASN.1 encoded in clear text), and the basic algorithms and encoding/padding schemes for performing RSA encryption, decryption, and producing and verifying signatures. Well encounter PKCS#1 briefly when talking about the sub filter /adbe.x509.rsa_sha1. PKCS#7: Cryptographic Message Syntax Standard This standard is published as RFC 2315. Its used to digitally sign, digest, authenticate or encrypt any form of digital data. The Cryptographic Message Syntax (CMS) is updated in RFC 5652. Its architecture is built around certificate-based key management, such as the profile defined by the PKIX (PKI X.509) working group. PKCS#11: Cryptographic Token Interface This standard is also known as Cryptoki which is an amalgamation of cryptographic token interface and is pronounced as crypto-key. Its an API defining a generic interface to cryptographic tokens, such as Hardware Security Modules (HSM), USB keys and smart cards. Well encounter PKCS#11 in chapter 4 where well sign a PDF using a Luna SA HSM and an iKey 4000 USB key.

4 5

http://www.ietf.org/ http://www.itl.nist.gov/fipspubs/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

20

Digital Signatures for PDF documents 2012

PKCS#12: Personal Information Exchange Syntax Standard This standard defines a file format used to store private keys with accompanying public key certificates, protected with a password-based symmetric key. In practice, these files will have the extension .p12. Its usable as format for the Java key store. Note that you may also encounter .pfx files. PFX is a predecessor to PKCS#12. PKCS#13: Elliptic Curve Cryptography Standard This standard is still under development (2012). Its an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields. We wont use PKCS#13 in the context of this paper, but well briefly mention it in section 2.1.4 when looking at the different encryption algorithms that are supported in PDF. 1.4.3 The PDF ISO Standard The Portable Document Format used to be a specification that was proprietary to Adobe. The first version was published in 1993 and Adobe owned the copyright, but soon it was made open in the sense that Adobe allowed developers to use the specification to create a PDF writer (such as iText6) and/or a PDF viewer (such as JPedal 7). Since 2001, a couple of subsets of the PDF specification were already published by the International Standardization Organization (ISO)8 as ISO standards: ISO-15930 (aka PDF/X) for the prepress sector and ISO-19005 (aka PDF/A) which is a standard for archiving PDFs. In 2007, Adobe decided to bring the PDF specification (at that time PDF 1.7) to the Enterprise Content Management Association (AIIM)9, for the purpose of publication as an ISO standard. ISO published the standard on July 1st, 2008 as ISO-32000-1. Other PDF standards followed or will follow in the future, such as ISO 24517 (aka PDF/E) for engineering, ISO 16612 (aka PDF/VT) for Variable Data Printing and Transaction printing, and ISO14289 (aka PDF/UA) for Universal Accessibility. In the meantime, were looking forward to ISO32000-2, the successor of ISO-32000-1. Its expected for 2013, at which point PDF 2.0 will be introduced. In this paper, were already taking into account some of the changes that will be introduced in PDF 2.0. 1.4.4 CAdES, XAdES and PAdES The European Telecommunications Standards Institute (ETSI) 10 is an independent, non-profit, standardization organization in the telecommunications industry (equipment makers and network operators). The organization publishes Technical Standards (TS) of which two are of great importance for us; CAdES and PAdES.

6 7

http://www.itextpdf.com/ http://www.jpedal.org/ 8 http://www.iso.org/ 9 http://www.aiim.org/ 10 http://www.etsi.org/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

21

Digital Signatures for PDF documents 2012

CMS Advanced Electronic Signatures (CAdES) CAdES is a set of extensions to CMS, making it suitable for advanced electronic signatures. Its described in ETSI TS 101 733. One important benefit from CAdES is that electronically signed documents can remain valid for long periods, even if underlying cryptographic algorithms are broken. XML Advanced Electronic Signatures (XAdES) XAdES is an extension to XML-DSig, a standard defining the XML syntax for digital signatures. Its described in ETSI TS 101 903. The use of XAdES is not supported in iText. Im mentioning it here only because its the technology used in PAdES Part 5. PDF Advanced Electronic Signatures (PAdES) PAdES is a set of restrictions and extensions to PDF and ISO-32000-1 making it suitable for advanced electronic signatures. Its described in ETSI TS 102 778, and it will be implemented in ISO -32000-2. PAdES consists of six parts: Part 1the first part is an overview of support for signatures in PDF documents, and it lists the features of the PDF profiles in the other documents. Part 2PAdES Basic is based on ISO-32000-1. If you want to know more about digital signatures in PDF, you should read this specification before starting to dig into the PDF reference. PAdES part 2 is supported in iText since version 5.0.0. Part 3PAdES Enhanced describes profiles that are based on CAdES: PAdES Basic Electronic Signature (BES) and Explicit Policy Electronic Signature (EPES). PAdES part 3 is supported in iText since version 5.3.0. Part 4PAdES Long-Term Validation (LTV) is about protecting data beyond the expiry of the users signing certificate. This mechanism req uires a Document Security Store (DSS). PAdES part 4 is supported in iText since version 5.1.3. Part 5PAdES for XML content describes profiles for XAdES signatures. For instance, after filling an XFA form, which is XML content embedded in a PDF file, a user may sign selected parts of the form. This isnt supported in iText yet. Part 6Visual representations of Electronic Signatures. This is supported in iText, but it also depends on other factors. For instance: does your certificate contain sufficient information?

Well discuss PAdES in more detail in the following chapters of this white paper. Note that the code used in this paper will only work with iText version 5.3.2 and later.

1.5 Summary
In this chapter, weve explored the different aspects of digital signing. First we looked at a PDF file and discovered how we could forge an existing document. Weve learned about hashing algorithms and encryption, and we found out how to combine these concepts to protect a PDF file. We ended with an overview of terms and standards. Now were ready to take a closer look at digital signatures inside a PDF file. In the next chapter, well put the theory into practice with a first set of examples.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

22

Digital Signatures for PDF documents 2012

2. PDF and digital signatures
In this paper, well combine the specifications found in ISO-32000-1 which is the PDF standard from the International Standardization Organization (ISO), TS 102 778 (aka PAdES) from the European Telecommunications Standards Institute (ETSI), and ISO-32000-2, the successor of ISO-32000-1 which hasnt been officially released yet. Some implementations explained in ISO-32000-1 will be deprecated in ISO-32000-2. There may also be room for interpretation when comparing the ISO standard with the ETSI standard, but whenever thats the case, well opt for what we believe is the most future-proof choice. Note that the principles explained in this paper are a summary. For more details, please consult the actual standards.

2.1 Digital signatures in PDF

In section 1.1, weve taken a look inside different PDF files. Weve looked at the infrastructure that is needed to digitally sign a PDF document. Now lets focus on the actual signature.

The sub filter refers to an encoding or a format that was used to create the signature. For instance: does it use PKCS#1, PKCS#7, or CAdES? Is part of the information (such as the public certificate) stored outside the signature, or is it embedded in the signature? NOTE: In PDF, we sometimes refer to a detached signature. According to Wikipedia, a detached signature is a type of digital signature that is kept separate from its signed data, as opposed to bundled together into a single file. This definition isnt entirely correct in the context of PDF: the signature is enclosed in the PDF file, but the attributes of the signature are part of the signature, as opposed to stored in the signature dictionary. In versions predating iText 5.3.0, youd sign a PDF document choosing one of the following parameters for the setCrypto() method: PdfSignatureAppearance.WINCER_SIGNED: this created a signature with the sub filter /adbe.pkcs7.sha1. PdfSignatureAppearance.SELF_SIGNED: this created a signature with the sub filter /adbe.x509.rsa_sha1.

These options have been removed in 5.3.0 for very specific reasons. The /adbe.pkcs7.sha1 sub filter will be deprecated in PDF 2.0. ISO-32000-2 recommends: To support backward compatibility, PDF readers should process this value for the /SubFilter key but PDF writers shall not use this value for that key. iText is a PDF writer, and since iText 5.3.0, we no longer allow the creation of this type of signatures. Please dont sign any documents using this sub filter anymore.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

23

2.1.1 The signature handler and the sub filters When creating a digital signature for a PDF, you need to define a preferred signature handler (a /Filter entry). In iText, well always use the Adobe.PPKLite filter. Its possible to adapt iText to use another filter, but theres very little need to do so: an interactive PDF processor can use any handler it prefers as long as the handler supports the specified /SubFilter format.

Digital Signatures for PDF documents 2012

As for /adbe.x509.rsa_sha1, it will still be available in PDF 2.0, but the underlying standard that is used (PKCS#1) is explicitly forbidden in PAdES11. That is: the value of the /Contents entry of a signature may not be a DER-encoded PKCS#1 binary data object. Weve discontinued support for the creation of pure PKCS#1 signatures, so that iText-created signatures comply with PAdES. NOTE: The encrypted digests in a PKCS#7 container are stored as embedded PKCS#1 objects. This is, of course, perfectly OK and allowed in the PAdES standard. With iText 5.3.0 (released in June 2012), we completely redesigned the digital signature functionality. From this version on, well use detached signatures by default, either /adbe.pkcs7.detached or /ETSI.CAdES.detached. NOTE: Theres also /ETSI.RFC3161, but if you look up RFC 3161, youll discover that its an X509 PKI time stamp protocol. Well cover time stamps in chapter 3 and chapter 5. It goes without saying that iText is versatile enough to allow creating signatures with the sub filters /adbe.x509.rsa_sha1 or /adbe.pkcs7.sha1, but we deliberately made it more difficult to do so in order to discourage their use. In the following sections and chapters, you can safely assume that were talking about detached signatures, unless specified otherwise. 2.1.2 The byte range covered by the digital signature Figure 6 shows a schematic view of a signed PDF.

Figure 6: A signed PDF

11

ETSI TS 102 778-2, section 5.1, Note 1

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

24

Digital Signatures for PDF documents 2012

In section 1.1.3, we inspected the syntax of a signed PDF, and we saw that the signature dictionary contains a /ByteRange entry. If you read ISO-32000-1, youll find out that this byte range may contain gaps: areas in the PDF that arent covered by the signature. In theory, these gaps could make the PDF vulnerable12. PAdES introduces an extra restriction to the PDF digital signature specification that has been taken into account in ISO-32000-2 for ETSI sub filters: If /SubFilter is /ETSI.CAdES.detached or /ETSI.RFC3161, the /ByteRange shall cover the entire file, including the signature dictionary but excluding the /Contents value. Moreover, recent versions of Adobe Acrobat/Reader have been rejecting signatures with greater or more holes in their byte range. Thats why iText always takes the complete byte range of the PDF document, regardless of the sub filter that was chosen. 2.1.3 How to compose a signature The elements needed to compose a signature are shown on one side in figure 7. The actual contents are shown on the other side.

Figure 7: the contents of a digital signature

To the left, we have the elements of the digital identity of a person: his private key and a certificate containing his public key and identity info. Note that most of the times, there will be a chain of certificates. This will be explained in more detail in chapter 3. For now, were working with a single self-signed certificate. NOTE: if you look closely at figures 6 and 7, you see that the complete document is covered by the digital signature. Its not possible to sign specific pages. Some cou ntries demand that every page is initialized for the signature to be valid so that theres proof that every page has been seen, but the concept to initial the pages of a document doesnt exist in PDF. In code sample 3 (section 1.1.3), we see a PKCS#1 signature (which is no longer supported), and the certificate was an entry in the signature dictionary. It wasnt part of the actual signature. F or CMS and CAdES based signatures, the certificate (or certificate chain) is embedded in the digital signature. The signature also contains a digest of the original document that was signed using the private key. Additionally, the signature can contain a timestamp.
12

See the article about Collisions in PDF Signatures by Florian Zumbiehl http://pdfsig-collision.florz.de/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

25

Digital Signatures for PDF documents 2012

2.1.4 Algorithms supported in PDF In section 1.2.2, we listed several digest algorithms we could use to create a message digest, but not all of the algorithms weve listed are supported in PDF. In section 1.3, we talked about the RSA encryption algorithm, but there are some other algorithms we can use for signing: The Digital Signature Algorithm (DSA) this is a FIPS standard for digital signatures. RSA can be used for both encrypting and signing; DSA is used mainly for signing. DSA is faster in signing, but slower in verifying. The Elliptic Curve Digital Signature Algorithm (ECDSA) this is a new standard (PKCS #13). It will be introduced in PDF 2.0; its not yet supported in iText.

Lets take a look at an overview of the digest and encryption algorithms that are supported based on the sub filter:

Note that the use of this sub filter for signature creation will be deprecated in PDF 2.0 (ISO-32000-2). Its no longer supported in iText since version 5.3.0. adbe.x509.rsa_sha1 Supported message digests: SHA1 (since PDF 1.3), SHA256 (since PDF 1.6), and SHA384, SHA512, RIPEMD160 (since 1.7). RSA Algorithm: up to 1024 bits (since PDF 1.3), 2048 bits (since PDF 1.5), 4096 bits (since PDF 1.7). DSA Algorithm: not supported. Note that despite the reference to SHA1 in the name, other digest algorithms are supported. As pure PKCS#1 is forbidden in the PAdES standard, we no longer support this sub filter in iText (since 5.3.0). adbe.pkcs7.detached, ETSI.CAdES.detached and ETSI.RFC3161 Supported message digests: SHA1 (since PDF 1.3), SHA256 (since PDF 1.6), and SHA384, SHA512, RIPEMD160 (since 1.7). RSA Algorithm: up to 1024 bits (since PDF 1.3), 2048 bits (since PDF 1.5), 4096 bits (since PDF 1.7). DSA Algorithm: up to 4096 bits (since PDF 1.6). ECDSA: the Elliptic Curve Digital Signature Algorithm will be supported in PDF 2.0. Detached signatures are supported by default in iText since version 5.3.0. All message digests are supported. As for encryption algorithms: theres support for RSA and DSA, but not yet for ECDSA. WARNING: The use of SHA-1 is being phased out in some countries, hence the use of other hashing algorithms is recommended. NIST (the US National Institute of Standards and Technology) advises that 1024-bit RSA keys are no longer viable (since 2010) and advises moving to 2048-bit RSA keys. So do other agencies in other countries, for instance in Germany.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

26

adbe.pkcs7.sha1 Supported message digests: SHA1 (other digests may be used to digest the signed-data field, but SHA1 is required to digest the PDF document data that is being signed). RSA Algorithm: up to 1024 bits (since PDF 1.3), 2048 bits (since PDF 1.5), 4096 bits (since PDF 1.7). DSA Algorithm: up to 4096 bits (since PDF 1.6).

Digital Signatures for PDF documents 2012

Its high time that we throw in an example, demonstrating how to sign a PDF document using iText.

2.2 The Hello World of digital signing using iText

Forget everything that was written in the first and second edition of iText in Action ; forget all the code you wrote before upgrading to iText 5.3.0. Signing a PDF using iText has been completely redesigned. Youll soon find out that the changes are for the better. 2.2.1 A simple example adding a visible signature to a document Lets start with the Hello World app of signing. How can we use iText to sign a file and get a result as is shown in figure 8?

Figure 8: a signature appearance

With code sample 10, we can create a very simple digital signature using iText. Code sample 10: the Hello World of signing with iText
public void sign(String src, String dest, Certificate[] chain, PrivateKey pk, String digestAlgorithm, String provider, CryptoStandard subfilter, String reason, String location) throws GeneralSecurityException, IOException, DocumentException { // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0'); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature(new Rectangle(36, 748, 144, 780), 1, "sig"); // Creating the signature ExternalDigest digest = new BouncyCastleDigest(); ExternalSignature signature = new PrivateKeySignature(pk, digestAlgorithm, provider); MakeSignature.signDetached(appearance, digest, signature, chain, null, null, null, 0, subfilter); }

Please be aware that this is far from the definite code sample, but its a start. Lets examine the example step by step.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

27

Digital Signatures for PDF documents 2012

First we create a PdfReader and a PdfStamper object. This is what youll always do in iText when you want to manipulate an existing PDF document. The main difference is that you have to use the createSignature() method instead of the PdfStamper constructor. Secondly, we define the appearance using the PdfSignatureAppearance class. Well go into more detail later on in this chapter, but for now we only set the reason for signing and the location. We also define a rectangle where the signature will be added (lower-left coordinate [36, 748]; upperright coordinate [144, 780]), a page number (page 1), and a name for the signature field (sig). Furthermore, we need an implementation of the ExternalDigest interface to create a digest and of the ExternalSignature interface to create the signature, a process that involves hashing as well as encryption. We can use Bouncy Castle as security provider for the digest by choosing an instance of the BouncyCastleDigest class. If you want another provider, use the ProviderDigest class. iText has only one implementation for the signing process: PrivateKeySignature; well use another implementation in chapter 4 when we sign a document using a smart card. The constructor of the PrivateKeySignature class needs a PrivateKey instance, a digest algorithm and a provider. For instance: we wont use Bouncy Castle as provider when we apply a signature using PKCS#11 in chapter 4. NOTE: Unless otherwise specified, iText uses the same digest algorithm for making the hash of the PDF bytes as defined for creating the signature. The encryption method (RSA or DSA) and the key size will be obtained from the private key object. If we use the key store we created in section 1.3.1, iText will use 2048-bit RSA encryption because those were the parameters we passed to the keytool utility. Were using the signDetached() method, which means were creating a detached signature, and we can choose between adbe.pkcs7.detached and ETSI.CAdES.detached. This is done with an enum named CrypoStandard in MakeSignature: use either CMS or CADES. WARNING: For the moment, were passing plenty of null objects and one 0 value to the signDetached() method. Its important to understand that were creating a signed PDF that only meets the minimum requirements of a digital signature. Youll need to replace at least two of those null values with actual objects if you want to create a signature that conforms to the best practices in signing. This will be discussed in chapter 3. Code sample 11 shows how we can create a variety of signed Hello World files. First we create a PrivateKey instance and an array of Certificate objects based on the keystore we created in section 1.3.1. Then we invoke the method from code sample 10 using different digest algorithms, choosing between CMS (PKSC#7 as described in ISO-32000-1 and PAdES 2) and CAdES (as described in PAdES 3). Code sample 11: signing a PDF using different algorithms and sub filters
public public public public static static static static final final final final String char[] String String KEYSTORE = "src/main/resources/ks"; PASSWORD = "password".toCharArray(); SRC = "src/main/resources/hello.pdf"; DEST = "results/chapter2/hello_signed%s.pdf";

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

28

Digital Signatures for PDF documents 2012

public static void main(String[] args) throws GeneralSecurityException, IOException, DocumentException { BouncyCastleProvider provider = new BouncyCastleProvider(); Security.addProvider(provider); KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType()); ks.load(new FileInputStream(KEYSTORE), PASSWORD); String alias = (String)ks.aliases().nextElement(); PrivateKey pk = (PrivateKey) ks.getKey(alias, PASSWORD); Certificate[] chain = ks.getCertificateChain(alias); SignHelloWorld app = new E04_SignHelloWorld(); app.sign(SRC, String.format(DEST, 1), chain, pk, DigestAlgorithms.SHA256, provider.getName(), CryptoStandard.CMS, "Test 1", "Ghent"); app.sign(SRC, String.format(DEST, 2), chain, pk, DigestAlgorithms.SHA512, provider.getName(), CryptoStandard.CMS, "Test 2", "Ghent"); app.sign(SRC, String.format(DEST, 3), chain, pk, DigestAlgorithms.SHA256, provider.getName(), CryptoStandard.CADES, "Test 3", "Ghent"); app.sign(SRC, String.format(DEST, 4), chain, pk, DigestAlgorithms.RIPEMD160, provider.getName(), CryptoStandard.CADES, "Test 4", "Ghent"); }

Figure 9 shows the different icons that indicate whether or not a signature is valid. As you can see, these icons have changed over the years depending on the version of Adobe Acrobat or Reader youre using.

Figure 9: Different icons used to recognize if a signature was validated

A red cross always means that your signature is broken: the content has been altered or corrupted, or one of the certificates isnt valid, and so on. In any case, you shouldnt trust the signature. WARNING: support for CAdES is very new. Dont expect versions older than Acrobat/Reader X to be able to validate CAdES signatures! Acrobat 9 only supports signatures as described in the specification for PDF 1.7, and CAdES is new in PDF 2.0. In figure 8, we get a yellow triangle with a message At least one signature has problems. A yellow triangle (or a question mark in older versions of Adobe Reader) means that the signature cant be validated because some information is missing. In our case, Adobe Reader says: The signature validity is unknown. Theres no problem with the integrity because we see that the Document has not been modified since this signature was applied. So whats missing? In section 1.3.1, we created our own key store for Bruno Specimen. Anyone can create such a key store and pretend that he or she is Bruno Specimen. Adobe Reader is aware of this problem and tells us: Signers identity is unknown because it has not been included in your list of trusted identities and none of its parent certificates are trusted identities. Lets ignore the second part about the parent certificates for now, and focus on the list of trusted identities first.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

29

Digital Signatures for PDF documents 2012

2.2.2 Manage trusted identities There are different ways to add a certificate to the list of trusted identities. One way is to look at the signature panel and to open the Certificate Viewer by clicking on Certificate Details under Certificate details. See figure 10.

Figure 10: Certificate details viewer: add to trusted identities

Theres a tab named Trust saying This is a self-signed certificate. The selected certificate path is valid. However: The certificate is not trusted. In the trust settings, theres a button with caption Add to trusted identities. If you click this button, you get another dialog, as shown in figure 11.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

30

Digital Signatures for PDF documents 2012

Figure 11: Import Contact Settings dialog

You could decide to use this certificate as a trusted root. Lets try this and see what happens. Go to Edit > Protection > Manage Trusted Identities as shown in figure 12:

Figure 12: Import Contact Settings dialog

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

31

Digital Signatures for PDF documents 2012

Youll find Bruno Specimen listed if you display the Certificates as is done in figure 1 3:

Figure 13: the Manage Trusted Identities dialog

From now on, youll see a green check mark when opening the signed document. See figure 14.

Figure 14: Signed document and the Signature is valid.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

32

Digital Signatures for PDF documents 2012

One way you can add the certificate to the trusted identities, but it defies the purpose of a digital signature. If you accept the validity of the signers identity anyway, why go through the hassle of signing? The initial idea we thought of when we discussed authentication, was that Bruno Specimen would send you his public certificate, and that you would use it to identify him. So l ets remove the certificate from that list of trusted identities, and try anew using a different approach. 2.2.3 Adding a certificate to the Contacts list in Adobe Reader Bruno Specimen can extract his public certificate from his key store using the command shown in code sample 12. Code sample 12: exporting a certificate from a key store
$ keytool -export -alias demo -file bruno.crt -keystore ks -storepass password Certificate stored in file <bruno.crt>

Figure 15: Import a Certificate into the Trusted Identities list But wait! What if you dont really dont know Bruno Specimen? What if somebody else sends you a public key pretending hes Bruno Specimen? How can you know that the person who is sending you his public key is the person he or she says he or she is?

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

33

The result is a file name that can be imported into Adobe Reader by clicking Add Contacts. Just browse for the file bruno.crt and click Import (see figure 15). The file will show up in the list of Trusted Identities, but dont forget to edit the trust settings! You need to explicitly trust the certificate (as is shown in figure 11) before youll be able to validate Bruno Specimens signature.

Digital Signatures for PDF documents 2012

There are different ways and mechanisms that allow you to obtain a green check mark without managing trusted identities by adding separate certificates manually. In chapter 3, well discuss certificate authorities, and in section 3.4, well discover different options to get a green check mark requiring less (or even no) manual intervention. First lets sign our Hello World file once more, using a different method to create a PdfStamper object. 2.2.4 Signing large PDF files When you use the createSignature() method as shown in code sample 10, iText will create a copy of the document youre about to sign in memory, leaving the bytes that are reserved for the signature blank. iText needs this copy so that it can provide the bytes that need to be hashed and signed. This can be problematic for files with a large file size: you risk OutOfMemoryExceptions. Take a look at code sample 13 if you want to store the copy on disk instead of keeping it in memory: Code sample 13: Signing a document using a temporary file

Theres only one difference with code sample 10, we added a File object as an extra parameter to the createSignature() method. The tmp variable in this code sample can be a path to a specific file or to a directory. In case a directory is chosen, iText will create a file with a unique name in that directory. NOTE: if you use the createSignature() method with a temporary file, you can use an OutputStream that is null, in that case, the temporary file will serve as the actual destination file. This is good practice if your goal is to store a signed file on your file system. If the OutputStream is not null, iText will always try to delete the temporary file after the signing is done. Make sure you use a path with sufficient writing permissions, and make sure you dont try to overwrite existing files if youre working in a multithreaded environment. As were working with very simple PDF files in these examples, well continue using the method that tells iText to keep the bytes in memory.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

34

public void sign(String src, String tmp, String dest, Certificate[] chain, PrivateKey pk, String digestAlgorithm, String provider, CryptoStandard subfilter, String reason, String location) throws GeneralSecurityException, IOException, DocumentException { // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0', new File(tmp)); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature(new Rectangle(36, 748, 144, 780), 1, "sig"); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, digestAlgorithm, provider); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, null, null, null, 0, subfilter);

Digital Signatures for PDF documents 2012

Weve already seen an example of a PDF with an invisible signature (see figure 3) and weve already seen PDF documents with a visible signature (see for instance figure 8). If you define a rectangle of which either the width, or the height (or both) are zero, youre creating an invisible signature. In code samples 10 and 13, we created a visible signature using a Rectangle object and absolute coordinates for the lower-left corner and the upper-right corner. When creating a document of which you know it will have to be signed, you can choose the coordinates of the signature rectangle in advance.

2.3 Creating and signing signature fields

Its not always simple to determine the coordinates where the signature should be placed. Thats why you may want to create a placeholder if you need a visible signature. Lets start by creating a PDF document with an empty signature field using Adobe Acrobat. 2.3.1 Adding a signature field using Adobe Acrobat Open the document that needs to be signed in Adobe Acrobat and select Forms > Add or Edit Fields in the menu. Now select Digital Signature in the drop-down list box under Add New Field, and draw a rectangle. Acrobat will suggest a name for the field, for instance Signature1. See figure 16. You can change this name if necessary, but for us this name will do.

Figure 16: adding an empty signature field using Adobe Acrobat Lets save this document, and fill it out using code sample 14. Code sample 14: Signing a signature field
public void sign(String src, String name, String dest, Certificate[] chain, PrivateKey pk, String digestAlgorithm, String provider, CryptoStandard subfilter, String reason, String location) throws GeneralSecurityException, IOException, DocumentException { // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0'); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location);

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

35

Digital Signatures for PDF documents 2012

appearance.setVisibleSignature(name); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, digestAlgorithm, provider); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, null, null, null, 0, subfilter); }

Again, theres only one difference with code sample 10. We no longer need to pass a rectangle and a page number; the name of the field is sufficient. This way, a developer no longer has to worry about finding the best coordinates to position the signature. Now lets see if we can create an empty signature field using iText. 2.3.2 Creating a signature field programmatically using iText If you know how to create AcroForm fields using iText, you know how to create an empty signature field as shown in figure 16. If you dont know anything about AcroForm fields, take a look at code sample 15. Code sample 15: Creating a signature field
public void createPdf(String filename) throws IOException, DocumentException { // step 1: Create a Document Document document = new Document(); // step 2: Create a PdfWriter PdfWriter writer = PdfWriter.getInstance( document, new FileOutputStream(filename)); // step 3: Open the Document document.open(); // step 4: Add content document.add(new Paragraph("Hello World!")); // create a signature form field PdfFormField field = PdfFormField.createSignature(writer); field.setFieldName(SIGNAME); // set the widget properties field.setPage(); field.setWidget( new Rectangle(72, 732, 144, 780), PdfAnnotation.HIGHLIGHT_INVERT); field.setFlags(PdfAnnotation.FLAGS_PRINT); // add it as an annotation writer.addAnnotation(field); // maybe you want to define an appearance PdfAppearance tp = PdfAppearance.createAppearance(writer, 72, 48); tp.setColorStroke(BaseColor.BLUE); tp.setColorFill(BaseColor.LIGHT_GRAY); tp.rectangle(0.5f, 0.5f, 71.5f, 47.5f); tp.fillStroke(); tp.setColorFill(BaseColor.BLUE); ColumnText.showTextAligned(tp, Element.ALIGN_CENTER, new Phrase("SIGN HERE"), 36, 24, 25); field.setAppearance(PdfAnnotation.APPEARANCE_NORMAL, tp); // step 5: Close the Document document.close(); }

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

36

Digital Signatures for PDF documents 2012

When using iText, a PDF file is created from scratch in five steps: create a Document object, create a PdfWriter, open the Document, add content, and close the Document. Were interested in the fourth step: adding content. NOTE: iText has different convenience classes for text fields ( TextField), push buttons (PushbuttonField), radio fields and checkboxes (RadioCheckField). For signatures, we use the generic class PdfFormField and we create the signature field using the convenience method createSignature(). We choose a name, and we set some other field properties if necessary. In a PDF form based on the AcroForm technology, each field corresponds with zero, one or more widget annotations. These annotations define the visual appearance of the field on the document. In this case, we use setPage() to indicate the signature field has to be added to the current page and setWidget() to define the position on the page, as well as the behavior when somebody clicks on the field widget. There are four different types of behavior: HIGHLIGHT_NONE no highlighting. HIGHLIGHT_INVERT inverts the content of the annotation square. HIGHLIGHT_OUTLINE inverts the annotation border. HIGHLIGHT_PUSH displays the annotation as if it were being pushed below the surface of the page

If a field corresponds with a single widget annotation (as is the case here), the field properties and the annotation properties are usually merged into a single dictionary object. We can add the field and its visual representation to a document by adding the PdfFormField object to the PdfWriter using the addAnnotation() method. NOTE: Is it possible to have one signature correspond with more than one widget? Im sorry, but thats not a good question. See the spec about digital signature appearances by Adobe: The location of a signature within a document can have a bearing on its legal meaning. For this reason, signatures never refer to more than one annotation. If more than one location is associated with a signature the meaning may become ambiguous. In code sample 15, we also create an appearance for the empty signature using the class PdfAppearance. This class extends the PdfTemplate class used in iText to create small patches of reusable content. Its not to be mistaken with the PdfSignatureAppearance class. With PdfAppearance, you define what the field looks like before its signed, whereas PdfSignatureAppearance defines what the field looks like after signing. Creating an appearance for an empty signature field is optional: if you omit this code, a valid signature field will be added, but the end user might not really notice it. Hell only see a small orange ribbon added by Adobe Reader marking the location of the field. The original, unsigned document and the resulting, signed document for code sample 15 are shown next to each other in figure 17.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

37

Digital Signatures for PDF documents 2012

Figure 17: iText created document with empty signature field and the same document signed If you want to add a signature field to an existing document, you can invoke the same method on a PdfStamper object. The only difference is that you dont define the page number on the level of the widget annotation. 2.3.3 Adding an empty signature field to an existing document using iText In code sample 16, we pass the page number as a second parameter for the addAnnotation() method in PdfStamper. Thats the main difference compared to what we saw in code sample 15. Code sample 16: adding a signature field to an existing PDF

PdfReader reader = new PdfReader(src); PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(dest)); // create a signature form field PdfFormField field = PdfFormField.createSignature(stamper.getWriter()); field.setFieldName(SIGNAME); // set the widget properties field.setWidget(new Rectangle(72, 732, 144, 780), PdfAnnotation.HIGHLIGHT_OUTLINE); field.setFlags(PdfAnnotation.FLAGS_PRINT); // add the annotation stamper.addAnnotation(field, 1); // close the stamper stamper.close();

We can now reuse the method from code sample 14 to sign the document weve created from scratch or the document to which weve added a signature field. Code sample 17 shouldnt have any secrets for you anymore. Code sample 17: Creating a document with a signature field, then sign it
CreateEmptyField appCreate = new CreateEmptyField(); appCreate.createPdf(UNSIGNED); BouncyCastleProvider provider = new BouncyCastleProvider(); Security.addProvider(provider); KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType()); ks.load(new FileInputStream(KEYSTORE), PASSWORD);

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

38

Digital Signatures for PDF documents 2012

String alias = (String)ks.aliases().nextElement(); PrivateKey pk = (PrivateKey) ks.getKey(alias, PASSWORD); Certificate[] chain = ks.getCertificateChain(alias); SignEmptyField appSign = new SignEmptyField(); appSign.sign(UNSIGNED, SIGNAME, DEST, chain, pk, DigestAlgorithms.SHA256, provider.getName(), CryptoStandard.CMS, "Test", "Ghent");

The signature appearance as shown in the signed PDF of figure 17 is what a signature created by iText looks like by default. It contains the following information: Who has signed the document? iText extracts this information from the certificate. When was the document signed? If you provide a connection to a timestamp server, iText will use the date provided by the TSA (see chapter 3). Otherwise, iText will use the date and time of the computer that is used for signing, or a Calendar object provided in your code. What was the reason for signing? The reason is provided by you or your program. Where was the document signed? The location is provided by you or your program.

2.4 Creating different signature appearances

Suppose your customer isnt used to digital signatures . Suppose he doesnt realize that the field marked with the text Digitally signed by is the visual representation of a valid digital signature. Suppose that he wants to see an image of a wet ink signature instead of some plain text. That image as such wouldnt have any legal value whatsoever, but it can be reassuring on a psychological level. Thats more or less what the recommendations in PAdES part 6 are about, and why iText provides different methods to create custom appearances for signatures. 2.4.1 Defining a custom PdfSignatureAppearance In this section, Im going to start by explaining something, and then I want you to completely forget all about it: in early versions of the PDF specification, a signature appearance consisted of five different layers that are drawn on top of each other. These layers were numbered from n0 to n4: n0Background layer. n1Validity layer, used for the unknown and valid state. n2Signature appearance, containing information about the signature. n3Validity layer, used for the invalid state. n4Text layer, for a text representation of the state of the signature

In old Acrobat versions, one would for instance create a graphic of a yellow question mark, and put that into layer n1. On top of this yellow question mark, in layer n2, youd put the information about the signature. If the signature was made invalid, youd see the content of layer n3, usually a red cross. Layers would be made visible or not, depending on the status of the signature.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

39

This information was chosen by the iText developers. It may not correspond with the way you want to present a signature, so lets find out how we can change this appearance.

Digital Signatures for PDF documents 2012

Now please forget about these layers. Since Acrobat 6 (2003) the use of layers n1, n3 and n4 is no longer recommended. The only reason I mention them is to avoid questions about the following code snippet. Code sample 18: Creating a custom appearance for the signature.
public void sign(String src, String name, String dest, Certificate[] chain, PrivateKey pk, String digestAlgorithm, String provider, CryptoStandard subfilter, String reason, String location) throws GeneralSecurityException, IOException, DocumentException { // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0'); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature(name); // Creating the appearance for layer 0 PdfTemplate n0 = appearance.getLayer(0); float x = n0.getBoundingBox().getLeft(); float y = n0.getBoundingBox().getBottom(); float width = n0.getBoundingBox().getWidth(); float height = n0.getBoundingBox().getHeight(); n0.setColorFill(BaseColor.LIGHT_GRAY); n0.rectangle(x, y, width, height); n0.fill(); // Creating the appearance for layer 2 PdfTemplate n2 = appearance.getLayer(2); ColumnText ct = new ColumnText(n2); ct.setSimpleColumn(n2.getBoundingBox()); Paragraph p = new Paragraph("This document was signed by Bruno Specimen."); ct.addElement(p); ct.go(); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, digestAlgorithm, provider); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, null, null, null, 0, subfilter); }

In code sample 15, we created a PdfAppearance for the signature field before signing, but this appearance was lost and replaced with a default appearance chosen by iText. Code sample 18 now creates a custom appearance instead of the default one. The code is more complex than sample 10 and 14 because we use low-level methods to create a custom PdfSignatureAppearance. We use the getLayer() method to obtain specific layers, and we draw custom content for the background to layer 0, and information about the signature to layer 2. NOTE: If youve followed the advice I gave in the first line of this section, this is the point where youre supposed to ask: Why are you only using layer 0 and layer 2? What happened to layer 1? The answer is: there used to be a layer 1, 3 and 4 (and youll find refe rences to them in iText), but you should no longer use them. PdfSignatureAppearance will ignore all changes applied to these layers, unless you add the following line to your code: appearance.setAcro6Layers(false); (Again: this is not recommended!)

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

40

Digital Signatures for PDF documents 2012

In code sample 18, we chose a gray rectangle as background and the text This document was signed by Bruno Specimen for the signature information. The result is shown in figure 18.

Figure 18: A signature with a custom appearance

Creating your own appearance is fun, but it demands more work. iText provides some convenience methods that allow you to create custom appearances in a more programmer-friendly way. 2.4.2 Creating signature appearances using convenience methods Suppose you want to change the signature information, but you dont want to have to draw the text using PdfContentByte or ColumnText methods. Custom text Adding text is made easy using the setLayer2Text() and setLayer2Font() methods. Theres even a setRunDirection() method if you want to add text that is written from right to left. Adding an image in the background of the text, can be done with the setImage() method. These methods are used to create the signature widgets shown in figure 19.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

41

Digital Signatures for PDF documents 2012

Figure 19: Signature appearances with custom text or background

Code sample 19 shows the relevant snippets of the complete source code for this example. Code sample 19: Custom signature info and background image.

public void sign1() throws GeneralSecurityException, IOException, DocumentException { // Custom text and custom font appearance.setLayer2Text("This document was signed by Bruno Specimen"); appearance.setLayer2Font(new Font(FontFamily.TIMES_ROMAN)); } public void sign2() throws GeneralSecurityException, IOException, DocumentException { // Custom text, custom font, and right-to-left writing appearance.setLayer2Text( "\u0644\u0648\u0631\u0627\u0646\u0633 \u0627\u0644\u0639\u0631\u0628"); appearance.setRunDirection(PdfWriter.RUN_DIRECTION_RTL); appearance.setLayer2Font( new Font(BaseFont.createFont("C:/windows/fonts/arialuni.ttf", BaseFont.IDENTITY_H, BaseFont.EMBEDDED), 12)); } public void sign3() throws GeneralSecurityException, IOException, DocumentException { // Custom text and background image appearance.setLayer2Text("This document was signed by Bruno Specimen"); appearance.setImage(Image.getInstance(IMG));

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

42

Digital Signatures for PDF documents 2012

appearance.setImageScale(1); } public void sign4() throws GeneralSecurityException, IOException, DocumentException { // Default text and scaled background image appearance.setImage(Image.getInstance(IMG)); appearance.setImageScale(-1); }

Observe that we use the run direction in the sign2() method to create the signature of Lawrence of Arabia in Arabic. Custom images In sign3(), we add an image using its original dimensions: the image scale is 100%. Change the scale value to 0.5f if you want the image to be scaled to 50%, to 2f if you want it scaled 200%. If you omit the setImageScale() method, iText will scale the image to the absolute dimensions of the signature field, possibly changing the aspect ratio of the image. If you want to avoid the distortion of the background image, you can pass a negative value as the image scale parameter as is done in the sign4() method. Custom rendering mode Apart from changing the signature info and the background, iText also allows you to choose from four different rendering modes: RenderingMode.DESCRIPTIONthis is the default, it just shows whatever description was defined for layer 2. RenderingMode.NAME_AND_DESCRIPTIONthis will split the signature field in two and add the name of the signer on one side, the description on the other side. RenderingMode.GRAPHIC_AND_DESCRIPTIONthis will split the signature field in two and add an image on one side, the description on the other side. RenderingMode.GRAPHICthe signature field will consist of an image only; no description will be shown.

Figure 20 shows an example of every rendering mode.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

43

Digital Signatures for PDF documents 2012

Figure 20: Signature appearances with different rendering modes

The rendering mode is set using the setRenderingMode() method. Make sure that you also define an image using the setSignatureGraphic() method if you choose the rendering mode GRAPHIC_AND_DESCRIPTION or GRAPHIC. See code sample 20. Code sample 20: Changing the rendering mode and adding a signature graphic
PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature(name); appearance.setLayer2Text("Signed on " + new Date().toString()); appearance.setRenderingMode(renderingMode); appearance.setSignatureGraphic(image);

So far, weve always added a reason and a location to the signature appearance. This information is present in the signature dictionary, but this isnt the only metadata we can add. 2.4.3 Adding metadata to the signature dictionary The PDF specification allows you to add the following metadata to the signature dictionary: Name the name of the person or authority signing the document. This value should be used only when its not possible to extract the name from the signature. M the time of signing. Depending on the signature handler, this may be a normal unverified computer time or a time generated in a verifiable way from a secure server. This should only be used when the time of signing isnt available in the signature. Location the CPU host name or the physical location of the signing. Reason the reason for signing, such as I agree.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

44

Digital Signatures for PDF documents 2012

ContactInfo information provided by the signer to enable a recipient to contact the signer to verify the signature, for instance a phone number.

The name and the signature time are set by iText automatically, but you can override them. Lets take a look at code sample 21 to find out how this is done. Code sample 21: Setting the metadata for the signature dictionary
PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature(name); appearance.setContact(contact); appearance.setSignDate(signDate); appearance.setSignatureEvent( new SignatureEvent(){ public void getSignatureDictionary(PdfDictionary sig) { sig.put(PdfName.NAME, new PdfString(fullName)); } } );

We change the signature time using the setSignDate() method. This is a dangerous method: if you choose a date that predates the certificate, youll get a warning (a yellow triangle message) saying Signers identity is invalid because it has expired or is not yet valid. If you choose a date in the future, the signature will be broken (a red-cross icon) with the message There are errors in the formatting or information contained in this signature (Signature seems to be signed in future). NOTE: Its NOT a good idea to use the setSignDate() method. Apart from risking error messages in Adobe Reader, using the wrong date when signing a document may also be considered as fraud. Moreover, many instances wont accept a document that is signed without an official timestamp from a TSA. See chapter 3 to find out why a document that is signed without a time stamp could be considered as a useless document. If you take a closer look to code sample 21, you see that there are methods to set the reason, location, and contact info, but suppose that you want to add a key for which there s no method available in iText. In that case, you can use the SignatureEvent interface. Its getSignatureDictionary() method will be called right before the dictionary is written to the file, so you can use it to add extra keys or to override existing ones. In the code sample, I added a name Bruno L. Specimen which is slightly different from the name on the certificate. NOTE: This example is meant to explain a concept. Dont use it in your applications. Many of these metadata values arent visible in Adobe Reader. For example: Adobe Reader will prefer the name obtained from the certificate instead of the name added in the signature dictionary (which should only be used in case the name cant be retrieved from the certificate). Youll need to look inside the PDF document (for instance using iText RUPS) to see the information we added in code sample 21. Figure 21 shows such a look inside.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

45

Digital Signatures for PDF documents 2012

Figure 21: A look inside a signed PDF showing the keys of the Signature dictionary Theres one more method, actually a very important one, we havent discussed yet: a method to set the certification level. 2.4.4 Ordinary and Certifying signatures There are three different types of signatures. One of them isnt relevant in the context of this paper. Two of them are shown in figure 22.

Figure 22: Ordinary (approval) and Certification (author) signature

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

46

Digital Signatures for PDF documents 2012

ISO-32000-1 specifies that a PDF document may contain the following standard types of signatures: One or more approval signatures these signatures appear in signature form fields. The upper left document in figure 22 is an example of such a signature. Adobe Reader shows a green check mark when a valid approval signature is present. At most one certification signature this signature can define different permissions, as shown in figure 22. Youll see a blue ribbon when a document was certified. At most two usage rights signatures these are signatures created using a private key that is proprietary to Adobe. When a PDF document is signed using this key, the document is Reader enabled. Adobe Reader will unlock certain usage rights, for instance allowing you to save a filled out form locally. This type of signature is outside the scope of this paper.

Lets recycle code sample 10 once more, and add one line:
public void sign(String src, String dest, Certificate[] chain, PrivateKey pk, String digestAlgorithm, String provider, CryptoStandard subfilter, int certificationLevel, String reason, String location) throws GeneralSecurityException, IOException, DocumentException { // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0'); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature(new Rectangle(36, 748, 144, 780), 1, "sig"); appearance.setCertificationLevel(certificationLevel); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, digestAlgorithm, provider); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, null, null, null, 0, subfilter); }

In code sample 22, we pass a parameter named certificationLevel. This parameter can have one of the following values available as constants in the PdfSignatureAppearance class: NOT_CERTIFIED creates an ordinary signature aka an approval or a recipient signature. A document can be signed for approval by one or more recipients. CERTIFIED_NO_CHANGES_ALLOWED creates a certification signature aka an author signature. After the signature is applied, no changes to the document will be allowed. CERTIFIED_FORM_FILLING creates a certification signature for the author of the document. Other people can still fill out form fields or add approval signatures without invalidating the signature. CERTIFIED_FORM_FILLING_AND_ANNOTATIONS creates a certification signature. Other people can still fill out form fields- or add approval signatures as well as annotations without invalidating the signature.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

47

Code sample 22: Setting the certification level

Digital Signatures for PDF documents 2012

Up until now, weve always created documents containing a single signature. In section 2.5, well describe different workflows adding multiple signatures to the same document. 2.4.5 Adding content after a document was signed Unless otherwise specified, for instance using a signature lock dictionary changing the signatures modification detection and protection (MDP) level (see section 2.5.5), you can always fill out fields, add extra signatures and annotations to a document that was signed using an ordinary signature, but make sure you do it correctly. Code sample 23 shows how NOT to do it: Code sample 23: how NOT to add an annotation to a signed document
public void addWrongAnnotation(String src, String dest) throws IOException, DocumentException { PdfReader reader = new PdfReader(src); PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(dest)); PdfAnnotation comment = PdfAnnotation.createText(stamper.getWriter(), new Rectangle(200, 800, 250, 820), "Finally Signed!", "Bruno Specimen has finally signed the document", true, "Comment"); stamper.addAnnotation(comment, 1); stamper.close(); }

This example will work perfectly for PDF documents without any signature. PdfStamper will take the objects that are read by PdfReader, add new objects that represent a text annotation, and reorganize the objects creating a new document. The internal structure of this new PDF file can be quite different when compared to the original file. It goes without saying that this will break the signature. Code sample 24 shows how to preserve the original bytes that were signed: Code Sample 24: how to add an annotation to a signed document

public void addAnnotation(String src, String dest) throws IOException, DocumentException { PdfReader reader = new PdfReader(src); PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(dest), '\0', true); PdfAnnotation comment = PdfAnnotation.createText(stamper.getWriter(), new Rectangle(200, 800, 250, 820), "Finally Signed!", "Bruno Specimen has finally signed the document", true, "Comment"); stamper.addAnnotation(comment, 1); stamper.close(); }

Did you spot the difference? The code is almost identical. We only used a different constructor for PdfStamper. The zero byte means we dont want to change the version number of the PDF file. The Boolean value indicates whether or not we want to manipulate the file in append mode. This value is false by default. The original bytes arent preserved. By changing this value to true, we tell iText not to change any of the original bytes. This is often referred to as using PdfStamper in append mode. The extra objects defining the annotation will be added after the original %%EOF statement. Some other objects will be overridden, but the original file structure will be kept intact. As a result, an ordinary signature will not be broken when using code sample 24.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

48

Digital Signatures for PDF documents 2012

If we take a closer look at figure 22, we see messages such as only commenting, form fill-in, signing and page adding actions are allowed. Thats a document signed with certification level form filling and annotations. Code sample 24 wont break such a signature either. NOTE: Be aware that page adding actions are allowed doesnt mean you can use the insertPage() method. This message refers to page template instantiation as described in the Adobe Acrobat JavaScript Reference Manual, which is out of scope in this paper. There are two more PDFs with another message Only form fill-in, signing and page adding actions are allowed and No changes are allowed. Adding an annotation as is done in code sample 24 will break those signatures. This is shown in figure 23. The upper window shows a certifying signature with a certification level that allows adding a text annotation or commenting. Its still a Valid certified Document . The lower window shows a certifying signature with a certification level that doesnt allow any changes. As weve added an annotation, the Signature is invalid.

Figure 23: Preserving or breaking a signature Its important to understand that adding or removing any other content will break any type of signature. For instance: its not possible to add some extra words to a page. Code sample 25: Breaking a signature by adding text
public void addText(String src, String dest) throws IOException, DocumentException { PdfReader reader = new PdfReader(src); PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(dest), '\0', true); ColumnText.showTextAligned(stamper.getOverContent(1), Element.ALIGN_LEFT, new Phrase("TOP SECRET"), 36, 820, 0); stamper.close();

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

49

Digital Signatures for PDF documents 2012

}

Code sample 25 works for most ordinary PDFs, but it will always break the signature of a signed PDF, even if we create the PdfStamper object in append mode. The code to add a second signature (and a third, and a fourth) is similar to the code adding an annotation. Code sample 26 wont break existing signatures unless the modification detection and protection level of one of the signatures is no changes allowed. Code sample 26: adding an extra signature
public void signAgain(String src, String dest, Certificate[] chain, PrivateKey pk, String digestAlgorithm, String provider, CryptoStandard subfilter, String reason, String location) throws GeneralSecurityException, IOException, DocumentException { // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0', null, true); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature( new Rectangle(36, 700, 144, 732), 1, "Signature2"); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, digestAlgorithm, provider); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, null, null, null, 0, subfilter); }

Figure 24 shows two examples, in the upper window, we have a document that is signed twice by Bruno Specimen, once with a certification signature that allowed adding form fields and once with an approval signature. In the lower window, the first signature was a certification signature that doesnt allow a second signature.

Figure 24: Documents that are signed twice

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

50

Digital Signatures for PDF documents 2012

This functionality is very useful in a workflow where different people have to approve a document.

2.5 Signatures in PDF and workflow

Imagine a book publisher drawing up a contract for a book written by two authors. Such a book contract could contain one certification signature from the publisher, saying: I have written this contract. This is legally binding. In addition, the authors could add their approval signature, saying: We agree to the terms of the contract. When I wrote my first books for Manning publications, I received a paper contract that I had to sign with a wet ink signature. I then had to mail it from Belgium to the US using snail mail. Wouldnt it be great if we could use digital signatures to achieve this? 2.5.1 Sequential signatures in PDF Figure 25 shows what a PDF that is signed multiple times looks like on the inside.

Figure 25: Schematic view of a PDF file that is signed trice The part above the line marked with Rev1 is revision 1 of the document. Its identical to what we had in figure 6. When signing the document with a second signature, we dont change any of the bytes of revision 1. We add additional content (provided that the first signature allows this content), and we create a new signature. This new signature is based on a message digest that includes the entire byte array of revision 1. The result is revision 2. When signing the document with a third signature, the bytes of revision 2 are preserved. NOTE: Looking at figure 25, you see that the signatures have to be applied sequentially. Its not possible to sign in parallel. For instance: a publisher cant send his contract to two authors at the same time for approval, and then merge the signed documents afterwards if the signatures need to be in the same document (as opposed to bundled in a portfolio). One author always has to sign the contract first, then followed by the other author.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

51

Digital Signatures for PDF documents 2012

Weve already seen an example of a document that was signed twice by Bruno Specimen. In the next section, well make some examples that need to be signed by different parties. 2.5.2 Creating a form with placeholders for multiple signatures Figure 26 is a form with three empty signature fields. In code samples 15 and 16, we created such fields using the PdfFormField class and we used a hardcoded Rectangle to define its position.

Figure 26: This form needs to be signed by Alice, Bob, and Carol

In code sample 27, well let iText define the position. Well create a table with one column, and well use cell events to add the signature fields at the correct position in the table. Code sample 27: Creating a form with empty fields

public void createForm() throws IOException, DocumentException { Document document = new Document(); PdfWriter writer = PdfWriter.getInstance(document, new FileOutputStream(FORM)); document.open(); PdfPTable table = new PdfPTable(1); table.setWidthPercentage(100); table.addCell("Signer 1: Alice"); table.addCell(createSignatureFieldCell(writer, "sig1")); table.addCell("Signer 2: Bob"); table.addCell(createSignatureFieldCell(writer, "sig2")); table.addCell("Signer 3: Carol"); table.addCell(createSignatureFieldCell(writer, "sig3")); document.add(table); document.close(); } protected PdfPCell createSignatureFieldCell(PdfWriter writer, String name) { PdfPCell cell = new PdfPCell(); cell.setMinimumHeight(50); PdfFormField field = PdfFormField.createSignature(writer); field.setFieldName(name);

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

52

Digital Signatures for PDF documents 2012

field.setFlags(PdfAnnotation.FLAGS_PRINT); cell.setCellEvent(new MySignatureFieldEvent(field)); return cell; } public class MySignatureFieldEvent implements PdfPCellEvent { public PdfFormField field; public MySignatureFieldEvent(PdfFormField field) { this.field = field; } public void cellLayout(PdfPCell cell, Rectangle position, PdfContentByte[] canvases) { PdfWriter writer = canvases[0].getPdfWriter(); field.setPage(); field.setWidget(position, PdfAnnotation.HIGHLIGHT_INVERT); writer.addAnnotation(field); } }

The createForm() method is pretty straightforward. We create a document from scratch in five steps. In step four, we create a table with one column; we define its width percentage. Then we add six cells, and we add the table to the document. Three cells are created in a separate method. The createSignatureFieldCell() method creates a PdfPCell instance, we define a minimum width, and then we create a signature field. We dont define a widget yet. Instead we pass the field object to a PdfPCellEvent and we add an instance of this event to the cell. What does this event do? After the cell is rendered to the page by iText, the cellLayout() method is invoked. In this method, we set the page and the position of the signature field, and we add the signature field to the PdfWriter. Now lets sign this form three times.

2.5.3 Signing a document multiple times Please read figure 27 from top to bottom. Theres revision 1 signed by Alice using a certification signature. Two blank signature fields remain. Revision two is signed by Bob. Finally revision 3 is signed by Carol.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

53

Digital Signatures for PDF documents 2012

Figure 27: Signing a document trice

They all signed their revision using code sample 28. Code sample 28: Signing in append mode

public void sign(String keystore, int level, String src, String name, String dest) throws GeneralSecurityException, IOException, DocumentException { KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType()); ks.load(new FileInputStream(keystore), PASSWORD); String alias = (String)ks.aliases().nextElement(); PrivateKey pk = (PrivateKey) ks.getKey(alias, PASSWORD); Certificate[] chain = ks.getCertificateChain(alias); // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0', null, true); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setVisibleSignature(name); appearance.setCertificationLevel(level); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, "SHA-256", "BC"); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, null, null, null, 0, CryptoStandard.CMS); }

Alice, Bob and Carol signed the form in the order as defined in code sample 29. Note that the value of DEST in this example isnt a path (as was the case in previous examples), but a pattern for a path. Code sample 29: Signing a document multiple times
app.sign(ALICE, PdfSignatureAppearance.CERTIFIED_FORM_FILLING, FORM, "sig1", String.format(DEST, "alice"));

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

54

Digital Signatures for PDF documents 2012

app.sign(BOB, PdfSignatureAppearance.NOT_CERTIFIED, String.format(DEST, "alice"), "sig2", String.format(DEST, "bob")); app.sign(CAROL, PdfSignatureAppearance.NOT_CERTIFIED, String.format(DEST, "bob"), "sig3", String.format(DEST, "carol"));

That is: first Alice added a certification signature, and then Bob and Carol added an approval signature. Suppose we switched the order. Suppose that Alice and Bob first approve the document, and that Carol certifies the document afterwards. Or suppose that both Alice and Carol try adding a certification signature, what will happen? I never questioned this before I wrote this paper, because when discussing modification detection and prevention using certification signatures, ISO-32000-1 mentions the author of a document as the person applying the first signature'13. Out of curiosity, I tried three different setups and I was surprised by the result. Apparently, the certification signature doesnt have to be the first signature in the document. I dont know if it makes sense, but Adobe Reader validates documents that are signed by approval signatures first, followed by a certification signature as correct, provided that the certification level allows form filling. I was also surprised by the output if the final signature is a certification signature that doesnt allow form filling. If you look closely at figure 28, you can see that Caro ls certification signature is valid, but the original signatures by Alice and Bob are broken. Somehow this doesnt make sense, does it?

Figure 28: Strange results for strange signature operations As expected, Alices certification signature is invalid after Carol tried to sign the document using a second certification signature, but the output is kind of strange. In the signature panel, we see Certified by %s instead of Certified by Carol, and theres a looking glass instead of a red cross.
13

See ISO-32000-1, section 12.8.8.2.1 1

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

55

Digital Signatures for PDF documents 2012

These situations are rather exotic and to be avoided. Lets focus on real life examples, and combine signing with form filling. 2.5.4 Signing and filling out fields multiple times Lets create another form that needs to be signed by four parties. See the form shown in figure 29.

Figure 29: A form containing signature fields as well as text fields.

Again, Alice will be the author of the document. Shell sign first using a certification signature that allows form filling. Secondly, Bob will have to fill in a field, writing Read and approved by Bob, after which he signs the document with an approval signature. Thirdly, Alice needs to do the same thing. Finally, Dave approves the document as the fourth party in the workflow. Figures 30 to 35 show different steps in the process.

Figure 30: step 1, the document is certified by Alice

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

56

Digital Signatures for PDF documents 2012

In figure 31, Bob has filled out the field named approved_bob. The signature panel says that Changes have been made to this document that are permitted by the certifying party . Code sample 30 shows how you could fill out this field using iText. Code sample 30: filling out a form using iText
public void fillOut(String src, String dest, String name, String value) throws IOException, DocumentException { PdfReader reader = new PdfReader(src); PdfStamper stamper = new PdfStamper(reader, new FileOutputStream(dest), '\0', true); AcroFields form = stamper.getAcroFields(); form.setField(name, value); form.setFieldProperty(name, "setfflags", PdfFormField.FF_READ_ONLY, null); stamper.close(); }

As you can see, were using PdfStamper in append mode to avoid breaking Alices signature. The rest of the code is pretty standard in iText. You get an AcroFields object from the stamper, and you fill out fields using the setField() method, passing a key (the name as it was defined in the form) and a value. We also set the field to read only so that somebody further down the workflow doesnt accidentally change the field. The method setFieldProperty() expects four parameters: field the name of the field of which you want to change a property action the action you want to perform (fflags will replace all field flags, setfflags will add field flags, clrfflags will remove all field flags). value one or more properties set using field flags you want to change. See the constants starting with FF_ in the PdfFormField class). Inst[] an array of indexes to select specific field items. In this case, each field corresponds with a single item, so its safe to use null (which will apply the property to all items).

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

57

Figure 31: step 2, Bob says he has read and approved the document

Digital Signatures for PDF documents 2012

In the next step, Bob signs with an approval signature. See figure 32:

Figure 32: step 3, Bob has signed the document for approval Now Carol repeats these two steps.

Figure 33: step 4, Alice says she has read and approved the document Although filling out a field after signing for approval is allowed, we see a yellow question mark in figure 33. Theres nothing to worry about: none of the signatures i s broken. Filling out fields after a document was signed for approval is allowed, but we get a warning when the value of fields (in this case a field named approved_carol) has changed. If we take a look at figure 34, we see that the yellow triangle disappears as soon as Carol signs the document.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

58

Digital Signatures for PDF documents 2012

Figure 34: step 5, signed for approval by Carol

We still see an extra line in the signatures panel saying the field approved_carol was filled out, but the yellow triangle previously shown in the upper blue bar (partly covered by the blue certification ribbon) has now been replaced with blue circle with an i inside. The exclamation point informs us that a change was applied, but the change was allowed by the MDP settings of the signatures. Its probably a good idea to skip the form filling step, and to fill out the form and sign it simultaneously. Thats what we do in code sample 31. Code sample 31: Filling and signing in one go

public void fillOutAndSign(String keystore, String src, String name, String fname, String value, String dest) throws GeneralSecurityException, IOException, DocumentException { KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType()); ks.load(new FileInputStream(keystore), PASSWORD); String alias = (String)ks.aliases().nextElement(); PrivateKey pk = (PrivateKey) ks.getKey(alias, PASSWORD); Certificate[] chain = ks.getCertificateChain(alias); // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0', null, true); AcroFields form = stamper.getAcroFields(); form.setField(fname, value); form.setFieldProperty(fname, "setfflags", PdfFormField.FF_READ_ONLY, null); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setVisibleSignature(name); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, "SHA-256", "BC"); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, null, null, null, 0, CryptoStandard.CMS); }

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

59

Digital Signatures for PDF documents 2012

The final result is shown in figure 35:

Figure 35: step 6, Dave said he approves the document and signed it

We have protected the fields against accidental change by other people down the workflow, but one could easily change the read-only status, and replace the value of the field in a later revision. Wouldnt it be nice if an approval signature could lock a field or even the whole document the way you can lock a document using a certification signature? Lets take a look at the different options. 2.5.5 Locking fields and documents after signing Since PDF 1.5, its possible to lock s pecific fields when signing a document. In PDF 2.0, there will be a new feature that allows you to define the same permissions that are already available for certification signatures, but now also for approval signatures. In both cases, this be achieved by adding a /Lock entry to the signature field with a PdfSigLockDictionary as value. Code sample 32 shows different flavors of this dictionary. Code sample 32: creating PdfSigLockDictionary objects
table.addCell("For approval by Bob"); table.addCell(createTextFieldCell("approved_bob")); PdfSigLockDictionary lock = new PdfSigLockDictionary(LockAction.INCLUDE, "sig1", "approved_bob", "sig2"); table.addCell(createSignatureFieldCell(writer, "sig2", lock)); table.addCell("For approval by Carol"); table.addCell(createTextFieldCell("approved_carol")); lock = new PdfSigLockDictionary(LockAction.EXCLUDE, "approved_dave", "sig4"); table.addCell(createSignatureFieldCell(writer, "sig3", lock)); table.addCell("For approval by Dave"); table.addCell(createTextFieldCell("approved_dave")); lock = new PdfSigLockDictionary(LockPermissions.NO_CHANGES_ALLOWED); table.addCell(createSignatureFieldCell(writer, "sig4", lock));

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

60

Digital Signatures for PDF documents 2012

The first lock instance defines that we want to lock sig1 (Alices signature), approved_bob (Bobs text field) and sig2 (Bobs signature) as soon as Bob signs. The second lock defines that we want to lock all fields except approved_dave and sig4 as soon as Carol signs. The final lock object defines that no changes whatsoever are allowed on the document as soon as Dave signs. These are the values you can use as LockAction if you want to lock specific fields: ALL lock all fields in the document. INCLUDE lock all fields added to the signature lock dictionary. EXCLUDE lock all fields except those added to the signature lock dictionary.

If you want to define a lock that covers the whole document, use the PdfSigLockDictionary constructor with one LockPermissions argument. iText will automatically select LockAction.ALL, and youll need to choose one of the following LockPermissions: NO_CHANGES_ALLOWED after approval, nobody can change the document without breaking the signature FORM_FILLING after approval, form filling is allowed. FORM_FILLING_AND_ANNOTATION after approval, form filling and adding annotations is allowed.

If a document already has specific permissions in place, you need to apply a more restrictive action. You cant use this functionality to remove restrictions. Lets take a look at code sample 33 and examine the createSignatureFieldCell() snippet that adds the lock to the signature field. Code sample 33: locking fields

PdfFormField field = PdfFormField.createSignature(writer); field.setFieldName(name); if (lock != null) field.put(PdfName.LOCK, writer.addToBody(lock).getIndirectReference()); field.setFlags(PdfAnnotation.FLAGS_PRINT);

We dont add the PdfSigLockDictionary entry straight to the field object. Instead we add the dictionary to the PdfWriter instance first using the addToBody() method. This writes the object to the OutputStream creating a reference number. We use that number to create an indirect reference object with the getIndirectReference() method, and add it as value for the /Lock entry. Why? Because ISO-32000-1 demands that the entry shall be an indirect reference. Lets take a look at figure 36 to see the form with all fields filled in and all signatures applied. The final line in the signature panel informs us that the document was locked by sig4.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

61

Digital Signatures for PDF documents 2012

Figure 37 shows what happens if Chuck changes Bobs text field after Bob signed the document.

Figure 37: Bobs signature is broken by Chuck Bobs signature is broken because the approved_bob field was locked by sig2. Figure 38 shows what happens if Chuck changes approved_carol after Dave has signed.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

62

Figure 36: locked fields after final approval

Digital Signatures for PDF documents 2012

Carols signature is broken because sig3 restricted the permissions on Carols text field. Daves signature is also broken because sig4 doesnt allow any further changes on the complete document. Lets conclude this section with one final note about the LockPermissions functionality: this extra permission that can be set on the document level will only be introduced in ISO-32000-2 (PDF 2.0), but you can already use it in Adobe Acrobat and Adobe Reader X.

2.6 Summary

In this chapter, we started with a simple Hello World example showing how easy it is to sign a document using iText. In the examples that followed, we focused mainly on the cosmetic aspects of a signature. We learned how to create a signature field, and we found out how to create a variety of appearances. We noticed that there are different types of signatures: the blue ribbon and the green check mark signatures. The former represent certification or author signa tures, the latter are approval signatures. We ended this chapter by applying one certification and multiple approval signatures in a workflow. All these examples were meant to get acquainted with using iText for signing PDF documents. The signatures weve created so far arent created using the best practices. In the next chapter, well explain whats missing.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

63

Figure 38: Carols and Daves signature are broken by Chuck

Digital Signatures for PDF documents 2012

3 Certificate Authorities, certificate revocation and time stamping
Youre reading this paper with a specific goal. This goal was summarized in the introduction using three bullets. You want to use digital signatures to ensure: The integrity of the document assurance that the document hasnt been changed somewhere in the workflow. The authenticity of the document assurance that the author of the document is who you think it is (and not somebody else) Non-repudiation assurance that the author cant deny his or her authorship.

In the real world, we want documents to be signed by real human beings or real organizations, not by people weve made up. Thats what this chapter is about. We want to make sure that we can trust the document, its signature and its signer.

3.1 Certificate authorities

Imagine two real-world people who have never met: Alice and Bob. Alice needs to send a signed PDF document to Bob. For Bob to be able to validate the signature in the document, he needs Alices public certificate. That certificate is embedded in the signed PDF document, so he could add it to his list of Trusted Identities (2.2.2), but how does Bob know he can trust that certificate? Anyone can make a self-signed certificate using Alices name. This problem can be solved by involving a third person who knows both Alice and Bob. This person needs to be a trusted entity, so lets call him Trent. Trent knows Alice, and Trent is known by Bob. If somehow Trent marks Alices public key to confirm its authenticity, Bob knows that Alice is who she claims she to be. In the context of signatures, Trent does this by signing Alices certificate. Bob can decrypt Alices signed certificate using Trents certificate, and as Bob trusts Trents public certificate, he can now also trust Alices certificate. See figure 39:

Figure 39: Bob trusts Alice, because he knows Trent and Trent trusts Alice

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

64

Did we reach those three goals? Not yet! By using the concepts of hashing and encryption, we can assure that a document hasnt been modified. Using the public/private key mechanism, we can authenticate the author and he cant deny the authorship, but so far, weve only been using selfsigned certificates (see section 1.3.3). Weve signed documents in the name of fictive personae named Alice, Bob, Carol, and Dave.

Digital Signatures for PDF documents 2012

The more people we want to exchange messages with, the more trusted people well need to involve. This is called a web of trust. In practice, its not very convenient to manage all these personal relationships. Usually Trent isnt an actual person, but a specialized, well-known organization: a certificate authority (CA). There are several commercial certificate authorities whose business it is to sell certificates. In one of the next examples, well learn how to sign a document using a key issued by GlobalSign 14, but first lets work with a private key from CACert15. NOTE: CAcert is a community effort that allows you to get a certificate for free. In order to get a certificate in your name, you need to accumulate sufficient points. You can earn points by meeting people in real life, showing them your drivers license or any other ID that proofs that you are who you claim you are. Ive registered at cacert.org, and Ive created a public and private key pair that is stored in a file named bruno.p12. Remember that the 12 refers to PKCS#12, the Public Key Cryptography Standard that defines the format of the key store. 3.1.1 Signing a document with a p12 file from a Certificate Authority Lets adapt the code from section 2.2.1 to sign a document with the CAcert key and make some changes resulting in code sample 34. Code sample 34: Signing using a CAcert certificate

public static final String SRC = "src/main/resources/hello.pdf"; public static final String DEST = "results/chapter3/hello_cacert.pdf"; public static void main(String[] args) throws IOException, GeneralSecurityException, DocumentException { Properties properties = new Properties(); properties.load(new FileInputStream("c:/home/blowagie/key.properties")); String path = properties.getProperty("PRIVATE"); char[] pass = properties.getProperty("PASSWORD").toCharArray(); BouncyCastleProvider provider = new BouncyCastleProvider(); Security.addProvider(provider); KeyStore ks = KeyStore.getInstance("pkcs12", provider.getName()); ks.load(new FileInputStream(path), pass); String alias = (String)ks.aliases().nextElement(); PrivateKey pk = (PrivateKey) ks.getKey(alias, pass); Certificate[] chain = ks.getCertificateChain(alias); SignWithCAcert app = new SignWithCAcert(); app.sign(SRC, DEST, chain, pk, DigestAlgorithms.SHA256, provider.getName(), CryptoStandard.CMS, "Test", "Ghent", null, null, null, 0); }

I dont want to publish my password in a white paper that can be read by anyone. So Ive stored it in a properties file that can be found in my home directory. If you want to run this example, youll have to change the path c:/home/blowagie/key.properties to a path that points to a file containing at least two properties: a path to a p12 file and a password. Observe that the sample code assumes that the key store password and the password for the private key are identical.
14 15

https://www.globalsign.com/ http://www.cacert.org/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

65

Digital Signatures for PDF documents 2012

We get an instance of the key store using two parameters: pkcs12, because our keys and certificates are stored using PKCS#12 .p12 file, and BC or provider.getName(); were using the BouncyCastleProvider.

If youd inspect the Certificate array named chain in code sample 34, youd discover that it contains two certificates instead of just one as was the case in code sample 11. You can check this by taking a look at Certificate Viewer for the signed PDF document as is done in figure 40.

Figure 40: Certificate Viewer showing more than one Certificate

Theres an important difference with what we saw in figure 10. The certificate is no longer selfsigned! There are two certificates shown in the Certificate viewer. Theres my own certificate (Bruno Lowagie) which is the signing certificate (always the first element in the chain), and theres the certificate of the CA Cert Signing Authority, the root certificate (the final element in the chain). The CA Cert Signing Authority is the Issuer of my certificate. 3.1.2 Trusting the root certificate of the Certificate Authority CA Certs root certificate corresponds with the private key that was used to sign all the public certificates that are issued to the members of the CA Cert Community. You can trust CA Certs root certificate in the PDF the way we did in section 2.2.2, or you can download that root certificate from the cacert.org site and add it as a trusted identity as we did in section 2.2.3. From now on, all the people who have a certificate issued by this CA will be trusted. You no longer have to trust each individual separately. This is shown in figures 41 and 42.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

66

Digital Signatures for PDF documents 2012

Figure 41: Individual signature not trusted, but Signers identity is valid

Figure 42: Signers identity is valid, because root certificate is trusted

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

67

Digital Signatures for PDF documents 2012

This answers the question: How can we be sure that the public key were using is really from the person we think its from? We make sure by relying on a trusted third party: a Certificate Authority. However, theres another question we should ask: What happens if a private key is compromised? Suppose that I discover that somebody stole my certificate, and is planning to sign documents pretending to be me. If that happens, I should immediately notify the Certificate Authority, and ask the CA to add my certificate to the Certificate Revocation List (CRL). Before we look at the concept of CRLs, lets update the sign() method we used in chapter 2. 3.1.3 Best practices in signing When we signed documents in chapter 2, we always passed three null values and one zero to the signDetached() method. Lets take a closer look at the sign() method we used in code sample 35. Its an updated version of the method we used before.

public void sign(String src, String dest, Certificate[] chain, PrivateKey pk, String digestAlgorithm, String provider, CryptoStandard subfilter, String reason, String location, Collection<CrlClient> crlList, OcspClient ocspClient, TSAClient tsaClient, int estimatedSize) throws GeneralSecurityException, IOException, DocumentException { // Creating the reader and the stamper PdfReader reader = new PdfReader(src); FileOutputStream os = new FileOutputStream(dest); PdfStamper stamper = PdfStamper.createSignature(reader, os, '\0'); // Creating the appearance PdfSignatureAppearance appearance = stamper.getSignatureAppearance(); appearance.setReason(reason); appearance.setLocation(location); appearance.setVisibleSignature(new Rectangle(36, 748, 144, 780), 1, "sig"); // Creating the signature ExternalSignature pks = new PrivateKeySignature(pk, digestAlgorithm, provider); ExternalDigest digest = new BouncyCastleDigest(); MakeSignature.signDetached(appearance, digest, pks, chain, crlList, ocspClient, tsaClient, estimatedSize, subfilter); }

In code sample 35, the hardcoded null values and the 0, are replaced by different objects: a Collection of CrlClients, an OcspClient and a TSAClient. Finally, theres also an estimatedSize value. Lets take a look at these objects one by one, starting with the ones regarding certificate revocation.

3.2 Adding Certificate Revocation information

There are different ways to prove that a certificate wasnt revoked at the moment it was signed. You can embed a Certificate Revocation List (CRL) into the PDF; you can specify an URL that can be used to check the revocation status of the certificate; or you can do both. 3.2.1 Finding the URL of a Certificate Revocation List There can be a Certificate Revocation List for each certificate in the chain. To find the lists we need, we have to loop over the chain as is done in code sample 36. We can use the getCRLURL() method from iTexts CertificateUtil convenience class to extract the CRL.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

68

Code sample 35: an updated sign() method

Digital Signatures for PDF documents 2012

Code sample 36: getting the CRL URLs from a certificate chain
BouncyCastleProvider provider = new BouncyCastleProvider(); Security.addProvider(provider); KeyStore ks = KeyStore.getInstance("pkcs12", provider.getName()); ks.load(new FileInputStream(path), pass.toCharArray()); String alias = (String)ks.aliases().nextElement(); Certificate[] chain = ks.getCertificateChain(alias); for (int i = 0; i < chain.length; i++) { X509Certificate cert = (X509Certificate)chain[i]; System.out.println(String.format("[%s] %s", i, cert.getSubjectDN())); System.out.println(CertificateUtil.getCRLURL(cert)); }

If I use this code on my CAcert certificate, I get the following result:

[0] CN=Bruno Lowagie,E=bruno@________.com null [1] O=Root CA,OU=http://www.cacert.org,CN=CA Cert Signing Authority,[email protected] https://www.cacert.org/revoke.crl

In this case, my signing certificate doesnt contain any CRL, but the root certificate does. iText offers different ways to use this information. 3.2.2 Getting the CRL online If you want to embed CRLs in a PDF, you need a Collection of CrlClient elements. Creating a CrlClientOnline instance is the easiest way to achieve this. See code sample 37. Code sample 37: Using the default CrlClient implementation

LoggerFactory.getInstance().setLogger(new SysoLogger()); List<CrlClient> crlList = new ArrayList<CrlClient>(); crlList.add(new CrlClientOnline()); SignWithCRLDefaultImp app = new SignWithCRLDefaultImp(); app.sign(SRC, DEST, chain, pk, DigestAlgorithms.SHA256, provider.getName(), CryptoStandard.CMS, "Test", "Ghent", crlList, null, null, 0);

The MakeSignature class will pass a single certificate to CrlClientOnline, starting with the signing certificate. As soon as the CrlClient finds one, iText will stop looking, and use that CRL. While this solution is easy and while it will work in many cases, it wont work for my CAcert certificate. Moreover, well soon discover its not the best solution in general. Trusting the root certificate in your Java Runtime Environment (JRE) Lets start by explaining why its doesnt work for a CAcert certificate. As you can see, the URL of the Certificate Revocation List uses https. Suppose that youve installed a JRE or JDK from scratch, and you want to run this example, youll hit the following error as soon as iText tries to fetch the C RL:
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException

When seeing this message, you should immediately understand that this is not an iText problem. It should also be clear that this isnt a programming error either. Its a matter of configuration. iText uses the java.net.URL class to create a connection to the https-server at cacert.org. Https means that SSL is used, and that the Java classes try to do an SSL Handshake. For this handshake to

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

69

Digital Signatures for PDF documents 2012

succeed, the Java Virtual Machine (JVM) needs to trust the certificate on the cacert.org server, and thats whats going wrong here: theres a validator exception. The certificate isnt recognized in your Java Runtime Environment and as a result your JVM doesnt trust it. You can solve this by downloading CAcerts root certificate and by adding it to the cacerts key store in the lib/security directory of your Java home directory. This is done in code sample 38: Code sample 38: importing a root certificate into the Java cacerts file
$ keytool -import -keystore cacerts -file CAcertSigningAuthority.crt -alias cacert Enter keystore password: Owner: [email protected], CN=CA Cert Signing Authority, OU=http://www.cacert.org, O=Root CA Issuer: [email protected], CN=CA Cert Signing Authority, OU=http://www.cacert.org, O=Root CA Serial number: 0 Valid from: Sun Mar 30 14:29:49 CEST 2003 until: Tue Mar 29 14:29:49 CEST 2033 Certificate fingerprints: MD5: A6:1B:37:5E:39:0D:9C:36:54:EE:BD:20:31:46:1F:6B SHA1: 13:5C:EC:36:F4:9C:B8:E9:3B:1A:B2:70:CD:80:88:46:76:CE:8F:33 Signature algorithm name: MD5withRSA Version: 3 Extensions: #1: ObjectId: 2.5.29.19 Criticality=true BasicConstraints:[ CA:true PathLen:2147483647 ] #2: ObjectId: 2.5.29.14 Criticality=false SubjectKeyIdentifier [ KeyIdentifier [ 0000: 16 B5 32 1B D4 C7 F3 E0 E6 8E F3 BD D2 B0 3A EE ..2...........:. 0010: B2 39 18 D1 .9.. ] ] #3: ObjectId: 2.16.840.1.113730.1.8 Criticality=false #4: ObjectId: 2.16.840.1.113730.1.4 Criticality=false #5: ObjectId: 2.5.29.31 Criticality=false CRLDistributionPoints [ [DistributionPoint: [URIName: https://www.cacert.org/revoke.crl] ]] #6: ObjectId: 2.5.29.35 Criticality=false AuthorityKeyIdentifier [ KeyIdentifier [ 0000: 16 B5 32 1B D4 C7 F3 E0 E6 8E F3 BD D2 B0 3A EE ..2...........:. 0010: B2 39 18 D1 .9.. ] [[email protected], CN=CA Cert Signing Authority, OU=http://www.ca cert.org, O=Root CA] SerialNumber: [ 00] ] #7: ObjectId: 2.16.840.1.113730.1.13 Criticality=false Trust this certificate? [no]: yes Certificate was added to keystore

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

70

Digital Signatures for PDF documents 2012

Remember that the initial password of the cacerts key store when you install a JRE or a JDK is always changeit. If that doesnt work, somebody has changed the password on purpose. Make sure youre updating the correct cacerts file. There can be more than one on your OS. When in doubt, use System.getProperty(java.home) to get the correct path, and check if you have the right permissions to change the file. I always forget to chmod, resulting in a keytool error: java.io.FileNotFoundException: cacerts (Access is denied). What if somebody changes the CRL URL? We overlooked one line in code sample 37. In the first line, we get an instance of iTexts LoggerFactory, and we define a SysoLogger instance as logger. A SysoLogger writes whatever logging information iText produces to the System.out. After we fixed the SSLHandshakeException by adding CAcerts root certificate to the cacerts key store of our JRE, we get the following logging information:

The MakeSignature class processes CrlClientOnline a first time for the first certificate. As it doesnt find an URL for the CRL, it moves to the next certificate and processes CrlClientOnline a second time. Now it finds this URL: https://www.cacert.org/revoke.crl which should be a valid URL, but when trying to fetch the CRL, the cacert.org server is returning status code 302, which means youre being redirected. iText doesnt trust this, and wont embed the CRL. How can we fix this? Creating a CrlClient using a specific URL If you go to the CAcert site, you see that there are two URLs to fetch the Certificate Revocation List, either http://crl.cacert.org/revoke.crl or https://crl.cacert.org/revoke.crl. You can create an instance of CrlClientOnline using either one. The former solves the SSL handshake problem; the latter solves the redirect problem if youve added CAcerts root certificate to your JREs cacerts file. Code sample 39: Creating a CRL list for a CAcert certificate
CrlClient crlClient = new CrlClientOnline("https://crl.cacert.org/revoke.crl"); List<CrlClient> crlList = new ArrayList<CrlClient>(); crlList.add(crlClient);

Code sample 39 example is added to show how to work around some problems inherent to certificates obtained from CAcert. Creating a CrlClient using the Certificate chain A better way to embed CRLs that are fetched online is shown in code sample 40.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

71

c.i.t.p.s.MakeSignature INFO Processing com.itextpdf.text.pdf.security.CrlClientOnline c.i.t.p.s.CrlClientOnline INFO Looking for CRL for certificate CN=Bruno Lowagie,E=bruno@_.com c.i.t.p.s.CrlClientOnline INFO Skipped CRL url: null c.i.t.p.s.MakeSignature INFO Processing com.itextpdf.text.pdf.security.CrlClientOnline c.i.t.p.s.CrlClientOnline INFO Looking for CRL for certificate O=Root CA, OU=http://www.cacert.org,CN=CA Cert Signing Authority,[email protected] c.i.t.p.s.CrlClientOnline INFO Found CRL url: https://www.cacert.org/revoke.crl c.i.t.p.s.CrlClientOnline INFO Checking CRL: https://www.cacert.org/revoke.crl c.i.t.p.s.CrlClientOnline INFO Skipped CRL: Invalid HTTP response: 302 for https://www.cacert.org/revoke.crl

Digital Signatures for PDF documents 2012

Code sample 40: Creating a CRL list for all the certificates in a chain
List<CrlClient> crlList = new ArrayList<CrlClient>(); crlList.add(new CrlClientOnline(chain));

This example is much better in general because you dont need to hardcode the URLs. iText will loop over every certificate in the chain as we did in sample 36, and will fetch every CRL it encounters, not just the first one. This is important because if you buy a certificate from an established CA, there will be more certificates in the chain, and youll want to embed the CRLs for each of those certificates. Now that we finally succeeded in embedding a CRL into a PDF, lets take a look at the certificate details in the Certificate Viewer. See figure 43.

Figure 43: Valid certificate because the CRL is embedded

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

72

Digital Signatures for PDF documents 2012

It reads The selected certificate is considered valid because it does not appear in the Certificate Revocation List (CRL) that is embedded in the signature. If you receive a file like this, youre now certain that the signer is who he claims he is, and youre also certain that the signers didnt revoke his certificate prior to signing the document: it wasnt on the CAs certificate revocation list at the moment the PDF was signed. As for the root certificate, thats either a trust anchor or a certificate above the trust anchor in the certificate chain. See figure 44. Remember that the root certificate is the certificate from CAcert that we added to the Trusted Identities manually.

Figure 44: No CRL checking for the trusted root certificate

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

73

Digital Signatures for PDF documents 2012

If you fetch the CRL from an URL, you always have the most recent certification revocation list. Thats a good thing, but it isnt very practical if youre about to sign a thousand documents. Opening a connection for every separate document, downloading the same bytes over and over again, isnt such a good idea. Thats why we also have a CrlClient implementation that allows you to use an offline copy of the CRL. 3.2.3 Creating a CrlClient using an offline copy of the CRL Now that we know how to find the URL of a certificate revocation list, we can also use it in a browser to download the CRL to our hard disk. Or even better, we can write a cron job or a service that automatically downloads the CRL on a regular basis. Figure 45 shows what you see if you double-click a CRL file.

Figure 45: A CAcert Certificate Revocation List Instead of downloading the list from our code, we can now create a CrlClientOffline object. This object has two constructors. One that accepts a byte[] and one that accepts a CRL object. Code sample 41: Creating an offline CrlClient
FileInputStream is = new FileInputStream(CRL); ByteArrayOutputStream baos = new ByteArrayOutputStream(); byte[] buf = new byte[1024]; while (is.read(buf) != -1) baos.write(buf); CrlClient crlClient = new CrlClientOffline(baos.toByteArray()); List<CrlClient> crlList = new ArrayList<CrlClient>(); crlList.add(crlClient);

In code sample 41, we read a FileInputStream into a ByteArrayOutputStream and we use those bytes to create a CrlClientOffline object. In case youre curious how to create a CRL object from a file, see code sample 42.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

74

Digital Signatures for PDF documents 2012

Code sample 42: Creating a CRL object from a file
CertificateFactory cf = CertificateFactory.getInstance("X.509"); CRL crl = (CRL)cf.generateCRL(new FileInputStream(CRL));

You can use this CRL object instead of the byte[] to create a CrlClientOffline. WARNING: A downloaded CRL is valid for only a limited period. It usually expires after seven days. If it didnt expire, one could first download a CRL, then steal a cer tificate, then sign a document using the stolen certificate. As a matter of fact, this is always possible if the signature is applied within the expiration period. Thats why its good practice to cache a CRL only for a limited period. A CA normally updates its CRLs every 30 minutes. If possible, you should create a caching system that downloads a new CRL every half hour. Finally, you may have noticed one of the major downsides of embedding CRLs: the file size can get really big if the Certificate Authority doesnt really bother about the size of the CRL ( which is the case with CAcert). Later on in this chapter, well see how GlobalSign solves this problem. We can solve the problem ourselves by using the Online Certificate Status Protocol (OCSP) instead of CRLs. 3.2.4 Using the Online Certificate Status Protocol (OCSP) OCSP is an internet protocol for obtaining the revocation status of a certificate online. You can post a request to check the status of a certificate over http, and the CAs OCSP server will se nd you a response. You no longer need to parse and embed long CRLs. An OCSP response is small and constant in size, and it can be easily embedded in a digital signature. Use code sample 43 if you want to know if your certificate supports OCSP: Code sample 43: fetching the OCSP URL from a certificate
BouncyCastleProvider provider = new BouncyCastleProvider(); Security.addProvider(provider); KeyStore ks = KeyStore.getInstance("pkcs12", provider.getName()); ks.load(new FileInputStream(path), pass.toCharArray()); String alias = (String)ks.aliases().nextElement(); Certificate[] chain = ks.getCertificateChain(alias); for (int i = 0; i < chain.length; i++) { X509Certificate cert = (X509Certificate)chain[i]; System.out.println(String.format("[%s] %s", i, cert.getSubjectDN())); System.out.println(CertificateUtil.getOCSPURL(cert)); }

When I use this code on my CAcert certificate, I get the following output:
[0] CN=Bruno Lowagie,E=bruno@______.com http://ocsp.cacert.org [1] O=Root CA,OU=http://www.cacert.org,CN=CA Cert Signing Authority,[email protected] null

When signing a document, iText needs a way to send a post to the url http://ocsp.cacert.org, and to receive a response regarding the validity of my certificate. This is done by an implementation of the OcspClient interface, for instance iTexts OcspClientBouncyCastle class that uses the Bouncy Castle library. Code sample 44: Signing with OCSP
OcspClient ocspClient = new OcspClientBouncyCastle(); SignWithOCSP app = new SignWithOCSP();

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

75

Digital Signatures for PDF documents 2012

app.sign(pk, chain, SRC, DEST, provider.getName(), "Test", "Ghent", DigestAlgorithms.SHA256, CryptoStandard.CMS, null, ocspClient, null, 0);

If you look at code sample 44, youll see that we dont need to pass any URL or certificate; iText will pass the certificate with the OCSP URL to the OcspClient implementation. Lets take a look at the Certificate Viewer of the resulting PDF. Figure 46 demonstrates that the selected certificate is considered valid because it has not been revoked as verified using the Online Certificate Status Protocol (OCSP) response that was embedded in the signature.

Figure 46: A digital signature with an embedded OCSP response Its important to understand that the choice between using CRLs and using OCSP isnt an or this, or that question. For the sake of the consumer of the signed document, its always best to use both because that offers more certainty than using only one type of certificate revocation checking.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

76

Digital Signatures for PDF documents 2012

NOTE: Adobe Acrobat / Reader 8 had a preference for OCSP and would always do an OCSP lookup if there wasnt any embedded OCSP response. If it couldnt make a connection to the internet, it looked at the embedded CRLs (if any). Adobe Acrobat / Reader 9 and X however, have a preference for CRLs. They look for the CRL first, and if it isnt found, theyll fall back on OCSP. In many cases, especially when using software certificates like the one from CAcert, using OCSP is the better solution, but thats not a general rule. Theres always a tradeoff. 3.2.5 Which is better: embedding CRLs or an OCSP response? Three aspects are important when comparing embedding CRLs with embedding an OCSP response: the file size of the signed document, the performance when creating the signature, and the law. Comparing the file size If you compare the file size of a file that has CAcerts CRL embedded to the same file signed with the OCSP information from CAcert, youll see that the difference is huge. The one with the CRL is almost 10 MByte, the one with the OCSP is only 28 Kbyte. Rest assure: the difference isnt always this terrifying. It all depends on the CA youve chosen. Some certificate authorities (such as CAcert) keep the revocation information of all their certificates in only one file; others dont maintain their revocation list: for instance, they dont remove certificates from the list that have expired anyway. NOTE: A CA that cares about the file size of the CRLs, will create a hierarchy of certificates, splitting regular certificates, USB tokens and Hardware Security Modules (HSM) to keep the CRLs small. For instance, you cant extract the private key from an HSM, and stealing an HSM is rather impractical, so a CRL used only for HSM certificates can be kept small. Embedding the CRL of a HSM could result in smaller files than when using OCSP. Conclusion: you should choose your CA wisely if you need to embed CRLs into your documents. Differences in performance Even when the CRLs are bigger than the OCSP response, the larger file size may be an acceptable cost for improved performance. In the context of ISO-32000-1 and PAdES 2, revocation information is a signed attribute in a PDF document, which implies that the signing software (in this case iText) must capture the revocation information before signing. The OCSP connection to check the status can take time, whereas using CRLs that are cached on the file system can save a significant amount of time when you need to sign thousands of documents in batch. Legal requirements In some countries, not only non-revocation of the certificate, but also existence has to be proven when verifying qualified signatures. In Germany for instance, embedding a Certificate Revocation List wont be sufficient, because not appearing on the CRL doesnt mean the certificate actually exists. Now lets look at another problem that might arise. Suppose somebody has a CRL that dates from a year ago. He now wants to predate a document by signing it with signature that says the document was signed a year ago. He could do so by changing the clock on his computer. The only way we can prevent this from happening, is to demand that every signed document has a timestamp obtained from a Time Stamping Authority (TSA).

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

77

Digital Signatures for PDF documents 2012

3.3 Adding a timestamp
Before we jump into an example, lets try to understand why its important to know when a document was signed. We already know that certificates can be revoked, but certificates also have an expiration date. What happens if a certificate expires? 3.3.1 Dealing with expiration and revocation dates Suppose that Alice has acquired a private key with a certificate that is valid until 2014. As long as the expiration date hasnt passed, Alice can sign documents and these documents wil l be validated by Adobe Reader. After the expiration date, Alice can no longer use her private key to sign documents (which is to be expected), but theres more! Adobe Reader will inspect the certificate and see that it has expired. If theres no embedded CRL, no embedded OCSP response, and no timestamp, Adobe Reader wont show a green check mark anymore, but it will give a warning saying: I cant trust this signature anymore because the expiration date is in the past. See figure 47.

Figure 47: Alice signs a document without CRL and without timestamp

It gets even worse if the certificate is revoked. This doesnt always mean that Alices key was stolen. Its also possible that Alice has left the company she used to work for. She had a key she could use to sign company documents until 2014, but if she leaves the company in 2013, the company will most probably want to revoke that key. Figure 48 shows the consequences if that ever happens:

Figure 48: Alice leaves the company in 2013, her key is revoked

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

78

Digital Signatures for PDF documents 2012

Apart from the fact that Alice can no longer sign documents from 2013 on, all signatures she created before that date can no longer be trusted if no CRL, OCSP response or timestamp was added. Theres no way for the consumer of the document to verify if the document is valid. The certificate was revoked, and theres no certainty about the date the document was signed. After all, Alice could have changed the clock on her computer. What we need, is a situation as shown in figure 49:

Figure 49: Alice leaves the company; all documents she signed in the past remain valid Can we achieve this merely by adding a CRL or an OCSP response? No, because Alice could have cached the information about the certificate revocation before leaving the company. The only way we can assure that a document remains valid, is by also adding a timestamp. A document that was signed by Alice in 2012 will contain revocation information dating from 2012 saying that her certificate wasnt revoked at that time; the timestamp will assure that the document was certainly signed in 2012. This signature will survive the revocation and expiration date. But how do we add a timestamp to a digital signature in a PDF document? 3.3.2 Connecting to a timestamp server To solve this problem, we need to involve another third party: a Time Stamping Authority (TSA). A TSA provides an online service, accepting a message digest and concatenating a timestamp to it. This is done on a timestamp server that is contacted during the signing process. The timestamp server will return a hash that is signed using the private key of the TSA. NOTE: You need to be online to create a signature with a timestamp. Connecting to a timestamp server sending and receiving the hash takes time. If you need to sign thousands of documents in batch, you could ask the TSA to provide a time stamping certificate. This certificate will usually be stored on a Hardware Security Module. With code sample 45, we try to find out if CAcert also offers timestamping services. Code sample 45: Extracting the TSA URL from a certificate
BouncyCastleProvider provider = new BouncyCastleProvider(); Security.addProvider(provider); KeyStore ks = KeyStore.getInstance("pkcs12", provider.getName()); ks.load(new FileInputStream(path), pass.toCharArray()); String alias = (String)ks.aliases().nextElement();

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

79

Digital Signatures for PDF documents 2012

Certificate[] chain = ks.getCertificateChain(alias); for (int i = 0; i < chain.length; i++) { X509Certificate cert = (X509Certificate)chain[i]; System.out.println(String.format("[%s] %s", i, cert.getSubjectDN())); System.out.println(CertificateUtil.getTSAURL(cert)); }

This code returns null for both certificates, meaning CAcert probably doesnt offer any TSA services. Checking their web site confirms this. Fortunately, I received an account for a timestamp server at GlobalSign. For some accounts you need an URL, a username and a password. In that case, you can create a TSAClient instance as is done in code sample 46. Observe that were again using an implementation that uses the Bouncy Castle library, just like we did for the OcspClient. Code sample 46: Creating a TSAClient Sometimes you only need an URL containing a token identifying the user. In this case you can drop the parameters tsaUser and tsaPass. Theres also a constructor that accepts an estimated size and a digest algorithm. Well learn more about the estimated size in the final section of this chapter. How to recognize a document that has a timestamp Lets take a look at the result. In figure 50, weve opened the document, and were looking at the Date/Time information in the Signature properties. Weve also opened the Certificate viewer for the timestamp certificate.

Figure 50: Looking at the timestamp info

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

80

TSAClient tsaClient = new TSAClientBouncyCastle(tsaUrl, tsaUser, tsaPass);

Digital Signatures for PDF documents 2012

Instead of saying Signing time is from the clock on the signers computer as was the case with all previous documents we signed, we can now read The signature includes an embedded timestamp along with the exact time the document was signed and the certificate of the TSA, in this case the SEIKO Timestamp Service. Advanced A02-004 from GlobalSign. Retrieving TSA information during the time stamping process We can follow the signing process, by adding a Logger instance to the LoggerFactory. We can see which CRLs iText is fetching. iText will also send a message to the Logger when a document gets its timestamp, but we may want to store that info somewhere. For instance: we may want to store the exact time returned from the TSA in a database. Lets take a look at code sample 47: Code sample 47: Adding an event to a TSAClientBouncyCastle instance
TSAClientBouncyCastle tsaClient = new TSAClientBouncyCastle(tsaUrl, tsaUser, tsaPass); tsaClient.setTSAInfo( new TSAInfoBouncyCastle() { public void inspectTimeStampTokenInfo(TimeStampTokenInfo info) { System.out.println(info.getGenTime()); } } );

In this example, we implement the TSAInfoBouncyCastle interface. As soon as iText receives a response from a TSA, it will trigger the inspectTimeStampTokenInfo() method. In this case, we write the generation time (a Date object) to the System.out. Check out the API of Bouncy Castles TimeStampTokenInfo class, and youll discover that theres much more information you can retrieve. Instead of just writing this info to a console, you could easily pass it to other objects to create your own logs in the form of a file or records in a database. Weve finally created a PDF document that complies with the best practices. Theres only one thing that still bothers us: why do we have to add the root certificate of the CA to the Trusted Identities manually? Why cant Adobe Reader show a green check mark now that weve followed the rules by the book? Arent there easier ways to trust root certificates?

3.4 How to get a green check mark

One of the most Frequently Asked Questions by iText customers sounds like this: We have signed a document correctly, and it shows a green check mark when we open it on our machines, but our end users complain that they get a message saying that the validity of the signer is unknown. How can we avoid this? The answer they dont like to hear is: You have to ask the end users to trust the root certificate of the Certificate Authority. They dont like this answer because there are far too many unknown and dangerous words in one and the same sentence. When you break up the sentence and provide a tutorial similar to what we discussed in section 2.2.3, they dont like the answer because There are too many difficult steps in that tutorial. Fortunately, there are several other options.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

81

Digital Signatures for PDF documents 2012

3.4.1 Trust certificates stored elsewhere A lot of software ships with a root store (for instance the cacerts file of the JDK), a lot of hardware ships with a root store (for instance: each smartphone has a root store). These root stores contain the root certificates of all the major CAs: GlobalSign, VeriSign, Entrust, and others. Theres also a root store in Acrobat/Reader, but by default, it only contains the Adobes root certificate. As a result only signatures with this certificate in the root of the certificate chain get a green check mark automatically, but you can change Adobe Readers security settings. Using the Windows Certificate Store Chances are the root certificate of that CA is already shipped with your Windows OS, or youve already added it to your Windows Certificate Store for other purposes. You dont need to a dd and trust each of the certificates that are already present in the Windows Certificate Store manually. Instead, you can configure Adobe reader to search the operating systems certificate store when verifying signatures. By default, this option is turned off. Go to Edit > Preferences > Security > Advanced Preferences and youll see the dialog shown in figure 51. Just checkmark the options Enable searching the Windows Certificate Store for the following operations , choose which operations you approve, and youre all set.

Figure 51: Changing the Security settings regarding certificates Of course, this will only work for specific root certificates that are known on the level of the OS. You can also see another option in figure 51: you can also load the Security settings from a server. In this case, a companys Sysadmin will have a tool to manage root certificates, and he can distribute a list of trusted certificates among the employees of the company.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

82

Digital Signatures for PDF documents 2012

This is also what Adobe does with its Approved Trust List. 3.4.2 Adobe Approved Trust List (AATL) If the end user is outside the zone of your influence, the previous solutions wont work: you dont know which certificates he has in his certificate store, nor can you make him connect to a server. Thats why Adobe introduced the Adobe Approved Trust List, a certificate trust program introduced with Adobe Reader 916. Recent versions of Acrobat and Reader have been programmed to reach out to a web page to periodically download a list of trusted "root" digital certificates. QUOTE: Certificate authorities (CAs) as well as governments and businesses that provide certificates to their citizens and employees can apply to Adobe to join the AATL program by submitting application materials and their root certificates (or another qualifying certificate). After verifying that the applicant's services and credentials meet the assurance levels imposed by the AATL technical requirements, Adobe adds the certificate(s) to the Trust List itself, digitally signs the Trust List with an Adobe corporate digital ID that is linked to the Adobe Root certificate embedded in Adobe products, and then posts the list to a website hosted by Adobe. Any digital signature created using a certificate that chains up to one of the high-assurance, trustworthy certificates on the list, is trusted automatically by Acrobat / Reader versions 9 and X. So if you buy a certificate, ask your CA if hes a partner in the AATL program, or check the list on the Adobe website17. But what if you also have to support version 8? Adobe has stopped support for Acrobat 8 in 201118, but there are still people out there with Adobe Reader 8. Should you ask them to upgrade? Yes, most certainly! Can you force them to upgrade? Probably not, so if you really need to support Reader 8, you need to use the predecessor of AATL: Adobe Certified Document Services. Adobe Certified Document Services (CDS). The Adobe Certified Document Services (CDS) system was introduced in 2005. With CDS, the signing certificate is chained up to the Adobe root certificate. This certificate from Adobe is inherently trusted by Adobe Reader (including versions 9 and X). This way, CDS certified documents are validated without any action required by the user. Adobe wanted to make sure that certificates signed with its root certificate are as safe as possible. A CA who wanted to issue certificates signed with Adobes root certificate, needed to be a partner in the Adobes CDS program.19 He had to be Web-Trust Certified, and follow Adobes certificate policy. This policy discussed topics such as: How are certificates issued? How are they created? How are they validated? For example, it wasnt allowed for a CA to issue a software certificate because these certificates can easily be compromised: computers can be hacked and keys can be copied without anybody knowing the key was stolen.

16 17

http://www.adobe.com/security/approved-trust-list.html http://helpx.adobe.com/acrobat/kb/approved-trust-list1.html 18 http://blogs.adobe.com/adobereader/2011/09/adobe-reader-and-acrobat-version-8-end-of-support.html 19 http://www.adobe.com/security/partners_cds.html

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

83

Digital Signatures for PDF documents 2012

QUOTE: Subscriber key pairs must be generated in a manner that ensures that the private key is not known by anybody other than the Subscriber or a Subscribers authorized representative. Subscriber key pairs must be generated in a medium that prevents exportation or duplication and that meets or exceed FIPS 140-1 Level 220 certification standards. This program has been discontinued by Adobe, but a small number of vendors that were licensed to issue CDS certificates can still offer CDS certificates. They are protected by a Hardware Security Module (HSM; see figure 52) or an USB token (see figure 53).

Figure 52: a Hardware Security Module (HSM) from SafeNet

A key store on a hardware device can be used to create a signature, but the private key cant be extracted. This means that we can no longer create a KeyStore object by passing an InputStream as we did in all the previous examples. What do we need to do instead? Lets start with an example that uses the Windows Certificate Store to get access to an USB token. 3.4.3 Signing a document using a USB token (part 1: MSCAPI) For this example, well use an iKey 4000 from SafeNet 21 (see figure 53).

Figure 53: an iKey 4000 from SafeNet

20 21

http://csrc.nist.gov/publications/fips/fips1401.htm#sec1.2 http://www.safenet-inc.com/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

84

Digital Signatures for PDF documents 2012

SafeNet only provides Windows drivers for this type of key, so well only be able to sign documents on a Windows machine. Check out the companys web site if you need a key that also works on other OSs. Merely the iKey 4000 isnt enough for signing. We also need to put a private key on the USB token. Im using a certificate issued by GlobalSign. In this white paper, were using a certificate-based USB token for signing, but they can also be used for other purposes, such as authentication. You can use them to enable secure access, network logon, and so on. 22 Inspecting the Certificates available on Windows After I install the Windows drivers for the iKey 4000, my OS detects the USB token as soon as I plug it into a USB port. I can look for my certificate by opening the list of certificates available on my Windows installation. In figure 54, I used MS Internet Explorer > Internet Options > Content to get this information.

Figure 54: Internet Options > Content > Certificates

22

http://www.safenet-inc.com/data-protection/authentication/pki-authentication/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

85

Digital Signatures for PDF documents 2012

My GlobalSign certificate is present in my Windows-MY key store as long as I dont remove the USB token from my machine. I can address it through the Microsoft CryptoAPI (MSCAPI). Signing a document using MSCAPI When using Java, I need the SunMSCAPI provider, a class in the sun.security.mscapi package. Im working on Windows 7, and as I was using the 64 -bit version of Java 6, I had to upgrade to Java 7 because the SunMSCAPI provider wasnt available in the 64-bit version of Java 6. NOTE: if you need to upgrade to make this example work on your OS, you may want to avoid the 64-bit version of Java 7, and opt for the 32-bit version. The SunPKCS11 provider is missing in the 64-bit version of Java 6 as well as Java 7. Well need that provider in the next chapter. Theres no ETA as to when Oracle will fix this problem. Well still use Bouncy Castle for dealing with the timestamp and doing the hashing, but well need to use the SunMSCAPI class as the provider for signing. If you use the Bouncy Castle provider, youll get a Supplied key (sun.security.mscapi.RSAPrivateKey) is not a RSAPrivateKey instance exception. In code sample 48, Im explicitly adding an instance of SunMSCAPI. This isnt really necessary; that is: with the correct JDK it isnt. Im adding it to make really sure the class is present in my JVM. Ill get a compile error if I try compiling the code using the 64-bit version of Java 6. Code sample 48: Signing with a USB token using MSCAPI
public static void main(String[] args) throws IOException, GeneralSecurityException, DocumentException { LoggerFactory.getInstance().setLogger(new SysoLogger()); BouncyCastleProvider providerBC = new BouncyCastleProvider(); Security.addProvider(providerBC); SunMSCAPI providerMSCAPI = new SunMSCAPI(); Security.addProvider(providerMSCAPI); KeyStore ks = KeyStore.getInstance("Windows-MY"); ks.load(null, null); String alias = (String)ks.aliases().nextElement(); PrivateKey pk = (PrivateKey)ks.getKey(alias, null); Certificate[] chain = ks.getCertificateChain(alias); OcspClient ocspClient = new OcspClientBouncyCastle(); TSAClient tsaClient = null; for (int i = 0; i < chain.length; i++) { X509Certificate cert = (X509Certificate)chain[i]; String tsaUrl = CertificateUtil.getTSAURL(cert); if (tsaUrl != null) { tsaClient = new TSAClientBouncyCastle(tsaUrl); break; } } List<CrlClient> crlList = new ArrayList<CrlClient>(); crlList.add(new CrlClientOnline(chain)); SignWithToken app = new SignWithToken(); app.sign(SRC, DEST, chain, pk, DigestAlgorithms.SHA256, providerMSCAPI.getName(), CryptoStandard.CMS, "Test", "Ghent", crlList, ocspClient, tsaClient, 0); }

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

86

Digital Signatures for PDF documents 2012

Observe that were now creating a Keystore instance using the parameter Windows-MY. We load the KeyStore without passing an InputStream or a password. We just use null. The same goes for the password for the PrivateKey object. All the signing operations are passed to the Microsoft CryptoAPI. As soon as the MakeSignature class wants to use the PrivateKey instance to create the signature, the MS CryptoAPI will address the device and its drivers. A dialog box will be opened (see figure 55), and as soon as I provide the correct passphrase the message digest will be sent to the device where it will be signed.

Figure 55: Password dialog for the iKey 4000

This is the first example where the actual signing is nt done on the JVM, but externally, on a separate device. Well see some more examples in chapter 4 dedicated entirely to this type of signatures. Inspecting the Certificate chain When I open the resulting PDF, it is validated automatically. I immediately have a green check mark; I dont need to trust a certificate from a CA manually. Lets take a look at the Certificate Viewer shown in fi gure 56 to find out why.

Figure 56: The Certificate Viewer showing the Adobe Root CA Certificate

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

87

Digital Signatures for PDF documents 2012

We see that the certificate chain now has four entries. The signing certificate is my own. It was signed by a GlobalSign SHA256 CA for Adobe certificate. That certificate was in turn signed by a GlobalSign Primary SHA256 CA for Adobe certificate. At the top-level, theres the Adobe Root CA certificate. GlobalSign is a partner in Adobes Certified Document Services program, and they are allowed to issue certificates with Adobes root certificate. The presence of this certificate explains why I didnt need to add GlobalSigns root certificate one way or another to get a green check mark. This would be a good time for you to ask why GlobalSign added two extr a certificates in the chain. Id answer that we already discussed this in section 3.2. When talking about CRLs, I made a remark that good CAs do extra efforts to keep their CRLs as small as possible. Using intermediate certificates helps them to achieve this goal. Introducing intermediate certificates On figure 57, you can see that GlobalSign has an intermediate certificate GlobalSign Primary SHA256 CA for Adobe, used to issue certificates for Hardware Security Modules (HSM).

Figure 57: The Adobe Root CA, the intermediate GlobalSign and the end-user certificates Also using its Primary certificate, GlobalSign issued another intermediate certificate GlobalSign SHA256 CA for Adobe. With this certificate, they issue end user certificates for USB tokens. We already saw these certificate in figure 56 when we looked at the certificate chain in the document we signed with the iKey 4000.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

88

Digital Signatures for PDF documents 2012

Why the need for an extra intermediate certificate? As you saw in figure 55, I have to enter my passphrase when I use my USB token. If I enter the wrong password a couple of times, my private key will be wiped from the device, and Ill have to revoke it. Also: a USB token can easily be lost or stolen, in which case Ill also have to revoke it. If all USB tokens would be issued im mediately under the Adobe Root certificate, the CRL for the Adobe Root would be huge. By building in intermediate levels, the respective CRLs can be kept small. NOTE: Its less trivial to lose or steal an HSM from a server rack. Certificates stored on an HSM arent very likely to be revoked. Thats why theres no need for more than one level between the certificate on the HSM and the Adobe Root certificate. In the next chapter, well create some more signatures on hardware, even on a smart card, but theres one more parameter in the signing process we should discuss before we can close this chapter.

3.5 Estimating the size of the signature content

Do you remember when we first looked at the concept of a digitally signed PDF document? In figure 6, I drew a schema of a document with content in blue and a signature in light red. I explained that iText either keeps the blue bytes in memory, or stores them in a temporary file (section 2.2.4) reserving a hole that can only be filled once the blue bytes are hashed and signed. How does iText know in advance which size the signature will have? How does it determine the size of the hole? The answer is: iText doesnt know. iText makes an educated guess. Theres a parameter named estimatedSize in code sample 35. Up until now, weve always passed 0 as its value. In this case, iText will start with a value of 8192 bytes. It will add the number of bytes of the CRLs, and an extra 10 bytes for every CRL. 4192 bytes will be added if you defined an OcspClient, another 4192 if you created a TSAClient (unless youve defined another size in the class that implements the time stamping interface). Normally, this educated guess creates a hole that is too big. If you look inside the PDF, youll see plenty of zeros at the end of the sig nature bytes. So be it. Its better to provide too much space, than not enough. Suppose you have an algorithm can make a better estimation that is lower than iTexts guess. In that case, you can pass your estimated size to the MakeSignature class. In the case of code sample 49, iText would reserve 16,579 bytes: 8,192 (the minimum guess) + 4,192 (for the OCSP) + 4,192 (for the TSA). But lets start with an estimated size of 13,000, and see what happens. If 13,000 bytes arent enough, well add another 50, and well keep doing so until the signature fits. Code sample 49: Making a hit-and-miss estimation of the signature size
boolean succeeded = false; int estimatedSize = 10300; while (!succeeded) { try { System.out.println("Attempt: " + estimatedSize + " bytes"); app.sign(SRC, DEST, chain, pk, DigestAlgorithms.SHA256, provider.getName(), CryptoStandard.CMS, "Test", "Ghent", null, ocspClient, tsaClient, estimatedSize); succeeded = true; System.out.println("Succeeded!");

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

89

Digital Signatures for PDF documents 2012

} catch(IOException ioe) { System.out.println("Not succeeded: " + ioe.getMessage()); estimatedSize += 50; } }

Lets take a look at the result:

Attempt: 10300 Not succeeded: Attempt: 10350 Not succeeded: Attempt: 10400 Succeeded! bytes Not enough space bytes Not enough space bytes

3.6 Summary

In this chapter, weve learned about the best practices for signing PDF documents. First we were introduced to certificate authorities. We found out that they act as trusted entities that issue certificates to end users. One could argue that all the signatures we created in the previous chapter were useless and of no value: they didnt contain any certificate revocation information, nor did they have a timestamp. We experimented with different ways to embed certificate revocation information into a PDF: we worked with online and offline Certificate Revocation Lists and we used the Online Certificate Status Protocol. Then we discovered the need for a Time Stamping Authority, and we connected to a timestamp server. All of this didnt automatically result in a PDF that showed us a green check mark automatically, but then we created a document that was signed using an USB token and a signing certificate that was chained up to the Adobe root. Finally, we created a small example that explained why documents that are signed using iText are slightly bigger than strictly necessary. In the next chapter, well start by rewriting the example with the iKey 4000, only now, we wont depend on the Microsoft CryptoAPI, but well use PKCS#11.

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

90

The actual size of the signature was somewhere between 10,350 and 10,400 bytes. This means that iText reserved at least 6,176 bytes that werent necessary for the signature. Is that a h igh price to avoid an IOException? Maybe, but I dont think so. In some situations, you have to enter a PIN for each signing operation. You dont want to repeat that action for each try. Some smart cards take more than a second to create a signature. In our hit-and-miss example, weve made three connections to a timestamp server. Is that acceptable? Does that cost more than having a file with 6 extra Kbytes? Maybe, maybe not; its up to you to make a choice.

Digital Signatures for PDF documents 2012

4 Creating signatures externally
In the previous chapter, weve created one document that wasnt signed in the JVM of the machine were iText was running. The signature was created on an external device. In this chapter, well look at some other situations where we can use a private key for signing, but we dont have direct access to a file or a service from which we can export the private key. Well start with some PKCS#11 examples, and then study a smart card solution. Well finish by discussing different client/server architectures.

4.1 Signing a document using PKCS#11

The example we discussed in the previous chapter only worked on Windows because we were relying on the Windows Certificate Store. Cant we change the example so that it also works on other OSs? Another disadvantage of that MSCAPI example was that the signer had to enter his password every time he wanted to sign a document. That may be a requirement when youre at a notary signing an important document you dont want to enter your PIN and discover youve signed more documents than you intended to, but it isnt an ideal situation in the context where youre signing documents in batch on a server. 4.1.1 Signing a document using an HSM Suppose that your company needs to send out a huge amount of signed documents. You could choose a human being responsible for signing the document, and have him use a company certificate to sign each document one by one. Thats madness of course. Imagine the CEO of a company with thousands of customers having to sign each contract manually one by one. Typically youll want an automated solution. Youll want to sign those documents on a server, using the companies HSM. In that case, I have good news for you: you dont need a single thing to the sign() method weve used before! You can copy and paste code sample 35, and half of your work is done. Just like when we used MSCAPI, you just need to adapt the rest of your code to use another provider. Code sample 50: Signing a document using PKCS#11

LoggerFactory.getInstance().setLogger(new SysoLogger());

Properties properties = new Properties(); properties.load(new FileInputStream(PROPS)); char[] pass = properties.getProperty("PASSWORD").toCharArray(); String pkcs11cfg = properties.getProperty("PKCS11CFG"); BouncyCastleProvider providerBC = new BouncyCastleProvider(); Security.addProvider(providerBC); FileInputStream fis = new FileInputStream(pkcs11cfg); Provider providerPKCS11 = new SunPKCS11(fis); Security.addProvider(providerPKCS11); KeyStore ks = KeyStore.getInstance("PKCS11"); ks.load(null, pass); String alias = (String)ks.aliases().nextElement(); PrivateKey pk = (PrivateKey)ks.getKey(alias, pass); Certificate[] chain = ks.getCertificateChain(alias); OcspClient ocspClient = new OcspClientBouncyCastle(); TSAClient tsaClient = null;

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

91

Digital Signatures for PDF documents 2012

for (int i = 0; i < chain.length; i++) { X509Certificate cert = (X509Certificate)chain[i]; String tsaUrl = CertificateUtil.getTSAURL(cert); if (tsaUrl != null) { tsaClient = new TSAClientBouncyCastle(tsaUrl); break; } } List<CrlClient> crlList = new ArrayList<CrlClient>(); crlList.add(new CrlClientOnline(chain)); SignWithPKCS11HSM app = new SignWithPKCS11HSM(); app.sign(SRC, DEST, chain, pk, DigestAlgorithms.SHA256, providerPKCS11.getName(), CryptoStandard.CMS, "HSM test", "Ghent", crlList, ocspClient, tsaClient, 0);

Its not really necessary to create a Logger, but it helps you to see what happens during the signing process. The first difference is that we dont load a key store file and a password, but a configuration file and a password. In my case, the content of the configuration file looks like this:
Name = Luna library = /usr/lunasa/lib/libCryptoki2_64.so slot = 1

Im working on a Luna SA from SafeNet23. Its connected to a Linux machine, hence the name and the reference to an Executable and Linkable Format (ELF) file. The HSM itself is installed in a slot inside the Luna SA. In my case, I use slot 1. Again well add the Bouncy Castle provider because we rely on it for the time stamp, and we reuse the sign() method that uses Bouncy Castle to create the digest of the PDF bytes, but now we also create an instance of a SunPKCS11 provider by passing an InputStream that allows it to read the configuration file. In our case, the name of the provider will be SunPKCS11-Luna. Now we create a PKCS11 KeyStore using the parameter PKCS11, and we load it using the password for the HSM. From that moment on, all the code is almost identical to what we had before. The only change you need to make is the provider used for signing. You can still use the PrivateKeySignature class, but dont forget that it now expects SunPKCS11-Luna instead of BC. Now that was easy, wasnt it? Theres only one difficulty about it: What to put in the configuration file? That depends. Ask the vendor of the device and hell help you out. Or lets try another example ourselves. 4.1.2 Signing a document using a USB token (part 2: PKCS#11) We could easily reuse the source from code sample 50 and use it to sign a document on Windows with our iKey 4000. The only difference would be the configuration file. I can pick any name; I now need a DLL instead of an ELF; and then we face the tricky part: which slot do I use? Lets create the configuration file dynamically as is done in code sample 51. Code sample 51: creating a configuration file dynamically
String config = "name=ikey4000\n" + "library=c:/windows/system32/dkck201.dll\n" +

23

http://www.safenet-inc.com/products/data-protection/hardware-security-modules/luna-sa/

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

92

Digital Signatures for PDF documents 2012

"slotListIndex = " + getSlotsWithTokens()[0]; ByteArrayInputStream bais = new ByteArrayInputStream(config.getBytes()); Provider providerPKCS11 = new SunPKCS11(bais); Security.addProvider(providerPKCS11);

Ive chosen the name ikey4000 (but you can use another name if that pleases you more). Ive added the path to the CRYPTOKI (PKCS#11) DLL on my Windows machine, and then I call a method I named getSlotsWithTokens(). You can find the code for this method in code sample 52. Code sample 52: getting the slot used for the iKey 4000
public static long[] getSlotsWithTokens() throws IOException{ String libraryPath = "c:/windows/system32/dkck201.dll"; CK_C_INITIALIZE_ARGS initArgs = new CK_C_INITIALIZE_ARGS(); String functionList = "C_GetFunctionList"; initArgs.flags = 0; PKCS11 tmpPKCS11 = null; long[] slotList = null; try { try { tmpPKCS11 = PKCS11.getInstance(libraryPath, functionList, initArgs, false); } catch (IOException ex) { ex.printStackTrace(); throw ex; } } catch (PKCS11Exception e) { try { initArgs = null; tmpPKCS11 = PKCS11.getInstance(libraryPath, functionList, initArgs, true); } catch (IOException ex) { ex.printStackTrace(); } catch (PKCS11Exception ex) { ex.printStackTrace(); } } try { slotList = tmpPKCS11.C_GetSlotList(true); for (long slot : slotList){ CK_TOKEN_INFO tokenInfo = tmpPKCS11.C_GetTokenInfo(slot); System.out.println("slot: "+slot+"\nmanufacturerID: " + String.valueOf(tokenInfo.manufacturerID) + "\nmodel: " + String.valueOf(tokenInfo.model)); } } catch (PKCS11Exception ex) { ex.printStackTrace(); } catch (Throwable t) { t.printStackTrace(); } return slotList; }

In my case, Im using only one USB token, and the method writes the following info to the console:
slot: 2 manufacturerID: SafeNet, Inc. model: Model 400

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

93

Digital Signatures for PDF documents 2012

The method returns an array containing only one int value, so its OK to use the first (and only) item in the array. Now that I know that the value is 2, I could easily reuse the code from sample 50 changing nothing but the configuration file. It doesnt matter if were signing on an HSM or on a USB token. It doesnt matter if were siging in a Windows or on a Linux machine. Were using PKCS#11. In the next example, well do something completely different. Well create a signature on the chip of a smart card. This will require us to write our own implementation of the ExternalSignature interface. Thats right: we wont be using iText PrivateKeySignature class.

4.2 Signing a document with a Smart Card using javax.smartcardio

TODO

4.3 Client/server architectures for signing

TODO

TODO

5.1 Validating signed PDFs

TODO

5.2 PAdES 4: Long-Term Validation

TODO

Appendix
TODO

A. How to protect the integrity of a paper document?

TODO

B. Electronic signatures and digital signatures: are they the same thing?
TODO

C. Digital signatures on Android example

TODO

If you want to be kept up to date regarding updates to this document, please register for our newsletter at http://itextpdf.com/newsletter The completed document should be ready by the end of September. Please send your comments, corrections and suggestions to the iText mailing-list: http://itextpdf.com/contact.php

Ea rly Ac ite c xt es pd s f.c Pr om ev ie

94

5. Validation of signed documents