Documentation
¶
Overview ¶
Package assertion verifies what a client signs to mint a token: a short-lived JWT, signed by the private half of a key the account registered, saying which key is asking and what it is asking of.
The shape is RFC 7523's client assertion, which every JOSE library and every service-account flow already speaks, and it takes one request: the client signs a statement with a lifetime and an identifier of its own, rather than fetching a challenge to sign. A challenge would buy freshness that the expiry already bounds and the remembered identifier already enforces, at the price of an unauthenticated endpoint handing out state to anyone who asks for it.
Index ¶
Constants ¶
const Leeway = 60 * time.Second
Leeway is what a client's clock may be out by, in either direction.
Applied by hand, because the claims validator compares times exactly: left to it, an assertion issued a second into the future would be a forgery and one written by a runner whose clock is a minute behind would arrive already expired. Neither is, and both happen.
const Lifetime = 5 * time.Minute
Lifetime is the longest an assertion may be presentable for. Short because it needs to survive only the one request it is made for, and because every second of it is a second in which a copy taken off the wire is as good as the original.
const Type = "api-key+jwt"
Type is what an assertion must say it is, in the JWS header.
It is what keeps the two kinds of token this service handles apart in the one place where they could otherwise meet: a session token signed by the service, whose signing key somebody had registered as their own API key, would verify as a signature and then be read as a mint request. It carries no "typ" of this kind, so it is refused before its claims are looked at.
Variables ¶
This section is empty.
Functions ¶
func Subject ¶
Subject reads the "sub" of an assertion without verifying anything, which is how the key it claims to be from is looked up.
Nothing about the token is trusted at this point. What comes back is used to fetch a key, and the signature is then checked against that stored key: a key the token itself carried would let anyone mint for any subject by bringing their own.
Types ¶
type Assertion ¶
Assertion is a verified mint request: which key made it, and what identifies it.
It carries no expiry. How long the identifier has to be remembered is decided where the record is written, from the server's own clock; what a client writes in "exp" says whether the assertion is still presentable, and nothing past that.
func Verify ¶
func Verify( tokenString string, key *public_key.Key, audience string, now time.Time, ) (*Assertion, error)
* Verify checks an assertion against a key that was registered, and returns what the caller needs * to stop it being presented twice. * * What is checked, and why each of them: * * - the signature, by a verifier built from the stored key, whose name is the algorithm the key * was registered as -- so an assertion whose header names another algorithm is refused rather * than verified under one; * - "typ", so that no other token this service signs or accepts can be presented here; * - "sub", the key's id, so an assertion made for one key cannot be replayed under another's * lookup -- and "iss", the same id, where a client sends it, which RFC 7523 says to do and * which adds nothing "sub" has not already settled; * - "aud", where a client sends one, the service's own origin -- so an assertion made for the * development service cannot be presented to the production one; * - "iat" and "nbf", where a client sends them, neither in the future: an assertion cannot have * been made later than it arrived, nor say it is not yet usable and be used; * - "exp", required, inside the lifetime, so a captured assertion stops working; and * - "jti", required, which is what the caller then remembers for as long as an assertion can be * presented for. * * Only "sub", "exp" and "jti" have to be there. The rest are checked when they are there and not * missed when they are not, which is a weaker rule than it sounds: every claim is inside what was * signed, so leaving one out is open to the key's holder alone. Whoever captures an assertion can * relay it but cannot edit it -- strip a claim and the signature no longer verifies. A client that * omits "aud" gives up deployment binding for its own assertions and for nobody else's.
Source Files