AuthBox

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 agent as a card: the credential this box issued to your computer, shown to the operating system as a smart card in a reader, so the browser and ssh present it at the door as they would a real one.AGENTits own credentialREADERvirtualDOOR

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, Ubuntu or Pop!_OS: 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
$ sudo systemctl restart pcscd
$ ./authboxclient enroll -server https://enroll.authbox.example.com -invitation <token>
$ ./authboxclient card set-pin
$ ./authbox-agent -passphrase-file pass.txt -card

Restart pcscd once the driver is installed. pcscd is usually already running when the package arrives, and it reads its readers when it starts. The driver ships two readers, Virtual PCD 00 00 on port 35963 and Virtual PCD 00 01 on 35964. The agent dials the first, so opensc-tool -l shows the card in Virtual PCD 00 00 and the second reader empty.

Ask for an invitation that issues at once. With a subject named, the console's invitation form issues the certificate in the same response. If yours waited for an administrator, run authboxclient collect after they approve; the agent also collects when it starts. Enrolling is the enrollment guide's first path, and the intake's public name needs no -ca. With several credentials, -card-credential names the one the card presents.

If the card vanishes

The card appears, then vanishes a minute later. A distribution's unit runs pcscd --foreground $PCSCD_ARGS, and /etc/default/pcscd sets --auto-exit: pcscd leaves a minute after its last client. The agent then logs removed from the virtual reader: the driver closed the connection and dials again after one second, then two, then four, so the card is back as soon as pcscd is. To keep pcscd running, override the unit with sudo systemctl edit pcscd:

[Service]
EnvironmentFile=
ExecStart=
ExecStart=/usr/sbin/pcscd --foreground

Then sudo systemctl restart pcscd.

Then use 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. The card is admitted where this box's own credentials are: the console's own door, such as console.<domain>, and not a door that admits only PIV policy certificates, such as card.<domain>. For SSH, authboxclient ssh-cert asks the box's SSH CA to sign the card's key and prints the two lines for ~/.ssh/config; -ssh-cert on the agent keeps it fresh. authboxclient card status, card change-pin and card unblock manage the PIN.

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. A stock sshd beside the endpoint trusts the box's own SSH CA, read from GET /enroll/ssh-ca. The agent's -ssh-cert and authboxclient ssh-cert each get a certificate over the card's key by possession, and sshd admits that key through PKCS11Provider paired with the certificate, with the credential's subject as the key id. It refuses the same key offered raw, and the box refuses to certify a fresh key offered over the card's credential. Firefox at the door is a check by hand.

Read on