The password that opens it, and what may be done with it

Lock the document under a password, and name what a reader is asked to allow: printing, copying, filling in a form.

Summary

A binder goes in a drawer and the drawer takes a key. A PDF works the same way, with two keys 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. Beside the keys you name what a reader may do once the page is on the screen: print it, copy a sentence out of it, fill in a form, write a note in the margin. 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.

Technically

Written at the top level of a request, under "protection"

protection locks the document: every string and every stream is written as ciphertext under AES with a two-hundred-and-fifty-six-bit key. The block on its own is enough — one naming neither password locks the file all the same and lets it open with nothing typed in, which is what most protected files in the world do. The key is read off the machine's own randomness once per render and is derived from nothing the request carries, so two renders of one protected request come back as two different files; it is the one block of the schema of which that holds. The permissions are named one by one, each name granting one thing, and a name outside the eight comes back 400 with the eight listed. What the permissions withhold is stated in the file for a reader to honour, and the reading software in daily use does honour it; the user_password is what holds a page back on its own. A password stays inside the render: it reaches neither the log, nor an incident report, nor the answer the caller is given, and the body of the request is dropped as soon as it is read.

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 a reader 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 software that reads the page aloud.
    • assembling — pages may be inserted, rotated or removed.
  • A name outside the eight comes back 400, the eight listed with it.

Two renders of one protected request are two different files, the key being read off the machine each time. A document meant to come back byte for byte across two renders is written in the clear.

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: a locked document claiming pdfua1 grants extracting_for_accessibility, so that software reading the page aloud has something to read. A document claiming pdfua2 rests on PDF 2.0, which keeps that setting in reserve, and names whichever permissions it likes.

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

A whole request that draws it

{
  "protection": {
    "user_password": "the-reader-types-this",
    "owner_password": "the-author-keeps-this",
    "permissions": [
      "printing",
      "printing_at_full_resolution",
      "extracting_for_accessibility"
    ]
  },
  "metadata": { "title": "Salary statement, March 2026" },
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 768 },
      "content": ["Salary statement, March 2026"],
      "font": "sans",
      "font_size": 18
    }
  ]
}

The line that sends it, in three languages

The document as a whole

The numbers the reader shows A hundred letters in a single file What the document says about itself A file still readable in thirty years An invoice a person and a machine both read The address relative links are read against The PDF version the file declares What an image says about itself Files the document carries beside its pages Which carried files a page claims The identity card a single page carries The accessibility standard the document claims

Where to go next

Every key of a request, in one page The other forty-one settings of a request

See the prices See the examples