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 that card, file mock documents onto a sealed shelf, and see that the machine holding them cannot read them while your own credential can. A scenario the repository runs 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 5 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. Ask the box to certify the card's own key for SSH, by possession and with no second invitation, then log in through the door to the machine the box stood up for your mission. The same key is the card and the SSH key.

$ authboxclient ssh-cert
$ 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

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 with your own credential. On the mission's machine the shelf is ciphertext beside a sidecar that names its mock marking, and the machine cannot open it. Copy the two files to your laptop and open them there with your own credential.

$ cat /srv/mission/briefing.txt.authbox-meta
$ authboxclient 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 and refused a person cleared lower; the machine holding the file holds no credential and was told so. Written down in the key access service's row, a grant or a refusal (kas:rewrap).

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