This documentation describes AuthBox v0.3.0-133-g71cb5564.

Hand out classified records only to the cleared

In short

Hand records of mixed classification only to the people cleared for each. The application labels every answer with one header; the front door compares the label with the caller, replaces whole what they are not cleared for with a plain refusal, and signs a receipt for what it allows.

What it is for

You have an application holding records that are not all for the same audience — case files, personnel records, assessments, anything with a classification on it. Put it behind the front door and have it say, on every answer it gives, which classification that answer carries. One header, one line of code, no client, no credential, no call to us.

Two people ask the same front door for the same six records; the application behind the door answers each request with a label naming that record's classification and never decides anything itself; the door compares the label against what each person is cleared for, so the person cleared for everything receives all six records with a receipt naming what was compared, and the person cleared only to the lowest level receives two of them and a plain refusal for the rest, with the reason only in the log

The door compares that label against the person asking and against every machine the answer passes through, using the same directory and the same rules that decide everything else here, and any answer they are not cleared for is replaced whole with a plain refusal — not trimmed, not blurred, not partly sent. The refusal looks exactly like being refused the page itself, so nobody learns what they missed; the reason is written into the log instead, naming which rule failed and which link in the chain failed it.

Receipts, and other ways

What comes back when it is allowed carries a signed receipt naming what was compared, so an auditor can show that a record left the building to somebody cleared for it. If your application cannot be changed, the door will take a list of paths and what each one carries instead, and you change nothing at all. And if you would rather your application decide for itself — because there is no door in front of it, or because one answer mixes several classifications — the same three verbs ship as a library in Go and TypeScript, where a record cannot be handed out at all until the question has been asked and answered.

This is not content inspection. Nothing reads the record, guesses its classification, or edits it on the way out.

The topology

Two people ask the same door for the same records. The application answers each request with a label and decides nothing itself; the door compares.

   person cleared for everything  --+
                                    |     FRONT DOOR              APPLICATION
                                    +-->  compares the label  <-> answers with a
   person cleared to the lowest  ---+     against the caller       label on every
   level only                             and every machine        answer, and
                                          in the chain             decides nothing

   result: everything, with a receipt naming what was compared
           two records, and a plain refusal for the rest — the reason only in the log

Stand it up

$ docker run --rm authboxus/authbox-eval -evaluate -scenario door -print docker | sh

A front door in front of it: the door that compares the label is that evaluation's, and the evaluation image's four people are cleared at four levels of one ladder, from eval-admin at the top to eval-service at the bottom. What no evaluation carries yet is an application that labels its answers: the record showcase — six records at three classifications — is the worked composition's demonstration application and is not published, so the marked response itself is proved from the source and described here. The evaluation runbook says what that evaluation stands up and what its people may open today.

What the smoke proves

The composed run walks the whole path with real containers, and what only a composition can show is that the label the shipped library writes is the label the door reads — two implementations of one grammar — that the levels being compared are the staged deployment's own, and that the door's own entity is a link in the chain, not a bystander that waves the answer through. Each half is proved on its own beside it: the door's route behavior in the proxy's own tests, the application's in the showcase's own package.

Three things are asserted every run. An answer above the caller's level is replaced whole, and the body that comes back is the same plain refusal a missing page produces. An answer within it arrives with a receipt naming exactly what was compared. And the reason for the refusal is in the audit record — naming the rule and the hop — and nowhere in the response.

Read on

requirement:AB-581 pins that the application states a classification and decides nothing.
requirement:AB-582 pins the whole-body replacement and the refusal that tells the caller nothing.
requirement:AB-584 pins the receipt that names what was compared.
Each requirement's statement and the mutation that proves it are in Decisions, rules and settings, in the accreditation package.
The explainer is Marked data, end to end, in the operator guide: the six links a classification is protected by, who owns each, and — at the same length — what the mechanism does not do.
The sealed records scenario is what to read when the record has to stay protected after it leaves.