From 17756eb43e8bf7946de521a284514b860e1e9b1e Mon Sep 17 00:00:00 2001 From: Fabio Huser Date: Sun, 17 Apr 2016 12:04:15 +0200 Subject: [PATCH] Clarify kid format for JWT token auth in docs The kid value can have an arbitrary format according JOSE specification, but Docker distribution expects a specific format (libtrust fingerprint) to work. This is not written in the documentation so far and is only mentioned in the libtrust source code itself. Signed-off-by: Fabio Huser --- docs/spec/auth/jwt.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/spec/auth/jwt.md b/docs/spec/auth/jwt.md index f627b17a..87de62af 100644 --- a/docs/spec/auth/jwt.md +++ b/docs/spec/auth/jwt.md @@ -69,8 +69,17 @@ Token has 3 main parts: The header of a JSON Web Token is a standard JOSE header. The "typ" field will be "JWT" and it will also contain the "alg" which identifies the - signing algorithm used to produce the signature. It will also usually have - a "kid" field, the ID of the key which was used to sign the token. + signing algorithm used to produce the signature. It also must have a "kid" + field, representing the ID of the key which was used to sign the token. + + The "kid" field has to be in a libtrust fingerprint compatible format. + Such a format can be generated by following steps: + + 1. Take the DER encoded public key which the JWT token was signed against. + + 2. Create a SHA256 hash out of it and truncate to 240bits. + + 3. Split the result into 12 base32 encoded groups with `:` as delimiter. Here is an example JOSE Header for a JSON Web Token (formatted with whitespace for readability):