DPoP proof: support the "ath" claim

1 files changed, 23 insertions, 7 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index a6852a8..2ad0ca8 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -263,10 +263,11 @@ the proof is not checked by this function.
 @deffnx function dpop-proof-htm @var{proof}
 @deffnx function dpop-proof-htu @var{proof}
 @deffnx function dpop-proof-iat @var{proof}
+@deffnx function dpop-proof-ath @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}
+@deffn function dpop-proof-decode @var{current-time} @var{jti-list} @var{method} @var{uri} @var{str} @var{cnf/check} @var{[#:access-token]}
 Check and decode a DPoP proof encoded as @var{str}.
 
 The @var{current-time} is passed as a date, time or number (of
@@ -279,10 +280,14 @@ 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).
+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).
+
+Finally, when the DPoP proof is tied to an access token (so, for all
+uses except requesting an access token or a refresh token), it must be
+bound to an @var{access-token}.
 @end deffn
 
 @deffn function make-jti-list
@@ -296,11 +301,13 @@ 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{#iat}
+@deffn function issue-dpop-proof @var{client-key} @var{#alg} @var{#htm} @var{#htu} @var{#iat} {[#:@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
-private part is used to sign it.
+private part is used to sign it. For most uses, the DPoP proof should
+be encoded for a specific access token. Only token requests should
+omit the @samp{access-token} field.
 @end deffn
 
 @node Generic JWTs
@@ -932,6 +939,10 @@ The @var{value} of the htm field in the DPoP proof is incorrect.
 The @var{value} of the htu field in the DPoP proof is incorrect.
 @end deftp
 
+@deftp {exception type} &incorrect-ath-field @var{value}
+The @var{value} of the ath field is not the hash of the access token.
+@end deftp
+
 @deftp {exception type} &incorrect-redirect-uris-field @var{value}
 The @var{value} of the redirect-uris field of a client manifest is
 incorrect.
@@ -1180,6 +1191,11 @@ function was passed as @var{cnf/check}) the @var{cause} exception
 occurred while confirming.
 @end deftp
 
+@deftp {exception type} &dpop-invalid-access-token-hash @var{hash} @var{access-token}
+The @var{access-token} passed to the resource server does not match
+the @var{hash} provided in the DPoP proof.
+@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