AuthBox

Documentation embedded in this build.

The demo

In short

The demo is one deployment you walk in acts: ask for access, enroll your laptop, present its credential as a card, log in over SSH with it, file mock documents onto a sealed shelf the machine holding them cannot read, and open what the demo holds for you. A scenario proves each act.

What it is for

The demo is the product doing its work rather than showing its console. One deployment, demo.authbox.us, runs the box and every companion beside it, and you walk it in acts, in order, with your own laptop. Each act below says what you do, what the product decided and where that decision is written down; what proves each one is under "What the smoke proves".

Every organization, person and document on the demo is invented: the cover site is fictional, the documents are mock, and no level on it marks anything classified. It is an evaluation, and evaluation is free for everybody. The licensing page says what a demonstration is: "A demonstration is the reference deployment brought up live and walked in front of you." This page is the same deployment, walked by you.

The demo in acts: your laptop presents its card at the door, logs in to the mission's machine, and files onto a sealed shelf that machine cannot read.LAPTOPyour cardDOORSERVERmission'sSHELFsealed

The topology

Your laptop, the door every act goes through, and what stands behind it.

   YOUR LAPTOP                        demo.authbox.us
   +------------------+
   | authboxclient    |  card's key   +------+     +--------+   the box, the key
   | authbox-agent    | ------------> | DOOR | --> | AUTHBOX|   access service,
   |   -card          |  (mutual TLS) +------+     +--------+   the store
   +------------------+                  |
                                         +-------> the mission's machine
                                                   (its shelf mounted read-only)

Stand it up

A visitor needs an invitation, so act one is how to ask. There are 7 acts today; an act is added and never rewritten.

Act 1. Ask for access, and enroll from your laptop

Ask on the demo's public page with your name, an address to write to and one line on why. The owner answers with an invitation for a name they choose, and you enroll your computer with it through the public intake, which needs no file of ours to trust.

$ open https://enroll.demo.authbox.us/ask
$ authboxclient enroll -server https://enroll.demo.authbox.us -invitation <token>

The owner decided you may enroll, and under which name; the intake issued the certificate to that name and no other. Written down in the audit row of the request (access-request:file) and the audit row of the answer (access-request:invite).

Act 2. Present your computer's credential as a card

Set a PIN, and the agent shows the credential to your computer as a smart card in a reader. Your browser and curl present it at the demo's door as they would a real card.

$ authboxclient card set-pin
$ authbox-agent -passphrase-file pass.txt -card
$ opensc-tool -l

The door admitted the card as the credential it is, and refused a request that presented nothing. Written down in the receipt on every answer (X-AuthBox-Receipt).

Act 3. Log in over SSH with the card

One line logs in through the door to the machine the box stood up for your mission, with a certificate the box issued for the card's own key by possession and no second invitation. The same key is the card and the SSH key.

$ authboxclient ssh member@<server>.ssh.demo.authbox.us

The box certified the card's key with one principal per mission you hold; the door let a member through to the mission's machine and refused a stranger. Written down in the audit row of the certificate (ssh:issue) and the door's row of the connection (tcp:open).

Act 4. File mock documents onto the shelf

File three mock documents into your mission's shelf at the mock SECRET level, which is sealed, and one into a shelf at mock CONFIDENTIAL, which is not. The address names the level.

$ open https://store.demo.authbox.us/
$ curl -T briefing.txt https://store.demo.authbox.us/s/<mission>/briefing.txt
$ authbox-file notes.txt

The store sealed each document at the level its address names, wrapped its key to the key access service, and kept no key itself. Written down in the sidecar beside each sealed document (.authbox-meta).

Act 5. See that the machine cannot read it, and open it as yourself

On the mission's machine the shelf is ciphertext beside a sidecar that names its mock marking. authbox-open opens it there for you, by the certificate you logged in with; on your laptop, your own credential opens a copy.

$ cat /srv/mission/briefing.txt.authbox-meta
$ authbox-open /srv/mission/briefing.txt
$ scp member@<server>.ssh.demo.authbox.us:/srv/mission/briefing.txt* .
$ authboxclient open briefing.txt

The key access service released the key to a member cleared to the mock level, on the machine by the certificate they logged in with, and refused a person cleared lower. Written down in the key access service's row, a grant or a refusal (kas:rewrap).

Act 6. See what the demo holds for you

Open the store's front page and your own pages in the portal: the folders open to your identity, what the demo holds about you, the missions you may ask for, each stamped with its mock marking, and your own requests.

$ open https://store.demo.authbox.us/
$ open https://me.demo.authbox.us/me
$ open https://me.demo.authbox.us/missions
$ open https://me.demo.authbox.us/requests

The box answered every page as you, relayed through the door and the companion you opened; a mission you are not cleared to know about is absent, not hidden. Written down in the portal's row of each page, under its path (/me).

Act 7. Present the card you already carry

Bring a CAC or a Treasury-family PIV card to https://card.demo.authbox.us/, which serves a certificate your machine already trusts. The door admits only the card's authentication certificate, checked against its issuer's own list, fetched ahead of time. The box writes a record for you on first sight; once an administrator places that record in a group, the card route lets you in from then on.

$ open https://card.demo.authbox.us/
$ open https://console.demo.authbox.us/ui/entities
$ open https://console.demo.authbox.us/ui/groups/<group>

The door admitted a card another authority issued, on its authentication certificate alone, and the box recorded the person; the administrator decided which group the record joins, and the route permitted from that moment. Written down in the audit row of the record, on first sight (entity:first-seen) and the door's row of the card route, outcome (permit).

What the smoke proves

Each act is proved by the steps of a scenario that stands the product up from its images and drives it as a visitor would, or, where no scenario drives a part yet, by the unit test named.

Read on