Update (May 2021): The PDF format cleared this up further in PDF Ref 2.0 Section 12.7.5.5 and made it clear that the appearance stream of a digital signature should be created at the time of signature: For signature fields that are visible, the appearance dictionary (AP) for the widget annotation of these fields should be created at the time of signature creation. This dictionary defines the field’s visual appearance on the page (see 12.5.5, “Appearance streams”), but the information included in the appearance dictionary shall not be used by a signature verification handler at the time of signature verification. It is there strictly for the purpose of providing a way for a human verifier to perform their own verification of the visual representation. A PDF processor shall not incorporate the validation status of a signature (e.g. a checkmark for passed or an X for failed) into the appearance of the signature field.
Outdated: Multiple Layers in Digital Signatures
Following an old format, digital signature field will sometimes define an appearance containing multiple entries / layers to be turned on or off based on the signature validity by the application at display time.
In an older version of iText, the method to add all these layers to a signature appearance is called setAcro6Layers().
We found this documentation from iText:
2.4.1 Defining a custom PdfSignatureAppearance
In this section, I’m 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:
- n0: Background layer.
- n1: Validity layer, used for the unknown and valid state; contains, for instance, a yellow question mark.
- n2: Signature appearance, containing information about the signature.
- n3: Validity layer, used for invalid state..
- n4: Text layer, for a text presentation 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, you’d put the information about the signature. If the signature was made invalid, you’d see the content of layer n3, usually a red cross. Layers would be made visible or not, depending on the status of the signature. Now please forget about these layers. Since Acrobat 6 (2003) the use of layers n1, n3 and n4 is no longer recommended…
The use of layers n1, n3, and n4 is no longer recommended since Acrobat 6. Acrobat 6.0 and higher recommends that only layer n0 and n2 be present.
No Support in Qoppa
Qoppa PDF rendering code does not have built-in logic to turn on or off the layers based on the signature validity. Our code follows the standard PDF specifications when it comes to rendering the appearance stream and is rendering all of the layers. When rendering such signatures, the signature appearance may display both the question mark or validity check mark (from n1 layer) as well as the invalid cross (from n3 layer).
Do you plan to add support for this?
No. There were good reasons for discontinuing this feature. A viewing application essentially has to modify the document (although only internally) based on the state of the digital signature, to remove commands to draw only some of the layers. This goes against the whole principle of digital signatures.
We’ve considered adding support for this, but there is a few factors that stopped us from doing so:
- This format has not been used since 2003, almost 20 years ago.
- Adobe recommends against using this.
- It would take significant effort to implement support for this.
- We could justify the effort if we saw a future for this feature, but considering that software is not supposed to use this, we think there are very few documents in existence, and probably close to none that will be created in the future that use this feature.
