Parse and issue OIDC ID tokens

1 files changed, 102 insertions, 0 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index 70df6d4..c9c164a 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -118,11 +118,77 @@ are @emph{strings}, but we hope that in the future SRFI-180 will be
 more closely respected.
 
 @menu
+* The ID token::
 * The access token::
 * The DPoP proof::
 * Generic JWTs::
 @end menu
 
+@node The ID token
+@section The ID token
+
+The ID token is a special JWT that the application keeps for
+itself. It is signed by the identity provider, and contains the
+following claims:
+
+@table @emph
+@item webid
+the URI of the user’s webid;
+@item iss
+the URI of the identity provider (issuer);
+@item sub
+the username (the webid-oidc issuer puts the webid again here, but it
+could be any string);
+@item aud
+the ID of the client application that is intended to receive the ID
+token;
+@item nonce
+some random data to change the signature;
+@item exp
+an UTC time (in seconds) for when the token expires;
+@item iat
+the time when it was issued.
+@end table
+
+There are functions to work with ID tokens in
+@emph{(webid-oidc oidc-id-token)}.
+
+@deffn function id-token? @var{object}
+Check that @var{object} is a decoded ID token.
+@end deffn
+
+The following helper functions convert URIs to the URIs from
+@emph{(web uri)} and times to @emph{(srfi srfi-19)} dates.
+
+@deffn function id-token-webid @var{token}
+@deffnx function id-token-iss @var{token}
+@deffnx function id-token-sub @var{token}
+@deffnx function id-token-aud @var{token}
+@deffnx function id-token-nonce @var{token}
+@deffnx function id-token-exp @var{token}
+@deffnx function id-token-iat @var{token}
+Get the suitable field from the payload of @var{token}.
+@end deffn
+
+ID tokens can be signed and encoded as a string, or decoded.
+
+@deffn function id-token-decode @var{token} @var{[#http-get]}
+Decode @var{token}, as a string, into a decoded token. The signature
+verification will need to fetch the oidc configuration of the claimed
+issuer, and check the signature against the published keys. The
+@code{http-get} optional keyword argument can set a different
+implementation of @code{http-get} from @emph{(web client)}. Return
+@code{#f} if it failed, or the decoded token otherwise.
+@end deffn
+
+@deffn function id-token-encode @var{token} @var{key}
+Encode @var{token} and sign it with the issuer’s @var{key}.
+@end deffn
+
+@deffn function issue-id-token @var{issuer-key} @var{#alg} @var{#webid} @var{#iss} @var{#sub} @var{#aud} @var{#exp} @var{#iat}
+Create an ID token, and encode it with @var{issuer-key}.
+@end deffn
+
 @node The access token
 @section The access token
 
@@ -400,6 +466,22 @@ The @var{value} of the typ field in the DPoP proof header is
 incorrect.
 @end deftp
 
+@deftp {exception type} &incorrect-sub-field @var{value}
+The @var{value} of the sub field is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-iss-field @var{value}
+The @var{value} of the iss field is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-nonce-field @var{value}
+The @var{value} of the nonce field in the DPoP proof is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-htm-field @var{value}
+The @var{value} of the htm field in the DPoP proof is incorrect.
+@end deftp
+
 @deftp {exception type} &not-a-client-manifest @var{value} @var{cause}
 The @var{client-manifest} is incorrect.
 @end deftp
@@ -533,6 +615,26 @@ code.
 The @var{authorization-code} cannot be signed.
 @end deftp
 
+@deftp {exception type} &not-an-id-token @var{value} @var{cause}
+The @var{value} is not an ID token.
+@end deftp
+
+@deftp {exception type} &not-an-id-token-header @var{value} @var{cause}
+The @var{value} is not an ID token header.
+@end deftp
+
+@deftp {exception type} &not-an-id-token-payload @var{value} @var{cause}
+The @var{value} is not an ID token payload.
+@end deftp
+
+@deftp {exception type} &cannot-decode-id-token @var{value} @var{cause}
+The @var{value} string is not an encoding of a valid ID token.
+@end deftp
+
+@deftp {exception type} &cannot-encode-id-token @var{id-token} @var{key} @var{cause}
+The @var{id-token} cannot be signed.
+@end deftp
+
 @node Cannot fetch data on the web
 @section Cannot fetch data on the web
 In the client (local and public parts), resource server and identity