JWK: document it, and use GOOPS

1 files changed, 149 insertions, 0 deletions

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index cf413af..8004d3c 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -296,6 +296,7 @@ more closely respected.
 * The access token::
 * The DPoP proof::
 * Generic JWTs::
+* Public-key cryptography::
 @end menu
 
 @node The ID token
@@ -524,6 +525,154 @@ exception.
 Encode the JWT and sign it with @var{key}.
 @end deffn
 
+@node Public-key cryptography
+@section Public-key cryptography
+
+Some functions require a key, or a key pair, to operate. The
+@emph{(webid-oidc jwk)} module provides you with everything required
+to manage keys.
+
+@deftp {Class} <private-key> ()
+This is the base class for a private key. You need it to issue
+signatures.
+@end deftp
+
+@deftp {Class} <public-key> ()
+This is the base class for a public key. You need it to check
+signatures.
+@end deftp
+
+@deftp {Class} <key-pair> () @var{public-key} @var{private-key}
+A key pair contains a @var{public-key} and a matching
+@var{private-key}. You use this form for keys you own.
+@end deftp
+
+@deftp {Class} <rsa-key-pair> () (@code{<key-pair>})
+This key pair contains matching RSA keys.
+@end deftp
+
+@deftp {Class} <ec-key-pair> () (@code{<key-pair>}) @var{crv}
+This key pair contains matching elliptic curve keys. @var{crv} is a
+symbol identifiying the curve.
+@end deftp
+
+@deftp {Class} <rsa-private-key> (<private-key>) @var{d} @var{p} @var{q} @var{dp} @var{dq} @var{qi}
+@deftpx {Class} <rsa-public-key> (<public-key>) @var{n} @var{e}
+@deftpx {Class} <ec-scalar> (<private-key>) @var{crv} @var{z}
+@deftpx {Class} <ec-point> (<public-key>) @var{crv} @var{x} @var{y}
+All fields are strings, base64 encoding the parameters, except
+@var{crv}, which is a symbol.
+@end deftp
+
+@deftp {Class} <jwks> () @var{keys}
+An identity provider may use different keys that are in validity to
+sign different access tokens. The JWKS encapsulates many public
+@var{keys}.
+@end deftp
+
+@deftypefn {Generic method} <public-key> public-key (@var{key} @code{<key-pair>})
+@deftypefnx {Generic method} <public-key> public-key (@var{key} @code{<public-key>})
+Return the public part of @var{key}, which may either be a key pair or
+a public key.
+@end deftypefn
+
+@deftypefn {Generic method} <private-key> private-key (@var{key} @code{<key-pair>})
+@deftypefnx {Generic method} <private-key> private-key (@var{key} @code{<private-key>})
+Return the private part of @var{key}.
+@end deftypefn
+
+@deftypefn {Generic method} <string> rsa-d (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-d (@var{key} @code{<rsa-private-key>})
+@deftypefnx {Generic method} <string> rsa-p (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-p (@var{key} @code{<rsa-private-key>})
+@deftypefnx {Generic method} <string> rsa-q (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-q (@var{key} @code{<rsa-private-key>})
+@deftypefnx {Generic method} <string> rsa-dp (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-dp (@var{key} @code{<rsa-private-key>})
+@deftypefnx {Generic method} <string> rsa-dq (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-dq (@var{key} @code{<rsa-private-key>})
+@deftypefnx {Generic method} <string> rsa-qi (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-qi (@var{key} @code{<rsa-private-key>})
+@deftypefnx {Generic method} <string> rsa-n (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-n (@var{key} @code{<rsa-public-key>})
+@deftypefnx {Generic method} <string> rsa-e (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <string> rsa-e (@var{key} @code{<rsa-public-key>})
+@deftypefnx {Generic method} <symbol> ec-crv (@var{key} @code{<ec-key-pair>})
+@deftypefnx {Generic method} <symbol> ec-crv (@var{key} @code{<ec-point>})
+@deftypefnx {Generic method} <symbol> ec-crv (@var{key} @code{<ec-scalar>})
+@deftypefnx {Generic method} <string> ec-x (@var{key} @code{<ec-key-pair>})
+@deftypefnx {Generic method} <string> ec-x (@var{key} @code{<ec-point>})
+@deftypefnx {Generic method} <string> ec-y (@var{key} @code{<ec-key-pair>})
+@deftypefnx {Generic method} <string> ec-y (@var{key} @code{<ec-point>})
+@deftypefnx {Generic method} <string> ec-z (@var{key} @code{<ec-key-pair>})
+@deftypefnx {Generic method} <string> ec-z (@var{key} @code{<ec-scalar>})
+Key parameter getters.
+@end deftypefn
+
+@deftypefn {Generic method} <list> keys (@var{jwks} @code{<jwks>})
+Return all the public keys used by @var{jwks}.
+@end deftypefn
+
+@deftypefn {Generic method} <undefined> check-key (@var{key} @code{<key>})
+@deftypefnx {Generic method} <undefined> check-key (@var{key} @code{<key-pair>})
+Check that the @var{key} parameters are consistent.
+@end deftypefn
+
+When exchanging keys, maybe you will have them in the form of a JWK:
+an alist from symbols to strings, as a representation for a JSON
+object.
+
+@deftypefn {Generic method} <list> key->jwk (@var{key} @code{<key>})
+@deftypefnx {Generic method} <list> key->jwk (@var{key} @code{<key-pair>})
+Return an alist with known parameter names for JSON.
+@end deftypefn
+
+@deffn function jwk->key @var{jwk}
+Parse @var{jwk} as a key or a key pair.
+@end deffn
+
+@deftypefn {Generic method} <symbol> kty (@var{key} @code{<rsa-key-pair>})
+@deftypefnx {Generic method} <symbol> kty (@var{key} @code{<rsa-public-key>})
+@deftypefnx {Generic method} <symbol> kty (@var{key} @code{<rsa-private-key>})
+@deftypefnx {Generic method} <symbol> kty (@var{key} @code{<ec-key-pair>})
+@deftypefnx {Generic method} <symbol> kty (@var{key} @code{<ec-point>})
+@deftypefnx {Generic method} <symbol> kty (@var{key} @code{<ec-scalar>})
+Return @code{'RSA} for RSA keys, or @code{'EC} for elliptic curve
+keys.
+@end deftypefn
+
+@deftypefn {Generic method} <string> jkt (@var{key} @code{<key-pair>})
+@deftypefnx {Generic method} <string> jkt (@var{key} @code{<public-key>})
+Hash the @var{key} parameters in a reproducible order to get the hash
+of a key.
+@end deftypefn
+
+@deffn function generate-key @var{[#:n-size]} @var{[#:e-size]} @var{[#:e=\"AQAB\"]} @var{[#:crv]}
+Generate a new key pair.
+@end deffn
+
+@deftypefn {Generic method} <values> serve (@var{jwks} @code{<jwks>}) @var{expiration-date}
+Return a response and response body for serving
+@var{jwks}. Client-side caching is very much necessary for a JWKS, so
+pass @var{expiration-date} as a SRFI-19 date to define a maximum date
+for caching. It should be in the future, for instance in 1 hour.
+@end deftypefn
+
+@deffn {function} get-jwks @var{uri} [#:@var{http-request}]
+Download a JWKS on the web at @var{uri}. Use @var{http-request}, with
+the same interface as that of @emph{(web client)}, to actually get the
+JWKS.
+@end deffn
+
+@deftp {Exception type} &not-a-jwk
+If the key parameters are incorrect, this exception is raised.
+@end deftp
+
+@deftp {Exception type} &not-a-jwks
+If the JWKS cannot be downloaded, or is incorrect, this exception is
+raised.
+@end deftp
+
 @node Caching on server side
 @chapter Caching on server side