Document security / What is inside it
Classifying generated documents so handling rules can apply
Attaching a sensitivity level to each kind of document, which is what makes every other rule in this cluster applicable rather than aspirational.
The exposure
Handling rules are written for classifications and generated documents usually have none. Without one, every rule about retention, delivery, storage and access has to be decided per document kind by whoever is implementing it, which means it is decided inconsistently and re-decided every time. A payslip and a marketing brochure get the same treatment because the pipeline that produces them does not distinguish them, and the treatment is whichever was convenient.
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.
- Classify by document kind rather than per document, so the decision is made once and applied by the system rather than by a person.
- Attach the classification in code, next to the template, so it travels with the thing it describes and is visible to anybody changing it.
- Derive the handling from the classification: retention, whether a link or an attachment, whether a password is applied, who can retrieve it, how long a share link lives.
- Use your organisation's existing scheme if there is one rather than inventing a parallel vocabulary, since the point is to connect to rules that already exist.
- Mark the document itself only where the scheme requires it, and remember a visible marking is seen by the recipient and says something to them.
- Review the classification when a template changes materially, because adding a field can change what a document is.
In practice
A fragment, with the thing that goes wrong kept in a comment where it is the more instructive half.
// One decision per kind, in code, next to the template.
export const DOCUMENT_CLASSES = {
invoice: {
sensitivity: "confidential",
delivery: "attachment",
retentionDays: 2555,
shareLinkTtl: 3600,
password: false,
markOnDocument: false,
},
payslip: {
sensitivity: "restricted",
delivery: "link", // withdrawal may matter
retentionDays: 2190,
shareLinkTtl: 900,
password: true, // a barrier if it reaches the wrong address
markOnDocument: true,
},
brochure: {
sensitivity: "public",
delivery: "attachment",
retentionDays: 90,
shareLinkTtl: 86400,
password: false,
markOnDocument: false,
},
};
// The handling follows from it, rather than being decided per call site
// by whoever is implementing.
async function deliver(kind, doc, recipient) {
const c = DOCUMENT_CLASSES[kind];
return c.delivery === "link"
? sendLink(doc, recipient, { ttl: c.shareLinkTtl })
: sendAttachment(doc, recipient);
}
/* Use the organisation's existing scheme rather than a parallel
vocabulary: the point is to connect to rules that already exist.
And review the class when a template changes materially. Adding a
field can change what a document is. */What people do instead
Leaving classification implicit and deciding handling at each call site. Every developer makes a reasonable choice, the choices differ, and there is no single place to answer how a payslip is supposed to be handled.
How this is found out
During an audit that asks how documents are classified, at which point the answer is a description of what the code happens to do rather than a policy.
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.
Deciding how long to keep a document, and proving it was deleted
The period a document remains available and the mechanism that removes it afterwards, where the second half is the one that is usually missing.
Sending a document as a link or as an attachment, and the tradeoff
Two delivery models with different security properties, where the convenient one is usually the less controlled one.
Internal information that ends up printed on a customer document
The values that reach a customer-facing document because they were available, which are usually internal identifiers, judgements and debugging aids.
Personal data in a document that will be emailed
What a document discloses once it is attached to a message, which is more than the recipient asked for and travels further than the message.
Why a black rectangle over text does not redact it
The most consequential misunderstanding in document handling: covering text with a shape hides it visually and leaves it entirely intact in the file.
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.