Document security / Who can reach the document
Revoking access to a document you already delivered
The difference between a link that stops working and a document that cannot be reached, which people conflate until they need one of them urgently.
The exposure
Expiry and revocation are different mechanisms and only one of them is immediate. An expiry is set when a link is minted and takes effect at a time; nothing about issuing a shorter expiry affects a link already in the wild. Revocation is a decision taken now that has to be enforced at redemption, which means there has to be a check at redemption to enforce it. A system with expiring links and no revocation path can only wait, and the moment somebody needs revocation is never a moment when waiting is acceptable.
The decisions
Reasons rather than a description of the code. Each one has a default that is fine for a page and wrong for a file somebody keeps.
- Design the revocation path before you need it. Every system has expiry because it comes free with signing, and revocation has to be built.
- Enforce revocation at redemption. A signed token is self-contained by design, so the only way to stop honouring one is to check something at the moment it is used.
- Keep the revocation state small and fast to check, since it is on the retrieval path for every document.
- Make removing the document the backstop. If the object is gone, every link to it stops working regardless of signature validity.
- Distinguish revoking a document from revoking a person's access. They are different operations with different blast radii and both are needed.
- Record revocations with a reason, because the question afterwards is always why and when rather than whether.
In practice
A fragment, with the thing that goes wrong kept in a comment where it is the more instructive half.
/* Expiry and revocation are not the same mechanism.
expiry decided when the link is minted, effective at a time.
Issuing shorter links does nothing to the ones already
out there.
revocation decided now, effective now, and only if something on
the redemption path checks for it. */
// The check that makes revocation possible at all.
async function onRetrieve(documentId, tokenSubject) {
if (await revocations.has(`doc:${documentId}`)) throw new Gone();
if (await revocations.has(`subject:${tokenSubject}`)) throw new Gone();
return storage.read(documentId);
}
// Two operations with different blast radii; both are needed.
async function revokeDocument(documentId, { by, reason }) {
await revocations.add(`doc:${documentId}`, { ttl: MAX_LINK_TTL });
await audit.record({ action: "document.revoked", documentId, by, reason });
}
async function revokeSubjectAccess(subjectId, { by, reason }) {
await revocations.add(`subject:${subjectId}`, { ttl: MAX_LINK_TTL });
await audit.record({ action: "subject.revoked", subjectId, by, reason });
}
/* The backstop, when it has to be certain: delete the object. If the
document is gone, every link to it stops working whatever the
signature says.
And note the ceiling: the revocation entry only needs to outlive the
longest link that could still be valid. */What people do instead
Assuming a short expiry is a revocation mechanism. It bounds the damage from a leak and does nothing about a document sent to the wrong person five minutes ago, which is the case where somebody is standing at your desk asking for it to stop working now.
How this is found out
At the worst possible moment, when a document has gone somewhere it should not and somebody asks how quickly it can be withdrawn. The answer is either immediate or it is however long the expiry has left.
Frequently asked
Does this page tell me what the law requires?
No, and deliberately not. Retention periods, erasure obligations and residency rules vary by jurisdiction, by industry and by the kind of document, and they change. What these pages describe is the shape of the problem and the mechanisms a system needs in order to implement whatever answer your own advisers give you. Where a genuine tension exists, such as an immutable record against a right to erasure, it is named as a tension rather than resolved.
Why is so much of this about the contents rather than access control?
Because access control decides who can obtain a copy and has no opinion at all about what happens to the copy. Once a document is on somebody's laptop, forwarded to a colleague or printed, every control listed here has already stopped applying to it. What is inside the file is therefore the part that keeps mattering, which is the opposite of the balance you would strike for a page.
How much of this applies at a small volume?
Most of it, because these are decisions rather than infrastructure. Redacting by omitting rather than covering costs nothing. Deciding what goes on a template costs one review. Classification is one object in code. Legal hold and an audit trail are the two that take real work, and both are far cheaper to build before they are requested than under the deadline that comes with the request.
Related security topics
The decisions that depend on each other, then the rest of the same group.
Signed URLs for documents, and choosing an expiry that fits
Giving out a URL that carries its own authorisation for a limited time, which moves the access check to the moment the link is minted rather than the moment it is used.
Responding when a document goes to the wrong recipient
The response to the most common document incident, where the technical options are limited and the decisions are mostly about scope and disclosure.
Access control on documents you stored rather than streamed
The authorisation model for documents that persist somewhere after generation, which is a longer-lived and larger surface than the render call itself.
Serving a generated document behind proper access control
Making sure the person downloading a document is entitled to it, which fails most often because the document lives somewhere the check does not.
What belongs in a document filename, and what must not
The name the recipient sees, which travels further than the document's contents and is visible in places the contents are not.
Every document security topic
The full list, grouped by access, contents and what happens afterwards.
What this API actually does
The options and endpoints these decisions are built on, one page each.
Most of these are decisions rather than features, and the cheapest time to make them is before the first document is delivered rather than after one reaches the wrong person.