README

The Token Server

This directory contains an implementation of a service that generates and validates various tokens used in LUCI authentication protocol.

In particular, this service implements so called "machine tokens" used for authenticating Swarming bots:

1. Each bot has a TLS private key and a certificate, signed by some trusted CA.
2. luci_machine_tokend executable periodically runs and uses the private key and certificate when calling MintMachineToken gRPC method of the token server.
3. The server verifies that the certificate is signed by a trusted CA, that it is not expired or revoked, and that the request was signed by the corresponding private key. If everything checks out, the server generates a short lived (1h by default) stateless machine token (basically, certificate Common Name and some additional data signed by the token server's own private key).
4. The bot uses this token when sending requests to Swarming (by putting it into X-Luci-Machine-Token header).
5. Swarming checks the signature of the token (using only local crypto) when authenticating requests from bots.

Layout

• api: gRPC protocol definition and autogenerated Go code.
• appengine: server implementation (runs on Standard GAE).
• auth/machine: implementation of the token checking logic that can be used by backends that want to use machine tokens. Swarming service uses same logic (implemented in Python).
• client: library that wraps TokenMinter gRPC API into a usable form. It implements logic for reading and using TLS certificate and private keys.
• cmd/luci_machine_tokend: executable deployed on all bots. It knows how to generate machine tokens given a TLS certificate and private key.
• testing: local integration test that checks interaction of luci_machine_tokend with the server (and some other things, such as certificate revocation list updates).