diff options
Diffstat (limited to 'doc/webid-oidc.texi')
-rw-r--r-- | doc/webid-oidc.texi | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi index a435c33..7a1b6ea 100644 --- a/doc/webid-oidc.texi +++ b/doc/webid-oidc.texi @@ -108,6 +108,47 @@ following, we will only be interested by public-key cryptography. The concatenation of header, dot, payload, dot and signature in base64 is the encoding of the JWT. +Decoded JWT are represented as a pair. The car of the pair is the +header, and the cdr is the payload. Both the header and the payload +use the JSON representation from srfi-180: objects are alists of +@strong{symbols} to values, arrays are vectors. It is unfortunate that +guile-json has a slightly different representation, where alist keys +are @emph{strings}, but we hope that in the future SRFI-180 will be +more closely respected. + +@menu +* Generic JWTs:: +@end menu + +@node Generic JWTs +@section Generic JWTs + +You can parse generic JWTs signed with JWS with the following +functions from @emph{(webid-oidc jws)}. + +@deffn function jws? @var{jwt} +Check that @var{jwt} is a decoded JWT signed with JWS. +@end deffn + +@deffn function jws-alg @var{jwt} +Get the algorithm used to sign @var{jwt}. +@end deffn + +@deffn function jws-decode @var{str} @var{lookup-keys} +Check and decode a JWT signed with JWS and encoded as @var{str}. + +Since the decoding and signature verification happen at the same time +(for user friendliness), the @var{lookup-keys} function is used. It is +passed as arguments the decoded JWT (but the signature is not checked +yet), and it should return a public key, a public key set or a list of +public keys. If the key lookup failed, this function should raise an +exception. +@end deffn + +@deffn function jws-encode @var{jwt} @var{key} +Encode the JWT and sign it with @var{key}. +@end deffn + @node Exceptional conditions @chapter Exceptional conditions @@ -143,6 +184,11 @@ Each JWT type – access token, DPoP proof, ID token, authorization code (this is internal to the identity provider) has different validation rules, and can fail in different ways. + +@deftp {exception type} ¬-json @var{value} @var{cause} +Cannot decode @var{value} to a JSON object. +@end deftp + @deftp {exception type} &unsupported-crv @var{crv} The identifier @var{crv} does not identify an elliptic curve. @end deftp @@ -171,6 +217,40 @@ The identifier @var{crv} does not identify an elliptic curve. @var{key} has not signed @var{payload} with @var{signature}. @end deftp +@deftp {exception type} &missing-alist-key @var{value} @var{key} +@var{value} isn’t an alist, or is missing a value with @var{key}. +@end deftp + +@deftp {exception type} ¬-a-jws-header @var{value} @var{cause} +@var{value} does not identify a decoded JWS header. +@end deftp + +@deftp {exception type} ¬-a-jws-payload @var{value} @var{cause} +@var{value} does not identify a decoded JWS payload. +@end deftp + +@deftp {exception type} ¬-a-jws @var{value} @var{cause} +@var{value} does not identify a decoded JWS. +@end deftp + +@deftp {exception type} ¬-in-3-parts @var{string} @var{separator} +@var{string} cannot be split into 3 parts with @var{separator}. +@end deftp + +@deftp {exception type} &no-matching-key @var{candidates} @var{alg} @var{payload} @var{signature} +No key among @var{candidates} could verify @var{signature} signed with +@var{alg} for @var{payload}, because the signature mismatched for all +keys. +@end deftp + +@deftp {exception type} &cannot-decode-jws @var{value} @var{cause} +The @var{value} string is not an encoding of a valid JWS. +@end deftp + +@deftp {exception type} &cannot-encode-jws @var{jws} @var{key} @var{cause} +The @var{jws} cannot be signed. +@end deftp + @node GNU Free Documentation License @appendix GNU Free Documentation License |