# Trust PDF

A library to verify that a signed PDF matches the unsigned original.

## The Problem

Imagine this scenario: you generate a PDF file with your terms and conditions
and send it to your customer or business partner to be signed. The other party
signs it and uploads it to your server.

For all you know about digital documents and signatures, it should be trivially
easy for your server to verify the validity of the signature, and that the
signed document they submitted is actually the same document you sent to them,
right?

**WRONG!**

It is unreasonably hard to decide if the contents of a signed PDF file you are
given corresponds to the unsigned version you wrote and trust! It seems there
isn't any established, true and tested protocol or standard on how to do that,
nor does it seems that the writers of the PDF standard gave any thought to the
problem.

Which is kind of understandable, after all, PDF standard assumes there is an
actual GUI, with an actual person reading the file, and that this person will
read it again after it was signed and sent back, and will watch the PDF embedded
videos, and execute the PDF embedded JavaScripts. But since you are automating
the process, you should be instead dealing with PKCS #7 files with the PDF
embedded in them, and not the other way around (and if that was the case, the
task would be indeed trivial).

But in the real world, we have governments running online tools to generate
legally binding digital signatures for its citizens, where the only possible
output is a signed PDF, who became the de-facto standard for digitally signed
documents, and we have to find a way to automatically deal with them.

This library is my attempt to tackle the problem, and it will work as long as
the signature is added in a specific and restricted way.

## The Difficulty

The problem is that the PDF is a complex format with lots of moving parts, and
the embedded signature is just another object of its internal structure. In
fact, it is handled by PDF as if it is a form field (and sometimes an
annotation, with the visible drawing that users think is the actual signature,
but is not). So, to include a signature, you have to necessarily change the PDF
file in non-trivial ways, with limitless degrees of freedom and choices on how
to do it.

Word is that Adobe Acrobat will deserialize all the PDF objects into memory, add
the new signature objects and then re-serialize it in a completely new save.
Thus any hope of trivial byte-to-byte comparison goes out of the window.

But there is a glimmer of hope in an alternative way of modifying a PDF file,
called incremental update. The PDF signers I have tested will actually use this
method, and if the original PDF has the proper `/SigFlags` set, even Acrobat
will use it. It works by taking the original PDF bytes verbatim, and appending
the new content. The original file becomes a prefix for the new file.

One might think that you just have to check if the original file is a prefix of
the signed file to ensure it was not modified, and one would be wrong. An
incremental update can change absolutely everything about a PDF file. It
actually has to provide a new index for the PDF objects, which might optionally
use the objects in the original file, but it doesn't have to. And a signature
included in such way will not only sign the original file range, it will sign
everything, including the incremental update itself, so you can't have your
lawyers argue that what was signed was actually the prefix document, and not the
modified one.

## The Strategy

To solve the problem, this library whitelists what can be done in order to add
signatures in the document:

* The signed document must start with the unsigned document;
* Every added signature must have its own incremental update;
* Each incremental update must keep unmodified all the objects in the previous
  increments, except the ones strictly necessary to change: the `/Catalog`, the
  `/AcroForm` and at most one `/Page`;
* In the `/Catalog`, only `/AcroForm` and a couple of other fields can be added,
  if missing;
* In `/AcroForm`, a single extra `/FT /Sig` form field must be added;
* In at most one of the pages, a single annotation of `/Subtype /Widget` can be
  added;
* The signatures must be valid, and cover from the beginning of the document to
  the end of their incremental update;
* The final signature must cover the entire document;
* And probably some more restrictions.

It is my hope that this will suffice to prevent any content modification of the
rendered PDF, with the exception of the signature annotation, which might be
crafted and placed somewhere to meaningfully change the interpretation of the
contents. To mitigate that, this library will also return the page and the
rectangle of each signature annotation, for further whitelisting by the
application.

## Usage

Below is a minimal complete program on how to verify one signed PDF file against
an unsigned reference.

```rust
// Load the PDF files
let reference_file_i_wrote_and_trust =
    std::fs::read("test_data/valid_modification/unsigned.pdf").unwrap();
let signed_file_i_received =
    std::fs::read("test_data/valid_modification/signed-visible.pdf").unwrap();

// Verify the signed file with the original as reference
let result = trust_pdf::verify_from_reference(
    reference_file_i_wrote_and_trust,
    &signed_file_i_received,
);

let Ok(signatures) = result else {
    panic!("Someone is trying to trick you!");
};

// The signed document is valid extension of the unsigned document,
// but we still need to validate the signatures. If you enabled the
// `openssl` feature, we have a helper function for that.
#[cfg(feature = "openssl")]
{
    let mut trust_store = trust_pdf::openssl::load_ca_bundle_from_dir("test_data/trusted_CAs")
        .unwrap();
    trust_store
        .set_flags(openssl::x509::verify::X509VerifyFlags::PARTIAL_CHAIN)
        .unwrap();

    let intermediaries = openssl::stack::Stack::new().unwrap();

    let digital_signature_verifier =
        trust_pdf::openssl::OpenSslVerifier::new(trust_store.build(), intermediaries);
    if digital_signature_verifier.verify_many(&signed_file_i_received, &signatures).is_ok()
    {
        println!("Everything looks alright!");
    } else {
        panic!("The digital signatures are invalid!");
    }
}
```

## Optional Features

* `openssl`: this feature uses the `openssl` crate to provide an implementation
  for the `Pkcs7Verifier` trait, needed to verify PKCS #7 signatures embedded in
  the PDF files. You can however provide your own implementation, so dependency
  on OpenSSL is optional.

## Security

This library is a best effort attempt, and as it stands, was written by one guy
during his holidays and spare time, and underwent no independent review, no real
world usage, and barely any testing. Also be mindful of the no-warranty clause
in the license.

That said, if you really want to secure anything with it, then I suggest, as a
backup plan, putting legal language in you unsigned document saying that any
digital signature in the document applies only to the first, unmodified version,
of the PDF document, and modifications introduced via Incremental Updates are
not legally binding. Assess with your lawyer the chances of such a thing
holding up in court.

Finally, in the off-chance anyone is interested in funding it, this project
would benefit from a professional security audit and a bug bounty program.

# License

This project is distributed under MIT license.