Implement JWS encoding and decoding

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} &not-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} &not-a-jws-header @var{value} @var{cause}
+@var{value} does not identify a decoded JWS header.
+@end deftp
+
+@deftp {exception type} &not-a-jws-payload @var{value} @var{cause}
+@var{value} does not identify a decoded JWS payload.
+@end deftp
+
+@deftp {exception type} &not-a-jws @var{value} @var{cause}
+@var{value} does not identify a decoded JWS.
+@end deftp
+
+@deftp {exception type} &not-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