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

Your own card, from its own authority

In short

For a person who holds a real CAC or PIV card: the evaluation image carries the DoD PKI's and the U.S. Treasury PKI's own certificates as the card's issuer sets, fetches their revocation lists from the addresses on the card, mints nothing, and records the card holder on first sign-in.

What it is for

The smart-card scenario proves the door against a stand-in authority the image mints. This one trusts the real authorities, two of them, each carried in the image as an issuer set of its own: the DoD PKI's roots and ID CAs, as DISA publishes them, as dod-id; and the U.S. Treasury PKI's root and the CAs it has issued, as treasury. The Treasury is a shared service provider, so a PIV card from the Treasury, DHS, NASA, the Social Security Administration or the VA chains to it. Bring a CAC or a PIV card either PKI issued, present it at the door, and you are recorded, with the policies the card carried shown on your own record.

Nothing is minted for the card and nothing is stored about it ahead of time. The box reads the card; it never issues one. A sign-in records the person's name, UPN with EDIPI and FASC-N in this volume, which the teardown deletes.

The topology

The smart-card scenario's two containers, the writer and the front door, with two sets pointed at the real authorities and the lists fetched live.

   DoD ROOT CAs -------- DoD ID CA-nn ------ issues --+
   US Treasury ROOT CA - agency CA (Treasury, -------+-->  YOUR CARD
        |                DHS, NASA, SSA, VA)                |
        | the bundles,        | their lists, fetched from   | sign-in certificate
        | in the image        | the address on the card     v
        v                     v                           DOOR  ---->  AUTHBOX  ---->  RECORD
   /data/pki/cards/dod-id.pem    /data/crl               admits          issues         first seen,
   /data/pki/cards/treasury.pem  (held before any        by chain        nothing        no groups
   (or the ones you mounted)      card is admitted)

Stand it up

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

Bring your card. The banner says which bundle is in force for each set and where: the image's, named by DISA's version or the day the Treasury's was taken, written to /data/pki/cards/dod-id.pem and /data/pki/cards/treasury.pem, or one you mounted there. Pick the card's authentication certificate when the browser asks, and enter the PIN. The door publishes the card's own name, card. under the door's domain on port 8444, and the console is behind it at /ui. The first try works a minute or two after start: each door fetches the revocation lists from the addresses on the card and refuses the card until it holds them, and the lists are large. This is the one scenario that needs the network; an airgapped room copies the lists into /data/crl by the CRL runbook's §2b instead. Before you present the card, the console's Admitted by certificate page (/ui/issuers) says whether the lists are held. Beyond the evaluation, a card holder's browser trusts the public web PKI and never this box's root, so the card's name on a door other people reach is a public name, whose certificate the door orders itself (Public names, §13 of the front door's runbook).

The bundle and the card's age. DISA adds ID CAs a few times a year, and the Treasury adds agency CAs under its root. A card under a CA newer than the image's bundle is refused at the handshake naming the set; mount a fresh bundle, as PEM, at that set's path (-v ./dod.pem:/data/pki/cards/dod-id.pem:ro, or ./treasury.pem at treasury.pem) and the act adopts it. The sets require no policy until a real card has shown what it carries, so any certificate under either chain is admitted for now; the policies read off the first card are pinned afterwards, and the card's signature and e-mail certificates are refused by policy from then on, as the stand-in scenario's already are.

Choose the sets. Both are admitted unless you say otherwise: -issuers beside -evaluate keeps only the sets it names, comma-separated, so -issuers treasury admits Treasury cards alone and writes no DoD bundle, and the recipe the image prints with it hands the flag to the writer. A card enrolls for an AuthBox certificate from the DoD set only, since a deployment names one set to enroll from; when the flag leaves that set out, enrollment moves to the first set kept and the banner says so. The flag is read on the first start only; a deployment of your own chooses its sets in its answers file.

A tester elsewhere. The door's names resolve to the evaluator's own machine, so this is for a card holder sitting at it with a reader. A tester somewhere else needs a deployment on a real name, which is the bring-your-own runbook's smart-card procedure, not a scenario.

What the smoke proves

The evaluation's own proof runs the printed recipe and proves what can be proved without a card: the sets dod-id and treasury are named in the writer's file and the door's alike; each bundle in the volume is byte for byte the one the image carries; the banner tells the evaluator to bring their card; a certificate this box issued is refused on the card's route; and the doors either fetched the lists or said the network was absent, and the smoke prints which. The sign-in itself is the hour with a real card, recorded in plan 193 when it happens.

Read on

Sign in with the card you already carry is the same door against a stand-in, with a card holder the image mints, for a room with no card and no network.
Bring your own directory, PKI and mail is the runbook for a deployment of your own: the anchors file, the issuer set, the policies, the fetcher.
The evaluation runbook says what each container is and how it ends.