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

Sign in with the card you already carry

In short

For people who already carry a PIV or CAC card issued by an authority this box never ran. The door admits the card's sign-in certificate, refuses the same card's signature certificate, checks the issuer's own revocation list, and records a person it has never seen for an administrator to place in a group.

What it is for

Some people already hold a smart card — a PIV card, a CAC — from an authority that is not this box: a federal agency's PKI, a large company's badge system. They should sign in with it, and this box should issue them nothing to do so. AuthBox trusts the card's authority as a named issuer set beside its own, and every door of the deployment admits the same set.

A card carries several certificates chained to one authority. The door admits only the one whose policy says it is for signing in, and refuses the card's signature certificate at the handshake. It checks the issuer's own revocation list, fetched ahead of time from the address each certificate names, never during the handshake. A person nobody has seen is recorded on first sign-in with no group at all, and an administrator places the record where it belongs.

Under that recording rule a card holder is an entity of this deployment, so every grant made to "everyone" reaches them the moment they first sign in. A deployment that does not want that refuses unknown cards, or grants to named groups.

This is not an authority. AuthBox reads the card; it never mints one.

The topology

One authority you already have, one box, and the doors in front of it.

   THEIR ID CA  --publishes its list at the address on each card-->  fetched ahead
        |                                                                 |
        | issued                                                          v
   the card ---- sign-in certificate ---->  DOOR  ---->  AUTHBOX  ---->  RECORD
                 (policy: PIV auth)          |           issues           first seen,
                                             |           nothing          no groups
   the card ---- signature certificate --X   refused at the handshake

The command line, SSH and the companions take an AuthBox certificate the card enrolls for: a card holder presents the card once at the enrollment listener and leaves with a certificate for the places a card cannot reach. Signing documents with a card is not built (plan 155 records why).

Stand it up

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

A card from another authority. The evaluation image mints a stand-in authority — a root and one ID CA, named "Stand-in" — and a card holder whose certificate carries the PIV authentication policy and a user principal name. Import eval-card-holder.p12 from the credentials page on port 8080, open the console on port 8443 at /ui, and you are recorded; the door on port 8444 publishes the card's own name, card. under the door's domain.

The evaluation's card is a stand-in PKCS#12 file; a real card is the browser's own, and the recipe is the same with the issuer set pointed at the real authority's anchors. The stand-in's lists are signed once, so the evaluation's answers let every door hold a list for thirty days rather than one (crl_max_age: 720h); after that every door refuses the card as stale, and a fresh volume is a fresh stand-in. The evaluation runbook says what each container is and how it ends.

What the smoke proves

The scenario tier stands up the box, a door and a static server publishing the stand-in's lists at the addresses its certificates name. In order: the card holder signs in at the box and is recorded; an administrator places the record in a group; the door's route that requires the card's sign-in policy admits it; the same person's signature certificate is refused at the handshake; a revoked card is refused once the fetcher's round brings its list, and the refusal is in the audit chain; and the card holder enrolls with the card and is answered with the certificate it issued.

The evaluation's own proof runs the printed recipe: the card holder is answered as a person with the card's attributes and a first-seen record on the audit chain, the signature certificate is refused, and the door's card route admits the card and refuses a certificate this box issued.

Every proof here is against the stand-in until a real card is tried.

Read on

Bring your own directory, PKI and mail is the runbook: the anchors file, the issuer set, the dictionary's two card rows, importing the people you already know, and the fetcher with its airgapped form.
Enrolling with AuthBox covers enrolling with the card for a certificate the command line and SSH accept.
Bring the organization you already have is the same idea for a directory and a PKI you run yourself.