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

A file that stays classified after it is copied

In short

Records that stay classified after they leave you, whether copied to a partner, a share, a backup or a laptop that goes missing. Each is sealed as it is written, its classification locked to the encryption, and a small door that holds keys and no data hands the key only to the cleared.

What it is for

You hand out records that must stay classified after they leave you — a file sent to a partner, dropped on a share, taken away on a backup, or sitting on a laptop that later goes missing. Seal each one as you write it: the record is encrypted, the classification is written into it and locked to the encryption, and the key is handed to a small door that holds keys and no data.

One classified file is sealed once and then copied everywhere — a laptop, a backup, a partner's share — and every copy is unreadable on its own; two people ask a key door for the key that opens it, and the door asks the same directory that decides everything else here: the cleared person receives the key and reads the file, the person who is not cleared is refused and holds only ciphertext, and the door itself never sees the file and keeps no copy of any key

How the key is released

From then on the file protects itself. Anybody can copy it and nobody can read it; to open one, a person asks that door, and the door asks the same directory that decides everything else here whether that particular person is cleared for that particular record — and releases the key only for that one request, to that one person. Your application never holds a key that opens what it just handed out, the door never sees the record, and every ask, granted or refused, is written into a log that is the only record anywhere that a key moved.

What this does not do is follow the file after somebody cleared has opened it — and we say so on the page that explains it, because the point is not that nothing can leak, it is that a copy on its own is worth nothing.

This is not a rights-management agent on anybody's machine. Nothing of ours is installed where the file goes, and nothing follows a plaintext once somebody cleared has opened it.

The topology

One record is sealed once and copied everywhere; a separate door holds the key and decides each opening on its own.

   SEALED RECORD ---> a laptop        (ciphertext)
        |        ---> a backup        (ciphertext)
        |        ---> a partner share (ciphertext)
        |
        |   "may this person open this record?"
        v
   KEY DOOR  <--- asks --->  THE SAME DIRECTORY that decides everything else
   holds one key
   and no data              cleared     -> the key, for that one request
                            not cleared -> refused; they hold ciphertext

The door never sees the record and keeps no copy of any key it released.

Stand it up

$ docker run --rm authboxus/authbox-eval -evaluate -scenario companions -print docker | sh
$ docker logs writer

The server with its helpers brings the key access door and the object store up beside the box and the front door, each on its own image, on one volume the box's first boot writes their files into. An object filed at a sealed level is ciphertext in the store's volume and is opened by the key access door only for a holder of its mission. The evaluation runbook says which port each one answers on and how it ends.

What the smoke proves

The rewrap's own ordering and every refusal are proved beside the key access door, the seal-and-open round trip in the marked-data library, and the compiled binary against a real authority. The evaluation's own proof waits for every companion to be ready on its own health check. What only a running composition shows is the part that no unit test can reach:

Three files agree about one attribute authority — the writer's setting, the door's own, and the showcase's flag. A deployment where they disagree looks exactly like a working one until the first release is refused.
The wrapping key the bring-up generated is the key identifier every manifest names.
The front door carries the requester's certificate to the key door, rather than its own, so the door decides about the person and not about the hop.
A sealed body handed freely down an unmarked route to an uncleared caller is still ciphertext in their hands — which is the whole claim, demonstrated rather than asserted.

Read on

requirement:AB-592 pins that the classification is written into the record and locked to the encryption.
requirement:AB-595 pins that the key is released per request, per person, against the same directory.
requirement:AB-597 pins the log that is the only record anywhere that a key moved.
Each requirement's statement and the mutation that proves it are in Decisions, rules and settings, in the accreditation package.
The operator runbook is the key access door, in the operator guide: what that container holds — one private key and no data — and the three configuration facts a refused release is almost always one of.
The classified records scenario is the shape for records that never leave the door.