pdf-association
SigFlags - Signature flags meaning II
Years ago I was asking Leonard about the exact meaning of the sigflags attribute and his answer was as follows:
If bit 1 (HasSigs) is set, then the document has signature fields. They may be either signed or unsigned if bit 2 (AppendOnly) is set, then any changes to the PDF shall be done in append mode. By itself, not an indication of signed fields. If both bits are set, then the file has signed fields.
I want to use sigflags as a quick indicator whether the document is signed or not. So my question is when both attributes are set (true): Is this really a clear indication of the existence of signed signatures?
What if there are only unsigned signatures and AppendOnly is still set? To e.g. indicate that I (as a document creator) want that all changes are done in append mode? ("By itself, not an indication of signed fields.")
Thank you for you input!
PS: According to the spec the sigflags attributes are defined as follows:
| Bit | Name | Meaning |
|---|---|---|
| 1 | SignaturesExist | If set, the document contains at least one signature field. This flag allows an interactive PDF processor to enable user interface items (such as menu items or push-buttons) related to signature processing without having to scan the entire document for the presence of signature fields. |
| 2 | AppendOnly | If set, the document contains signatures that may be invalidated if the PDF file is saved (written) in a way that alters its previous contents, as opposed to an incremental update. Merely updating the PDF file by appending new information to the end of the previous version is safe (see H.7, "Updating example"). Interactive PDF processors may use this flag to inform a user requesting a full save that signatures will be invalidated and require explicit confirmation before continuing with the operation. |
I want to use
sigflagsas a quick indicator whether the document is signed or not. So my question is when both attributes are set (true): Is this really a clear indication of the existence of signed signatures?
As you already explained yourself, it is not guaranteed that a document with both those flags set is signed, nor is it guaranteed that a document with both those flags cleared is not signed.
As far as I can see, there is no requirement in the spec to set those flags, Thus, you cannot even blame a PDF signer that does not set those flags for doing anything wrong.
On the other hand, having AppendOnly set without a signature strictly speaking is invalid. Nonetheless, there are much worse violations of the PDF specifications that are ignored by most PDF processors.
Essentially those flags are there to give hints to a visual PDF processor to adapt its GUI to include (e.g. signature validation) or exclude (e.g. full save) certain options. After having read all the relevant parts of a PDF, the PDF processor can finally adapt its GUI to match the actual findings.
Thus, if you only need such a weak indicator, you can use the flags. Otherwise, you have to dive deeper into the structures.
(Of course, if the flags indicate a signature but your PDF processor finds none, this might be because there is a signature but you don't support its signing scheme; in that case, therefore, your PDF processor should still warn that certain operations may break something in the document, even if the processor doesn't know exactly what.)
For those looking: Table 225 in ISO 32000-2:2020 in subclause 12.7.3 Interactive form dictionary.
Regardless of current extant files and implementations (and a lack of ISO-ese), I believe the spec is quite clear on a couple of aspects that validators (for example) could check (e.g. only 2 bits are defined and the rest "shall be" zero; if SignaturesExist bit is set then "the document contains at least one signature field" (stated factually)). The processor requirement for AppendOnly is also only permissive ("may"). So any additional reliance on these bits would be reading into the definitions more than is currently stated...
The processor requirement for AppendOnly is also only permissive ("may").
That "may" is not an ISOese/RFCese MAY but merely factual: A generic PDF signature is not required to cover its whole revision by the spec, so a save that applies changes to that revision may or may not break such a signature.
Nonetheless, see my original comment, I don't recommend either to fully trust these flags.
As you already explained yourself, it is not guaranteed that a document with both those flags set is signed, nor is it guaranteed that a document with both those flags cleared is not signed.
As far as I can see, there is no requirement in the spec to set those flags, Thus, you cannot even blame a PDF signer that does not set those flags for doing anything wrong.
That is quite clear. The sigflags attribute is optional so it could be set or not. But if I have a PDF UI and a PDF document is loaded which contains the flag I want to know how exactly the value can be interpreted to trigger dedicated actions like showing a signature tab (or not).
The following bit values can occur:
0 - nothing set - nothing to do 1 - SignatureExists=true, (AppendOnly=false) - Signed or unsigned signature exists 2 - AppendOnly=true, (SignatureExists=false) - All changes should be done in append mode (don't know whether there are signatures) -> All changes will be added in append mode 3 - SignatureExists=true, AppendOnly=true - There are signatures all changes should be done in append mode
My question was basically about 2 and 3.
For 2: I like the idea to be able to instruct a PDF processor to do everything in append mode, however the spec says "If set, the document contains signatures that may be invalidated". Meaning there must be signatures inside. But then normally 'SignatureExists' should be set as well, right? So the definition of "AppendOnly=true AND SignatureExists=false" is not clear
For 3: Leonard said "If both bits are set, then the file has signed fields." But this isn't clear from the description imho since SignatureExists=true also for unsigned signatures... So I would like to propose the following improvement to the spec:
| Bit | Name | Meaning |
|---|---|---|
| 1 | SignaturesExist | If set, the document contains at least one (signed or unsigned) signature field. This flag allows an interactive PDF processor to enable user interface items (such as menu items or push-buttons) related to signature processing without having to scan the entire document for the presence of signature fields. |
| 2 | AppendOnly | Instructs a pdf processor to apply all changes using the incremental update mechanism. If 'SignaturesExist' is set as well, the the document contains signed signatures that would be invalidated if the PDF file is saved (written) in a way that alters its previous contents, as opposed to an incremental update. Merely updating the PDF file by appending new information to the end of the previous version is safe (see H.7, "Updating example"). Interactive PDF processors may use this flag to inform a user requesting a full save that signatures will be invalidated and require explicit confirmation before continuing with the operation. |
That would change the descriptions to better match what Leonard told you.
But does it really make sense?
If you open up the description of AppendOnly to allow for other reasons than signature validity, then why do you want to make these other reasons non-combinable with the existence of unsigned signature fields?
IMO there are two choices:
- Leave the flag descriptions as they are. We are talking about SigFlags after all (flags specifying various document-level characteristics related to signature fields), so why should an AppendOnly in here have a meaning unrelated to signatures?
- Open up the AppendOnly description completely, so that even in combination with SignaturesExist it still only means "please use incremental updates only" without implying that any existing signature fields are signed. In this case one might consider adding a third flag ContentSigned to indicate that some content of the PDF actually is signed.
As an aside,
the the document contains signed signatures that would be invalidated if the PDF file is saved (written) in a way that alters its previous contents
No, not necessarily: If you receive a PDF with two revisions, the first one being signed, the second one adding some changes in an incremental update but not being signed by itself, you can freely alter the contents of that existing incremental update and don't have to add an own incremental update for your changes.
Also PDF as a format is open to other signature schemes, too. E.g. someone might revive object digests and use them as the digests signed in their scheme. If done properly, an object digest can survive a complete re-save with only unrelated changes.
Thus, I would not claim that the signatures would be invalidated, merely mention that they may be invalidated.