Boot Strapping Background

Background: why we need to bootstrap

The authorization cache

For Greenpass to work at all, the authorization cache needs to be running. The authorization cache is implemented by JSDSIAuthServer.jar.

The Greenpass RADIUS server contacts the authorization cache whenever it encounters an EAP/TLS certificate that wasn't issued by the "local" CA (the OpenSSL CA in our test setup, but should be, e.g., the Institutional CA). It extracts the public key from the certificate, hashes it for brevity (see ExtractingAndHashingPublicKeys), and sends it to the authorization cache, asking, "has the principal identified by this public key been authorized to access the network?" The authorization cache uses JSDSI to do all the hairy certificate-chain reduction and signature checking, then sends back a "yes" or "no" answer.

The authorization cache lets the supplicant ("Bob") access the network if it has seen a certificate or certificate chain that delegates (in one or many steps) from the authorization cache's source-of-authority (SOA, or "trust root" or "trust anchor") to Bob. Both Bob and the SOA are identified simply by their public keys (or a hash thereof, in Bob's case). The authorization cache will get a certificate chain for the Bob via one of the following two methods:

1. Alice delegates to Bob: the delegation Web app automatically sends the freshly-generated and signed certificate chain off to the authorization cache. OR,
2. Bob has a cert chain from Alice stored in his Web browser as a cookie: when Bob visits the Greenpass front page, it grabs this cookie and sends it to the authorization cache.

Aside: after Alice delegates to Bob in case (1), Bob can go to the Greenpass front page, which asks the authorization cache for his entire cert chain and stores it in his Web browser as a cookie for longer-term use. Bob can access the network even before obtaining this cookie, however, because his cert chain gets sent to the authorization cache -- which is what the RADIUS server consults -- as soon as Alice delegates to him.

Assumptions of the Greenpass delegation Web app

The Greenpass delegation Web app bootstraps kind of inductively (hence the need for boostrapping, which forms a "base case"...don't worry, you'll see what it means if you keep reading). To delegate from A to B, it just combines three things:

1. A's certificate chain -- of one or more certificates -- which it assumes is stored in her Web browser as cookie greenpass_chain;
2. a new certificate from A to B, generated when A runs the delegation Java applet; and
3. a hexadecimal MD5 hash of B's public key value.

Aside: the hex hash is used later as B's greenpass_hash cookie. It is required by addCertChain() mostly as a leftover sanity check -- i.e., does the new certificate's subject actually match this hash? -- more than anything else. Both the RADIUS server and the Greenpass front page query the authorization cache regarding a user's permissions by sending it this hash, however, so it serves as a fast index into the hash table of certs.

What Boostrapping Is

The assumption just discussed has a consequence: only a user who already has a certificate chain of length at least 1 can use the delegation Web app. The SOA, therefore, can't use the Web app because it has a certificate chain of length 0.

Bootstrapping, then, consists of three steps:

1. generating a public key file in SPKI format (see ExtractingAndHashingPublicKeys) that can be fed to JSDSIAuthServer as its SOA by providing the filename as a command-line argument;
2. generating at least one SPKI certificate chain -- without using the delegation Web app -- that delegates from the SOA to a living, breathing user (see GeneratingSpkiCertificates); and finally,
3. getting this certificate chain (of only one certificate) to the flesh-and-blood user's Web browser as a cookie so he/she can use it with the Web-based delegation interface.

How To Bootstrap

Steps (1) and (2) are discussed on the pages referenced above, ExtractingAndHashingPublicKeys and GeneratingSpkiCertificates GeneratingSpkiCertificates. Step (1) needs to done very rarely -- when the intended SOA changes, for example. Step (2) can be done just as rarely as step (1), but you might need to designate new "depth-1" users (where the SOA is "depth-0") sometimes, or renew their expired certificates.

Step (3) is accomplished by uploading the depth-1 user's certificate to the authorization cache; she can then visit the guest Web app and click straight through it without waiting for a delegator. The final page will find her certificate "chain" already in the authorization cache -- just as if she were a depth-2+ user that had recently been delegated to -- and install it in her Web browser as a cookie.

Once you have a certificate delegating from the SOA to a depth-1 user, along with a hex hash of her public key, use the bootstrap.py file in the jdaemons/scripts directory to upload her cert to the authorization cache. Run it as follows, e.g.:

$ ./bootstrap.py f568014cb04693a90822f255c192db02 RootToAlice.spkicert

This script really just uses XML-RPC to call the 2-argument version of the authorization cache's addCertChain() method. (Hence the need for a hex hash, which again is just a relic of the way Nick wrote that method. Maybe we could just write an easier script that calculates that hash automatically from the public key already contained in the certificate?)

IMPORTANT NOTE: Once Alice's certificate chain gets sent to the authorization cache and she visits the Greenpass Web apps to pick it up as a cookie, you won't need to run this script again unless Alice manages to misplace her cert chain (e.g., by deleting the cookie).