The Password That Opens It, and What May Be Done with It

Summary

A binder goes in a drawer and the drawer takes a key. A PDF works the same way, with two passwords rather than one. The first is typed by whoever opens the document: as long as it is not typed, the reading software shows nothing at all. The second belongs to whoever wrote the document, and hands that person everything the others are asked to do without. Both are yours to choose, and you may ask for one, the other, both, or neither. What you name is allowed, and what you leave out stays out. Those are wishes the reading software people actually use honours; the password before the first page is the one that truly holds the door. And since the password travels with your request, send it over a secure connection — the document is written with it, and it is forgotten the moment the file is on its way back.

Request Schema

• protection — object, optional, absent by default. Present, the document is locked under AES-256; absent, it is written in the clear.
• protection.user_password — string, optional. What a person types before reading software shows a single page. Absent, the document opens with nothing typed in.
• protection.owner_password — string, optional. What the author types to be given everything the permissions withhold. Absent, the file states the other password in its place.
• protection.permissions — array of strings, optional, empty by default. Each name grants one thing, and what is granted is what is named. Eight values:
  • printing — the document may be printed.
  • printing_at_full_resolution — it prints at the resolution it was drawn at. Granting printing alone prints it as a coarse picture.
  • modifying — the content of the document may be changed. Annotating it, filling in a form and reordering its pages each have a permission of their own, below.
  • copying — text and pictures may be taken out of it.
  • annotating — shapes may be drawn over it and form fields filled in.
  • filling_forms — form fields may be filled in on their own, wherever annotating is left out.
  • extracting_for_accessibility — text may be taken out for a screen reader; every locked document grants it, named or not.
  • assembling — pages may be inserted, rotated or removed.
• A name outside the eight comes back 400, the eight listed with it.
• protection.key — string, optional. The thirty-two bytes the encryption key is built from, in base64, the way an embedded font's bytes travel. Absent, the server draws them once per render. A value that is not base64, or that is not thirty-two bytes once decoded, comes back 400.
• protection.only_the_attachments — boolean, optional, false by default. true narrows the lock to the document's attachments: the pages, the strings and what the document says about itself are written in the clear and open with nothing typed in, each attachment is written as ciphertext, and the password the request states is what hands the attachments over. A request asking for it for a document with no attachment, or that states both passwords, comes back 400.
• protection.for_older_readers — boolean, optional, false by default. true locks the document the way older reading software opens it: AES with a key of 128 bits, the passwords spelt in the PDFDocEncoding character set, the document declaring PDF 1.6 at the least. A password that character set cannot spell comes back 400.
• protection.metadata_in_the_clear — boolean, optional, false by default. true leaves the document's metadata packet readable while everything else is locked: the title, the author and the rest of what the document says about itself as XML, for a search index or an archive's catalogue to read without the password. The strings of the information dictionary stay locked with the rest.
• protection.authenticated — boolean, optional, false by default. The lock that tells reading software a byte was changed: AES in Galois/Counter Mode, PDF 2.0.

Two renders of one protected request that states no key are two different files, the encryption key being read off the machine each time. A document meant to come back byte for byte across two renders states its own protection.key, or is written in the clear, and asks for no run of text carrying the moment of rendering — those are the two places in the schema where one request gives two files.

Archiving: archive and protection are asked for one at a time, and a request stating both comes back 400. An archiving standard promises the file can still be read once nobody is left who was told the password, and every part of PDF/A holds a file to that.

Accessibility: every locked document grants extracting_for_accessibility, whether the request names it or not, so that a screen reader always has something to read.

A password is carried in the request as it stands, so a customer sends one over TLS and keeps it out of anything that writes a request down.