Digital Signature Fundamentals

Public-key signatures cannot be applied efficiently to megabytes of data, and they should not be: the private-key operation is slow, and its input is limited in size. Every practical scheme therefore works in two steps, usually called hash and sign.

Verification repeats the first step on the data that is presented, compares the new digest with the one that the signature vouches for, and runs the public-key check. If the data changed, the digests differ. If the signature value was forged, the public-key check fails. The signature does not hide anything: a signed PDF is perfectly readable, and signing is independent of encryption (see Encryption & Permissions).

The first Java example uses only the JDK to make the two steps visible, with the key of the test signer created later on this page. It needs no Maven dependency beyond Java 21; the PKCS#12 file billing-signer.p12 is created by the script in the section on the test PKI, and its store password comes from the environment, never from the source.

Run with java HashAndSign.java billing-signer.p12 after exporting the environment variable, it prints a 64 hex digit digest (the SHA-256 of the data), a signature length of 384 bytes for an RSA 3072 key, true for the original data and false for the changed data. The digest value is not reproduced here because it depends only on the data and is irrelevant to the argument. Note that Signature.getInstance("SHA256withRSA") hashes internally: it is the combination of SHA-256 and the RSA PKCS#1 v1.5 signature scheme. PDF signing does the same two steps, but the thing that is digested is a pair of byte ranges of the file, and the thing that is signed is a CMS structure that contains the digest. Both are described below. The class and its methods derive from the Java documentation of java.security.Signature and java.security.MessageDigest.

The choice of algorithms matters for the lifetime of the document. For new signatures use SHA-256 or stronger. SHA-1 is forbidden for new signatures by ETSI TS 119 312, the European catalogue of cryptographic suites, and appears only in legacy files; the SubFilter adbe.pkcs7.sha1 of old tutorials is one of them (see below). RSA keys should be at least 3072 bits for signatures that must stay valid for years, or an elliptic curve such as P-256, which gives smaller signatures and faster operations. The algorithm and key-length recommendations, including RSA-PSS, ECDSA and the post-quantum schemes added in the current edition of the ETSI document, are discussed in PAdES Baseline Levels.

A bare public key says nothing about who owns it. An X.509 certificate (RFC 5280) binds a public key to an identity (the subject) by having another party, the issuer, sign the pair. A certificate carries these fields that matter for signing PDFs:

A single certificate is rarely enough to trust. Instead, validators build a chain (a certification path): the signer’s end-entity certificate was issued by an intermediate CA, which was issued by a root CA, which is self-signed and which the validator was configured to trust. The root is the trust anchor. Trust comes from the anchor, never from the PDF: a validator accepts a chain only if it ends at an anchor from its own trust store, which is the Adobe Approved Trust List for Acrobat, the EU Trusted Lists for European qualified signatures, or the certificate you configure in your own verification code.

The figure shows the test chain created below and the steps a validator takes. A production chain has the same shape, usually with one or two intermediate CAs between root and signer, and the signer’s private key usually inside a smart card, an HSM or a remote signing service rather than a file (see Remote, HSM and Deferred Signing). Which certificates are acceptable depends on the signature level you promise: any certificate works for a self-checked internal workflow, a certificate from a trusted-list CA is needed for Acrobat to show a green check without manual trust configuration, and a qualified certificate on a qualified device is required for a qualified electronic signature under eIDAS. These distinctions are explained in PAdES Baseline Levels. The format of the certificate and the path validation algorithm are specified in RFC 5280.

A private key and its certificate chain are stored together in a keystore. The format that works everywhere is PKCS#12 (RFC 7292), a file with the extension .p12 or .pfx that is encrypted with a store password. Java 9 made it the default keytool type, replacing the proprietary JKS, and Java 21 reads and writes it natively with KeyStore.getInstance("PKCS12"), which is what both examples on this page and the other signature pages use. OpenSSL creates and reads the same files. A keystore holds entries, identified by an alias: a private key entry carries the key and the certificate chain (signer first, then the issuing CAs), and a trusted certificate entry carries a single public certificate.

Never commit a keystore, never paste a key into a page or a ticket, and never log a password. In a service the store password comes from the secret store of the platform (see Secrets Manager and KMS, Key Vault and Secrets and Secret Manager and KMS), and the keystore bytes themselves come from the same place or from a mounted volume; better still, the private key stays in an HSM or a managed key service and the service only sends it digests to sign. The examples read the password from the environment variable BILLING_KEYSTORE_PASSWORD.

All the signature examples of this section use the same two keystores, created once with the JDK’s keytool. This page owns the script, and the other pages show a short reminder and link back here. The naming convention is fixed:

The script below creates a 3072-bit RSA root CA valid for ten years, a 3072-bit RSA signer valid for 825 days, and has the CA issue the signer certificate from a certificate signing request. It reads the store password interactively, so that no password literal exists in the page or in the shell history; for a throw-away test run you may instead export an obvious placeholder value, such as changeit-placeholder, and delete the files afterwards.

Three details of the script are easy to miss. First, -storepass:env and -keypass:env make keytool read the password from the named environment variable; they avoid putting the password on a command line where other users of the machine could see it. Second, in a PKCS#12 keystore the key password is the store password, which is why both options name the same variable. Third, keytool -importcert of the issued certificate works because the CA certificate was imported first as a trusted entry with its own alias: keytool rebuilds the chain from the certificates it finds in the keystore, and the result is a private key entry whose chain has length two. The check in step 6 prints Certificate chain length: 2, with the signer’s owner and the CA as its issuer. The commands are documented in the keytool reference for JDK 21. The extensions on the signer certificate say that it is not a CA (ca:false), may be used to sign data (digitalSignature, nonRepudiation) and is intended for e-mail and document protection (emailProtection); a validator that checks key usage accepts it for signing documents.

The CA keystore billing-test-ca.p12 is needed only for issuing; the signing examples read billing-signer.p12, and validation examples read billing-test-ca.pem. Because the CA is created by you, it is trusted by nobody else: Acrobat typically reports the signature as intact but with an unknown signer until you add billing-test-ca.pem to its trusted certificates, which is exactly the situation of a signature made with any certificate outside a trust list.

OpenSSL creates the same structure, which is useful on machines without a JDK, or when you want an elliptic curve key. The following variant uses ECDSA with P-256 for both certificates and produces files of the same names, so the other pages work with either variant (their signing examples use the algorithm of the key; an EC key signs with SHA256withECDSA). It was run with the LibreSSL 3.3.6 that ships with macOS; the options used are standard OpenSSL options.

The -subj option sets the distinguished name; leaving the [ dn ] section of the configuration empty is the form that keeps the option effective with both OpenSSL and LibreSSL. After this script the unencrypted .key files must be deleted, because only the PKCS#12 file is protected by the store password. Finally, openssl verify printing OK proves that the signer certificate chains to the CA certificate, the same fact that a PDF validator re-checks when it opens a signed file. The options are documented in the openssl-pkcs12 manual. In both variants the files are generated when you run the script; none of their content appears in this documentation, and a real service never reuses a test CA.

The signature value itself is not stored as a bare number. PDF stores a Cryptographic Message Syntax (CMS) object, specified in RFC 5652, the standard successor of PKCS#7. The two names are used interchangeably in PDF, as in the SubFilter adbe.pkcs7.detached. A signature uses the CMS type SignedData, which contains:

A SignerInfo identifies the signer’s certificate (issuer plus serial number, or a subject key identifier), names the digest algorithm and the signature algorithm, and carries two sets of attributes. The signed attributes are covered by the signature: the content type, the messageDigest attribute (the SHA-256 of the signed bytes of the file), in plain CMS and CAdES signatures the signing time, and for CAdES signatures the signing-certificate attribute that pins the exact certificate. The PAdES baseline profile (ETSI EN 319 142-1) forbids the CMS signing-time attribute: in a PDF the claimed signing time is the /M entry of the signature dictionary. It is these signed attributes, and not the file, that the private key signs: that is hash and sign applied twice, once to the file and once to the attribute set. The unsigned attributes can be added later without breaking the signature, and the most important one is the signature timestamp of RFC 3161, which proves that the signature existed at a given time (the basis of PAdES B-T).

The consequence for a validator is a fixed sequence: recompute the file digest and compare it with messageDigest, then verify the signature value over the signed attributes with the public key of the signer certificate, then validate the certificate chain. The Java example later on this page performs the first two steps. The European profile of CMS used in PAdES is CAdES (ETSI EN 319 122), and the signature timestamp format is RFC 3161, both covered in PAdES Baseline Levels.

In a PDF a signature lives in two linked places. A signature field is a form field of type /Sig (see How a PDF File Works for objects and the catalog): it is part of the /AcroForm field tree, it may be visible through a widget annotation with an appearance, or invisible, and its value /V points to a signature dictionary. The /AcroForm dictionary carries /SigFlags, whose bits tell a viewer that the document contains signatures and must be saved in append mode. The signature dictionary holds the signature itself:

The /Contents hex string and the signature-bearing dictionary have a property that no other object in a PDF has: their bytes are rewritten after the rest of the file is complete. This is the subject of the next section. The dictionary entries are defined in ISO 32000-2, clause 12.8, which can be downloaded free of charge from the PDF Association’s sponsored standards page (the page returns an error to command line tools, open it in a browser).

A signature cannot cover its own bytes, because the signature value depends on the digest and the digest would depend on the signature value. PDF solves it with a deliberate hole. When the signer writes the file, it:

The figure uses the numbers of a real file with two signatures made by the test signer of this page. The first signature covers [0 1235 17621 1606]: 1235 bytes before the hole, a hole of 16386 bytes, and 1606 bytes after it, ending at byte 19227, which is where the file ended when the first signature was made. A second revision was appended by an incremental update, and its signature covers [0 19354 35740 1414]: everything before its own hole, including the whole first signature, and the 1414 bytes after it, up to the end of the 37154 byte file. A signature that covers the file from the first to the last byte except its own hole is the strongest case; one whose second range ends before the end of the file protects only an earlier revision, and the bytes after it are changes that a validator has to examine separately (see the section on incremental updates).

A validator therefore does not trust the contents of the PDF it reads in the signed bytes: it checks that the /ByteRange has the shape of two ranges with a single gap, that the gap is exactly the /Contents of the signature dictionary it started from, and whether the second range reaches the end of the file. Several published attacks against PDF validators played with these checks, which is why a validator must be strict and why you should validate the files you produce with a different implementation than the one that signed them (see Signature Validation and Long-Term Validity).

The /SubFilter entry tells a reader how to interpret /Contents. The ones that matter today are:

The CAdES SubFilter is not just a different name. CAdES requires the signing-certificate-v2 signed attribute that binds the signature to the exact signer certificate, and is what a PAdES validator expects. For invoices that have to be valid in a European regulatory context, choose ETSI.CAdES.detached from the start; for an internal approval workflow, either works. How a validator treats each of them is discussed in the validation page.

A PDF can be modified by appending a new section to the end of the file, with new and changed objects, a new cross-reference section and a trailer whose /Prev points to the previous cross-reference section (see the incremental update section of How a PDF File Works). The bytes before the appended section are not touched. That property is what makes signatures possible on a format that is otherwise rewritten whenever it is edited: the signature of revision 1 covers the bytes of revision 1, and appending revision 2 leaves those bytes, and therefore that digest, intact. A reader can recompute the digest of the first revision at any time, as the program above does.

This produces the revision concept that every signature page uses:

The figure and numbers above show it: the first signature of the file still verifies although a second revision was appended, because all it covers is its own revision. A validator that sees covers the whole file: false for a signature knows that bytes were appended after it, and must then compare the appended objects with the allowed modifications. The appended-bytes policy is therefore not a property of the crypto: it is a property of the document, declared by the author’s certification signature.

PDF defines two kinds of document signature, which differ in what they say about subsequent changes.

An approval signature (also called an ordinary or recipient signature) says "I, the signer, approve the content of the document as it was when I signed". It places no restriction on what happens afterwards: anybody can append revisions, add further approval signatures, and fill forms, and the signature simply stays valid for its own revision. A document can carry any number of approval signatures. Most signature fields of a contract workflow are approval signatures.

A certification signature (also called an author signature) is the first signature of a document and declares what changes the author permits after it. It does this through a DocMDP (Document Modification Detection and Prevention) transform in the signature’s /Reference array, whose parameter /P is the permission level, and a pointer from the document catalog:

The catalog’s /Perms dictionary is how a viewer finds the certifying signature without scanning every field. At most one certification signature may exist in a document, it must be the first signature, and any later /DocMDP entry is ignored. The three levels are:

The value of /P defaults to 2 when absent. Level 2 is the sensible default for forms workflows: the author certifies the layout and text and allows the customer to fill the fields and sign. Level 1 suits a final document such as an issued invoice that nobody should change after it left the issuer; because it permits nothing, test the downstream workflow, including whatever validation data or timestamps you plan to append, before choosing it. In iText 9 the level is AccessPermissions, an enum in com.itextpdf.signatures with the constants UNSPECIFIED (an approval signature), NO_CHANGES_PERMITTED (P=1), FORM_FIELDS_MODIFICATION (P=2) and ANNOTATION_MODIFICATION (P=3), set with SignerProperties.setCertificationLevel(...), as the test file of this page did for its first signature (level 2). The iText signing page shows the code, and the AccessPermissions API page lists the constants. Acrobat shows a certified document with a blue ribbon and tells the user what changes are allowed; a violated certification is shown as an invalid signature.

A third kind of signature exists in the specification and is worth recognising so as not to confuse it: usage rights (/UR3 in /Perms) were used by Adobe to unlock extra features of its reader for a document. They are not a document signature in the sense of this page, they are proprietary, and iText and PDFBox do not create them.

DocMDP is a document-wide policy that only the author’s first signature can set. FieldMDP is its field-level counterpart: a signature can declare that the values of certain form fields must not change after it was applied, without freezing the whole document. It exists in two forms:

In iText 9 the lock dictionary is built with PdfSigFieldLock: setFieldLock(LockAction, String...) takes PdfSigFieldLock.LockAction.ALL, INCLUDE or EXCLUDE and the field names, and setDocumentPermissions(...) sets the level that applies with this signature. A typical use in the Bookshelf Billing onboarding form is a signature that locks the fields the customer already filled, so that nothing they entered can change after the back-office employee signs; the form fields themselves (types, flags, appearances) are described in the editable forms pages of this section. The API is documented in the PdfSigFieldLock reference.

FieldMDP and DocMDP combine, and the strictest one wins: if the certification signature allows form filling (P=2) but a later signature locks fields X and Y, then changing field X after that signature invalidates the later signature while leaving the certification intact.

A PDF file may contain any number of signatures, and they are sequential, not parallel: each new signature is an incremental update that covers the whole file as it stood, including the earlier signatures and their /Contents. The figure above shows it: the byte range of the second signature contains the first signature entirely. Consequences:

For the Bookshelf Billing scenario, the ordinary sequence is: the service issues an invoice and signs it once with the company’s certificate (a certification signature at P=1 or an approval signature, depending on whether later changes are allowed) and, for the onboarding form, certifies a template at P=2, lets the customer fill it, and adds a customer signature and a back-office signature in turn. Each of these uses the same file layout described here.

The foundation is the same whichever library signs: a CMS container, a byte range with a hole, a certificate chain and an optional timestamp. The libraries differ in how much of this they hide.

These points come from books and tutorials written for iText 5 and earlier, such as the signature chapter of the 2006 iText in Action consulted for the concept order of this page (finding O11 of this section’s source analysis); that book is not reproduced.