diff options
Diffstat (limited to 'doc/manual.html')
| -rw-r--r-- | doc/manual.html | 198 |
1 files changed, 186 insertions, 12 deletions
diff --git a/doc/manual.html b/doc/manual.html index e3e9cbe..2b44467 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -178,6 +178,84 @@ which case the fingerprint will be computed for you. </p> </info:deffn> + <h2>The DPoP proof</h2> + <p> + 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. + </p> + <info:deffn type="function" name="dpop-proof?" arguments="proof"> + <p> + Check that the <info:var>proof</info:var> is a decoded DPoP + proof. The validity of the proof is not checked by this + function. + </p> + </info:deffn> + <info:deffn type="function" name="dpop-proof-alg" arguments="proof"> + <info:deffnx type="function" name="dpop-proof-jwk" arguments="proof" /> + <info:deffnx type="function" name="dpop-proof-jti" arguments="proof" /> + <info:deffnx type="function" name="dpop-proof-htm" arguments="proof" /> + <info:deffnx type="function" name="dpop-proof-htu" arguments="proof" /> + <info:deffnx type="function" name="dpop-proof-iat" arguments="proof" /> + <p> + Get the corresponding field of the proof. + </p> + </info:deffn> + <info:deffn type="function" name="dpop-proof-decode" arguments="current-time jti-list method uri str cnf/check"> + <p> + Check and decode a DPoP proof encoded + as <info:var>str</info:var>. + </p> + <p> + The <info:var>current-time</info:var> is passed as a date, + time or number (of seconds). + </p> + <p> + In order to prevent replay attacks, each proof has a unique + random string that is remembered + in <info:var>jti-list</info:var> until its expiration date is + reached. See the <pre>make-jti-list</pre> function. + </p> + <p> + The proof is limited to the scope of + one <info:var>uri</info:var> and + one <info:var>method</info:var> + (<pre>'GET</pre>, <pre>'POST</pre> and so on). + </p> + <p> + Finally, the key that is used to sign the proof should be + confirmed by the identity provider. To this end, + the <info:var>cnf/check</info:var> function is called with the + fingerprint of the key. The function should check that the + fingerprint is OK (return a boolean). + </p> + </info:deffn> + <info:deffn type="function" + name="make-jti-list" + arguments=""> + <p> + This function in <emph>(webid-oidc jti-list)</emph> + creates an in-memory, async-safe, thread-safe cache for the + proof IDs. + </p> + </info:deffn> + <info:deffn type="function" name="dpop-proof-encode" arguments="proof key"> + <p> + Encode the proof and sign it with <info:var>key</info:var>. To + generate valid proofs, <info:var>key</info:var> should be the + private key corresponding to the <pre>jwk</pre> field of the + proof. + </p> + </info:deffn> + <info:deffn type="function" name="issue-dpop-proof" arguments="client-key #alg #htm #htu #iat"> + <p> + Create a proof, sign it and encode it with + <info:var>client-key</info:var>. <info:var>client-key</info:var> + 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. + </p> + </info:deffn> <h2>Generic JWTs</h2> <p> You can parse generic JWTs signed with JWS with the following @@ -396,38 +474,68 @@ </info:deftp> <info:deftp type="exception type" name="&incorrect-webid-field" arguments="value"> <p> - The <info:var>value</info:var> of the webid field in the JWT - is missing (if <pre>#f</pre>), or not an acceptable value. + The <info:var>value</info:var> of the webid field in the JWT + is missing (if <pre>#f</pre>), or not an acceptable value. </p> </info:deftp> <info:deftp type="exception type" name="&incorrect-iss-field" arguments="value"> <p> - The <info:var>value</info:var> of the iss field is incorrect. + The <info:var>value</info:var> of the iss field is incorrect. </p> </info:deftp> <info:deftp type="exception type" name="&incorrect-aud-field" arguments="value"> <p> - The <info:var>value</info:var> of the aud field is incorrect. + The <info:var>value</info:var> of the aud field is incorrect. </p> </info:deftp> <info:deftp type="exception type" name="&incorrect-iat-field" arguments="value"> <p> - The <info:var>value</info:var> of the iat field is incorrect. + The <info:var>value</info:var> of the iat field is incorrect. </p> </info:deftp> <info:deftp type="exception type" name="&incorrect-exp-field" arguments="value"> <p> - The <info:var>value</info:var> of the exp field is incorrect. + The <info:var>value</info:var> of the exp field is incorrect. </p> </info:deftp> <info:deftp type="exception type" name="&incorrect-cnf/jkt-field" arguments="value"> <p> - The <info:var>value</info:var> of the cnf/jkt field is incorrect. + The <info:var>value</info:var> of the cnf/jkt field is incorrect. </p> </info:deftp> <info:deftp type="exception type" name="&incorrect-client-id-field" arguments="value"> <p> - The <info:var>value</info:var> of the client-id field is incorrect. + The <info:var>value</info:var> of the client-id field is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-typ-field" arguments="value"> + <p> + The <info:var>value</info:var> of the typ field in the DPoP proof + header is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-jwk-field" arguments="value cause"> + <p> + The <info:var>value</info:var> of the jwk field in the DPoP + proof header is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-jti-field" arguments="value"> + <p> + The <info:var>value</info:var> of the jti field in the DPoP + proof is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-htm-field" arguments="value"> + <p> + The <info:var>value</info:var> of the htm field in the DPoP + proof is incorrect. + </p> + </info:deftp> + <info:deftp type="exception type" name="&incorrect-htu-field" arguments="value"> + <p> + The <info:var>value</info:var> of the htu field in the DPoP + proof is incorrect. </p> </info:deftp> <info:deftp type="exception type" name="&not-an-access-token" arguments="value cause"> @@ -447,14 +555,14 @@ </info:deftp> <info:deftp type="exception type" name="&cannot-fetch-issuer-configuration" arguments="issuer cause"> <p> - It is impossible to fetch the configuration of - <info:var>issuer</info:var>. + It is impossible to fetch the configuration of + <info:var>issuer</info:var>. </p> </info:deftp> <info:deftp type="exception type" name="&cannot-fetch-jwks" arguments="issuer uri cause"> <p> - It is impossible to fetch the keys of - <info:var>issuer</info:var> at <info:var>uri</info:var>. + It is impossible to fetch the keys of + <info:var>issuer</info:var> at <info:var>uri</info:var>. </p> </info:deftp> <info:deftp type="exception type" name="&cannot-decode-access-token" arguments="value cause"> @@ -468,6 +576,72 @@ The <info:var>access-token</info:var> cannot be signed. </p> </info:deftp> + <info:deftp type="exception type" name="&not-a-dpop-proof" arguments="value cause"> + <p> + The <info:var>value</info:var> is not a DPoP proof. + </p> + </info:deftp> + <info:deftp type="exception type" name="&not-a-dpop-proof-header" arguments="value cause"> + <p> + The <info:var>value</info:var> is not a DPoP proof header. + </p> + </info:deftp> + <info:deftp type="exception type" name="&not-a-dpop-proof-payload" arguments="value cause"> + <p> + The <info:var>value</info:var> is not a DPoP proof payload. + </p> + </info:deftp> + <info:deftp type="exception type" name="&dpop-method-mismatch" arguments="signed requested"> + <p> + The method value <info:var>signed</info:var> in the DPoP proof + does not match the method that is + <info:var>requested</info:var> on the server. + </p> + </info:deftp> + <info:deftp type="exception type" name="&dpop-uri-mismatch" arguments="signed requested"> + <p> + The URI value <info:var>signed</info:var> in the DPoP proof + does not match the URI that is <info:var>requested</info:var> + on the server. + </p> + </info:deftp> + <info:deftp type="exception type" name="&dpop-signed-in-future" arguments="signed current"> + <p> + The proof is <info:var>signed</info:var> for a date which is + too much ahead of the <info:var>current</info:var> time. + </p> + </info:deftp> + <info:deftp type="exception type" name="&dpop-too-old" arguments="signed current"> + <p> + The proof was <info:var>signed</info:var> at a past date of + <info:var>current</info:var>. + </p> + </info:deftp> + <info:deftp type="exception type" name="&dpop-unconfirmed-key" arguments="key expected cause"> + <p> + The confirmation of <info:var>key</info:var> is not what is + <info:var>expected</info:var>, or (if a function was passed as + <info:var>cnf/check</info:var>) the <info:var>cause</info:var> + exception occurred while confirming. + </p> + </info:deftp> + <info:deftp type="exception type" name="&jti-found" arguments="jti cause"> + <p> + The <info:var>jti</info:var> of the proof has already been + issued in a recent past. + </p> + </info:deftp> + <info:deftp type="exception type" name="&cannot-decode-dpop-proof" arguments="value cause"> + <p> + The <info:var>value</info:var> string is not an encoding of a + valid DPoP proof. + </p> + </info:deftp> + <info:deftp type="exception type" name="&cannot-encode-dpop-proof" arguments="dpop-proof key cause"> + <p> + The <info:var>dpop-proof</info:var> cannot be signed. + </p> + </info:deftp> <h1 type="appendix">GNU Free Documentation License</h1> <info:gfdl /> |