JWK: the default signature algorithm "alg" is now a key parameter

1 files changed, 13 insertions, 6 deletions

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index 8004d3c..6f76838 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -360,9 +360,9 @@ implementation of @code{http-get} from @emph{(web client)}. Return
 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{#:validity}
+@deffn function issue-id-token @var{issuer-key} @var{#:webid} @var{#:iss} @var{#:sub} @var{#:aud} @var{#:validity}
 Create an ID token that is valid for @var{#:validity} seconds, and
-encode it with @var{issuer-key}.
+sign and encode it with @var{issuer-key}.
 @end deffn
 
 @node The access token
@@ -406,7 +406,7 @@ by the ID token validation. Return the decoded access token, or raise
 an exception.
 @end deffn
 
-@deffn function issue-access-token @var{issuer-key} @var{#alg} @var{#webid} @var{#iss} @var{#:validity} @var{[#client-key} @var{|} @var{#cnf/jkt]} @var{#client-id}
+@deffn function issue-access-token @var{issuer-key} #:@var{webid} #:@var{iss} #:@var{client-id} #:@var{validity} [#:@var{[client-key} | #:@var{cnf/jkt}]
 Create an access token for @var{#:validity} seconds, and encode it
 with @var{issuer-key}. You can either set the @code{#:cnf/jkt} keyword
 argument with the fingerprint of the client key, or set
@@ -484,7 +484,7 @@ Encode the proof and sign it with @var{key}. To generate valid proofs,
 field of the proof.
 @end deffn
 
-@deffn function issue-dpop-proof @var{client-key} @var{#alg} @var{#htm} @var{#htu} {[#:@var{access-token}=#f]}
+@deffn function issue-dpop-proof @var{client-key} #:@var{htm} #:@var{htu} {[#:@var{access-token}=#f]}
 Create a proof, sign it and encode it with
 @var{client-key}. @var{client-key} should contain both the private and
 public key, because the public part is written in the proof and the
@@ -532,9 +532,14 @@ 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> ()
+@deftp {Class} <private-key> () @var{alg}
 This is the base class for a private key. You need it to issue
-signatures.
+signatures. Signatures issued with this key will use @var{alg} for the
+signature algorithm, but the public key associated with this private
+key will verify signatures in any compatible algorithm, not just
+@var{alg}.
+
+@var{alg} is a symbol, for instance @code{'RS256}.
 @end deftp
 
 @deftp {Class} <public-key> ()
@@ -606,6 +611,8 @@ Return the private part of @var{key}.
 @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>})
+@deftypefnx {Generic method} <symbol> alg (@var{key} @code{<key-pair>})
+@deftypefnx {Generic method} <symbol> alg (@var{key} @code{<private-key>})
 Key parameter getters.
 @end deftypefn