Implement the DPoP proof

1 files changed, 136 insertions, 0 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index 27295e0..0fa9a42 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -119,6 +119,7 @@ more closely respected.
 
 @menu
 * The access token::
+* The DPoP proof::
 * Generic JWTs::
 @end menu
 
@@ -174,6 +175,64 @@ of the client key, or set @code{#:client-key} directly, in which case
 the fingerprint will be computed for you.
 @end deffn
 
+@node The DPoP proof
+@section The DPoP proof
+
+This is a special JWT, that is signed by a key controlled by the
+application. The access token certifies that the key used to sign the
+proof is approved by the identity provider.
+
+@deffn function dpop-proof? @var{proof}
+Check that the @var{proof} is a decoded DPoP proof. The validity of
+the proof is not checked by this function.
+@end deffn
+
+@deffn function dpop-proof-alg @var{proof}
+@deffnx function dpop-proof-jwk @var{proof}
+@deffnx function dpop-proof-jti @var{proof}
+@deffnx function dpop-proof-htm @var{proof}
+@deffnx function dpop-proof-htu @var{proof}
+@deffnx function dpop-proof-iat @var{proof}
+Get the corresponding field of the proof.
+@end deffn
+
+@deffn function dpop-proof-decode @var{current-time} @var{jti-list} @var{method} @var{uri} @var{str} @var{cnf/check}
+Check and decode a DPoP proof encoded as @var{str}.
+
+The @var{current-time} is passed as a date, time or number (of
+seconds).
+
+In order to prevent replay attacks, each proof has a unique random
+string that is remembered in @var{jti-list} until its expiration date
+is reached. See the @code{make-jti-list} function.
+
+The proof is limited to the scope of one @var{uri} and one
+@var{method} (@code{'GET}, @code{'POST} and so on).
+
+Finally, the key that is used to sign the proof should be confirmed by
+the identity provider. To this end, the @var{cnf/check} function is
+called with the fingerprint of the key. The function should check that
+the fingerprint is OK (return a boolean).
+@end deffn
+
+@deffn function make-jti-list
+This function in @emph{(webid-oidc jti-list)} creates an in-memory,
+async-safe, thread-safe cache for the proof IDs.
+@end deffn
+
+@deffn function dpop-proof-encode @var{proof} @var{key}
+Encode the proof and sign it with @var{key}. To generate valid proofs,
+@var{key} should be the private key corresponding to the @code{jwk}
+field of the proof.
+@end deffn
+
+@deffn function issue-dpop-proof @var{client-key} @var{#alg} @var{#htm} @var{#htu} @var{#iat}
+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
+private part is used to sign it.
+@end deffn
+
 @node Generic JWTs
 @section Generic JWTs
 
@@ -258,6 +317,7 @@ Return a string explaining the @var{error}. You can limit the
 * Invalid data format::
 * Invalid JWT::
 * Cannot fetch data on the web::
+* Other errors in the protocol or from a reasonable implementation::
 @end menu
 
 @node Invalid data format
@@ -300,6 +360,28 @@ The @var{value} of the cnf/jkt field is incorrect.
 The @var{value} of the client-id field is incorrect.
 @end deftp
 
+@deftp {exception type} &incorrect-typ-field @var{value}
+The @var{value} of the typ field in the DPoP proof header is
+incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-jwk-field @var{value} @var{cause}
+The @var{value} of the jwk field in the DPoP proof header is
+incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-jti-field @var{value}
+The @var{value} of the jti 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} &incorrect-htu-field @var{value}
+The @var{value} of the htu field in the DPoP proof is incorrect.
+@end deftp
+
 @node Invalid JWT
 @section Invalid JWT
 Each JWT type – access token, DPoP proof, ID token, authorization code
@@ -392,6 +474,26 @@ The @var{value} string is not an encoding of a valid access token.
 The @var{access-token} cannot be signed.
 @end deftp
 
+@deftp {exception type} &not-a-dpop-proof @var{value} @var{cause}
+The @var{value} is not a DPoP proof.
+@end deftp
+
+@deftp {exception type} &not-a-dpop-proof-header @var{value} @var{cause}
+The @var{value} is not a DPoP proof header.
+@end deftp
+
+@deftp {exception type} &not-a-dpop-proof-payload @var{value} @var{cause}
+The @var{value} is not a DPoP proof payload.
+@end deftp
+
+@deftp {exception type} &cannot-decode-dpop-proof @var{value} @var{cause}
+The @var{value} string is not an encoding of a valid DPoP proof.
+@end deftp
+
+@deftp {exception type} &cannot-encode-dpop-proof @var{dpop-proof} @var{key} @var{cause}
+The @var{dpop-proof} 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
@@ -423,6 +525,40 @@ It is impossible to fetch the configuration of @var{issuer}.
 It is impossible to fetch the keys of @var{issuer} at @var{uri}.
 @end deftp
 
+@node Other errors in the protocol or from a reasonable implementation
+@section Other errors in the protocol or from a reasonable implementation
+The protocol does not rely solely on JWT validation, so these errors
+may happen too.
+
+@deftp {exception type} &dpop-method-mismatch @var{signed} @var{requested}
+The method value @var{signed} in the DPoP proof does not match the
+method that is @var{requested} on the server.
+@end deftp
+
+@deftp {exception type} &dpop-uri-mismatch @var{signed} @var{requested}
+The URI value @var{signed} in the DPoP proof does not match the URI
+that is @var{requested} on the server.
+@end deftp
+
+@deftp {exception type} &dpop-signed-in-future @var{signed} @var{current}
+The proof is @var{signed} for a date which is too much ahead of the
+@var{current} time.
+@end deftp
+
+@deftp {exception type} &dpop-too-old @var{signed} @var{current}
+The proof was @var{signed} at a past date of @var{current}.
+@end deftp
+
+@deftp {exception type} &dpop-unconfirmed-key @var{key} @var{expected} @var{cause}
+The confirmation of @var{key} is not what is @var{expected}, or (if a
+function was passed as @var{cnf/check}) the @var{cause} exception
+occurred while confirming.
+@end deftp
+
+@deftp {exception type} &jti-found @var{jti} @var{cause}
+The @var{jti} of the proof has already been issued in a recent past.
+@end deftp
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License