Documentation embedded in this build.

Your computer's credential as a card

In short

For a person with no smart card. On Linux, authbox-agent shows the credential this box issued to your computer as a PIV card in a virtual reader, behind a PIN you set, so Firefox, ssh and every other smart-card tool use it the way they use a real card, and the key never leaves the credential store.

What it is for

The smart-card scenario is for a person who already carries a card. This one is for a person who does not. The command-line tool enrolls your computer for a certificate of its own, and the agent that renews it can also show it to the operating system as a smart card in a reader. Then the browser's certificate prompt, ssh and every program that reads cards sees one, asks for its PIN, and signs with the key that never left your credential store. It is the same key and certificate, not a copy, and it is not hardware: the card names itself virtual, and a deployment that demands hardware refuses it.

The PIN is yours. There is no default, and the card refuses every PIN until you set one. Three wrong PINs block it, and clearing the block takes the credential store's passphrase, which stands in for a card's unblocking key. The agent dials the reader driver on your own machine and listens on nothing. Without the -card flag, nothing on this page exists.

The topology

Your computer, the reader driver pcscd loads, and the door the credential is presented at.

   YOUR COMPUTER
   +-----------------------------------------------------------+
   |  credential store ----- key, certificate -----> authbox-agent -card   |
   |  (passphrase, card PIN)                              |  dials         |
   |                                                      v                |
   |  Firefox, ssh, pkcs11-tool  ---- OpenSC ---->  pcscd + virtual reader |
   +-----------------------------------------------------------+
                                     | the card's certificate, PIN entered once
                                     v
                                   DOOR  ---->  AUTHBOX  ---->  decided as the
                                                              credential it is

Stand it up

The two tools come out of the published tools image, and the reader driver and OpenSC out of your distribution's packages (on Debian or Ubuntu: pcscd, vsmartcard-vpcd, opensc).

$ docker create --name tools authboxus/authbox-tools
$ docker cp tools:/authbox-agent . && docker cp tools:/authboxclient . && docker rm tools
$ sudo apt-get install pcscd vsmartcard-vpcd opensc
$ ./authboxclient enroll -server https://enroll.authbox.example.com -invitation <token>
$ ./authboxclient card set-pin
$ ./authbox-agent -passphrase-file pass.txt -card

Enroll first. authboxclient enroll is the enrollment guide's first path: an invitation from your administrator, a key generated on your machine, a certificate issued by the box. The intake's public name carries a publicly trusted certificate, so no -ca is needed. The agent presents that credential, and with several, -card-credential names the one.

Then use it. opensc-tool -l lists the reader with a card in it. In Firefox, add /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so once under Settings, Privacy & Security, Security Devices, and the site's certificate prompt shows the card. For SSH, ssh -I with the same module. authboxclient card status shows whether a PIN is set and how many tries are left; card change-pin changes it and card unblock clears a blocked card with the store's passphrase.

What the smoke proves

The scenario tier stands up the box and a door, enrolls a credential the way the tool leaves it, and starts the agent with -card in a Debian container holding nothing of AuthBox's but the two tools. In order: OpenSC lists a PIV card in the reader; pkcs11-tool signs with the card and the signature verifies under the credential store's own key; ssh-keygen reads the same key through OpenSC's module; curl presents the card at the door and is answered, while a request with no certificate is not; and three wrong PINs block the card until authboxclient card unblock clears it. Firefox at the door and ssh -I at an SSH door are a check by hand.

Read on

Enrolling with AuthBox is the user guide's section: what to install, the PIN commands, and what the card is not.
Sign in with the card you already carry is the door the same way around, for a card from an authority this box never ran.
SSH access to your hosts is where ssh -I with the card leads.