ISO's new PDF signature extensions

Introduction

Two PDF 2.0 extensions that have been in the pipeline for a long time are now finally out there!

• ISO/TS 32001 extends PDF to allow hash functions from the SHA-3 family to be used. This extension spec was published in September.
• ISO/TS 32002 clarifies ECDSA support in PDF and adds support for EdDSA (!) signatures. This one was published just yesterday.

Especially the addition of EdDSA is a pretty big deal, since EdDSA has many advantages over other popular signature algorithms.

So, how does this work? Read on.

Why is an extension standard even necessary?

ISO 32000-2 explicitly enumerates all signature algorithms and digest functions (and combinations thereof) that are allowed in PDF 2.0. To cut a long story short: ISO/TS 32001 and ISO/TS 32002 extend those lists. In fact, neither document proposes any significant changes to PDF-level structures. If so, why bother codifying them as ISO technical specifications?

There are a number of reasons, and they all have to do with interoperability. Here are some of the highlights.

• In file formats where multiple algorithm choices are available, there needs to be a way to announce the choices you made. ISO/TS 32001 and ISO/TS 32002 tell you which object identifiers (OIDs) you should use when producing signatures with EdDSA or SHA-3 digest functions¹. This allows recipients to detect systematically that, e.g., your Ed25519 signature is actually an Ed25519 signature instead of having to guess. Pretty crucial.
• While ISO 32000-2 declares that ECDSA is allowed in PDF 2.0, it doesn’t actually say which curves should be supported by all PDF 2.0 processors. ISO/TS 32002 addresses that by explicitly including a list of common curves (and their OIDs) that should be recognised by all processors.
• ISO/TS 32002 also requires ECDSA public keys to specify their curves by name (i.e. OID). Passing curve parameters in-band is forbidden². The overwhelming majority of general-purpose ECDSA implementations already enforce this rule in some form or another.
• Both extension documents also register themselves as PDF extensions, which allows implementers to explicitly declare the extensions they use in any given PDF document.

If you want to add support SHA-3 digests and EdDSA in your favourite piece of PDF software, and you have access to cryptographic tooling that supports the relevant primitives, then all you have to do is write some bookkeeping code. In other words, you have no excuse³, get to it already!

Where can I try this out?

As it happens, pyHanko already implements the required changes. I’ve included a quick do-it-yourself demonstration below.

If you don’t feel like going through the steps yourself, you can also watch the demo as an asciicast.

Installation

Since pyHanko is available through PyPI, you can install it using pip⁴—optionally in a virtualenv.

pip install pyhanko>=0.15.0

Note that depending on settings, pip doesn’t always install executables on the PATH. If so, prefix the commands below with python -m.

Sample keys

Here is some sample key material⁵ to play around with:

• An ed25519 private key (unencrypted/no passphrase)
• A certificate issued for said key
• A self-signed CA certificate for the issuer

Creating and validating an Ed25519 signature

Once the key files are in place, grab any PDF file, and try creating a signature:

pyhanko sign addsig --field Signature \
    pemder --key signer.key.pem --cert signer.cert.pem \
    --chain ca.cert.pem --no-pass \
    input.pdf output.pdf

If all goes well, pyHanko should automatically figure out that it’s dealing with an ed25519 key, and proceed accordingly. You can validate the output as follows:

pyhanko sign validate --pretty-print --trust ca.cert.pem output.pdf

You should see this snippet in the output:

Integrity
---------
The signature is cryptographically sound.

The digest algorithm used was 'sha512'.
The signature mechanism used was 'ed25519'.

Moreover, if you open up the file in a PDF debugger such as iText RUPS, you’ll see that the ISO/TS 32002 developer extension has been registered automatically as well.

What’s next?

Given that both of these extensions are very, very new, it’ll probably take a while before you can expect broad support across the market. It’s hard to say exactly how long that will take. On the one hand, several PDF software vendors participated in interoperability testing prior to publication, which bodes well for support in the PDF industry.

On the other hand, it’ll probably take a lot longer before public CAs start routinely issuing document signing certificates for EdDSA keys. Either way, they can’t start doing that if they can’t count on PDF implementations to support modern cryptography, so if you’re a PDF developer, please do your part!

Bibliography