From fa486f2e136a898d1b1548ec90757a78c65a0b70 Mon Sep 17 00:00:00 2001 From: Vivien Kraus Date: Thu, 16 Sep 2021 23:03:12 +0200 Subject: JWK: document it, and use GOOPS --- doc/disfluid.texi | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) (limited to 'doc') 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} () +This is the base class for a private key. You need it to issue +signatures. +@end deftp + +@deftp {Class} () +This is the base class for a public key. You need it to check +signatures. +@end deftp + +@deftp {Class} () @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} () (@code{}) +This key pair contains matching RSA keys. +@end deftp + +@deftp {Class} () (@code{}) @var{crv} +This key pair contains matching elliptic curve keys. @var{crv} is a +symbol identifiying the curve. +@end deftp + +@deftp {Class} () @var{d} @var{p} @var{q} @var{dp} @var{dq} @var{qi} +@deftpx {Class} () @var{n} @var{e} +@deftpx {Class} () @var{crv} @var{z} +@deftpx {Class} () @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} () @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 (@var{key} @code{}) +@deftypefnx {Generic method} public-key (@var{key} @code{}) +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 (@var{key} @code{}) +@deftypefnx {Generic method} private-key (@var{key} @code{}) +Return the private part of @var{key}. +@end deftypefn + +@deftypefn {Generic method} rsa-d (@var{key} @code{}) +@deftypefnx {Generic method} rsa-d (@var{key} @code{}) +@deftypefnx {Generic method} rsa-p (@var{key} @code{}) +@deftypefnx {Generic method} rsa-p (@var{key} @code{}) +@deftypefnx {Generic method} rsa-q (@var{key} @code{}) +@deftypefnx {Generic method} rsa-q (@var{key} @code{}) +@deftypefnx {Generic method} rsa-dp (@var{key} @code{}) +@deftypefnx {Generic method} rsa-dp (@var{key} @code{}) +@deftypefnx {Generic method} rsa-dq (@var{key} @code{}) +@deftypefnx {Generic method} rsa-dq (@var{key} @code{}) +@deftypefnx {Generic method} rsa-qi (@var{key} @code{}) +@deftypefnx {Generic method} rsa-qi (@var{key} @code{}) +@deftypefnx {Generic method} rsa-n (@var{key} @code{}) +@deftypefnx {Generic method} rsa-n (@var{key} @code{}) +@deftypefnx {Generic method} rsa-e (@var{key} @code{}) +@deftypefnx {Generic method} rsa-e (@var{key} @code{}) +@deftypefnx {Generic method} ec-crv (@var{key} @code{}) +@deftypefnx {Generic method} ec-crv (@var{key} @code{}) +@deftypefnx {Generic method} ec-crv (@var{key} @code{}) +@deftypefnx {Generic method} ec-x (@var{key} @code{}) +@deftypefnx {Generic method} ec-x (@var{key} @code{}) +@deftypefnx {Generic method} ec-y (@var{key} @code{}) +@deftypefnx {Generic method} ec-y (@var{key} @code{}) +@deftypefnx {Generic method} ec-z (@var{key} @code{}) +@deftypefnx {Generic method} ec-z (@var{key} @code{}) +Key parameter getters. +@end deftypefn + +@deftypefn {Generic method} keys (@var{jwks} @code{}) +Return all the public keys used by @var{jwks}. +@end deftypefn + +@deftypefn {Generic method} check-key (@var{key} @code{}) +@deftypefnx {Generic method} check-key (@var{key} @code{}) +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} key->jwk (@var{key} @code{}) +@deftypefnx {Generic method} key->jwk (@var{key} @code{}) +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} kty (@var{key} @code{}) +@deftypefnx {Generic method} kty (@var{key} @code{}) +@deftypefnx {Generic method} kty (@var{key} @code{}) +@deftypefnx {Generic method} kty (@var{key} @code{}) +@deftypefnx {Generic method} kty (@var{key} @code{}) +@deftypefnx {Generic method} kty (@var{key} @code{}) +Return @code{'RSA} for RSA keys, or @code{'EC} for elliptic curve +keys. +@end deftypefn + +@deftypefn {Generic method} jkt (@var{key} @code{}) +@deftypefnx {Generic method} jkt (@var{key} @code{}) +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} serve (@var{jwks} @code{}) @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} ¬-a-jwk +If the key parameters are incorrect, this exception is raised. +@end deftp + +@deftp {Exception type} ¬-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 -- cgit v1.2.3