Documentation embedded in this build.

Your own certificate authority for a team

What it is for

A team that wants its own certificates and has no public key infrastructure to hang them on. There is no configuration file to write by hand: the first boot serves a wizard on the loopback address, asks what this deployment is for and who runs it, and ends by standing up a certificate authority, writing one configuration file, and printing a single bootstrap administrator invitation.

Invite the rest of the team from the console; each person enrols with a key that never leaves their machine, and from then on the certificate is the login. Nothing is hosted for you, nothing phones home, and the root you just made stays on the host you made it on. If the wizard is interrupted it has applied nothing — there was nothing running yet to disturb.

This is not a hosted certificate authority. No key material and no directory ever leaves the host.

The topology

One host, and a straight line through it. The wizard runs on the loopback address, produces a certificate authority, which produces invitations, which produce the people the console is then for.

   one host, nothing else
   +--------------------------------------------------------------+
   |  127.0.0.1:8090   ->  certificate    ->  invitations  ->  console
   |  the first-boot       authority          one per            the team,
   |  wizard               (the root          person             each with
   |                        stays here)                          their own key
   +--------------------------------------------------------------+

The setup listener binds loopback and serves nothing but the wizard and the embedded documentation; it closes the moment the file is written, and no other listener starts while it is running.

Stand it up

$ authboxd -setup -config /etc/authbox/authbox.yaml   # the wizard, on 127.0.0.1:8090
$ make demo                                           # a worked deployment under ./demo
$ make all-in-one                                     # the authority, console and invitations

The first is what you run on a host of your own; open http://127.0.0.1:8090 and answer the questions. The other two are worked deployments from a checkout, for looking before you configure: make demo needs no network at all, and make all-in-one needs docker.

What the smoke proves

The wizard's own rules are proved against the compiled binary in test/integration/setup_test.go: it refuses to serve off loopback without a one-time token (TestSetupOffLoopbackNeedsAToken), it opens no other listener while it runs (TestSetupModeOpensNoOtherListener), and it refuses to overwrite a configuration that is already there (TestSetupRefusesToOverwriteAConfiguration). authboxctl setup, for a host with no browser, is proved to round-trip into a deployment that actually starts, and to create nothing when it is asked not to write.

make all-in-one then runs the composition's enrolment phase against real containers: the authority the bring-up minted issues real certificates, an invitation is created and claimed, and a person who holds the result reaches the console at the address the epilogue prints. make demo does the same on one machine with the cable out.

Read on

• flag:-setup pins the wizard itself: loopback, a token for anything else, no second listener, nothing applied to a running deployment.
• make:demo pins that a complete worked deployment builds and serves from a checkout with no network.
• make:all-in-one pins the authority, the console and the invitation path in containers.
• The operator runbook is the first boot, in the operator guide: the loopback rule and the token, the three key custody answers, what to do with the bootstrap invitation, and the enclave path with no browser.
• Enrolling with AuthBox is the page to hand the rest of the team.