tokenserver/README.md

# 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.
1.  `luci_machine_tokend` executable periodically runs and uses the private key
    and certificate when calling `MintMachineToken` gRPC method of the token
    server.
1.  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).
1.  The bot uses this token when sending requests to Swarming (by putting it
    into `X-Luci-Machine-Token` header).
1.  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).