diff options
Diffstat (limited to 'doc/disfluid.texi')
| -rw-r--r-- | doc/disfluid.texi | 79 |
1 files changed, 53 insertions, 26 deletions
diff --git a/doc/disfluid.texi b/doc/disfluid.texi index d2558b4..d18c8e9 100644 --- a/doc/disfluid.texi +++ b/doc/disfluid.texi @@ -323,8 +323,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{#exp} @var{#iat} -Create an ID token, and encode it with @var{issuer-key}. +@deffn function issue-id-token @var{issuer-key} @var{#:alg} @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}. @end deffn @node The access token @@ -372,11 +373,12 @@ decoded token otherwise. Encode @var{token} and sign it with the issuer’s @var{key}. @end deffn -@deffn function issue-access-token @var{issuer-key} @var{#alg} @var{#webid} @var{#iss} @var{#exp} @var{#iat} @var{[#client-key} @var{|} @var{#cnf/jkt]} @var{#client-id} -Create an access token, 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 @code{#:client-key} directly, in which case -the fingerprint will be computed for you. +@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} +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 +@code{#:client-key} directly, in which case the fingerprint will be +computed for you. @end deffn @node The DPoP proof @@ -401,12 +403,9 @@ the proof is not checked by this function. 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} @var{[#:access-token]} +@deffn function dpop-proof-decode @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 -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. @@ -424,9 +423,26 @@ 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 -This function in @emph{(webid-oidc jti-list)} creates an in-memory, -async-safe, thread-safe cache for the proof IDs. +The DPoP proof algorithm is sensitive to the current time, because the +proofs have a limited time validity. By default, the time is the +system time when the proof is decoded. + +@deffn parameter current-date +This parameter overrides the current time. + +It is a thunk returning a date, so you need to put two parenthesis to +get the time. However, you can set it to a date, a time, a number of +seconds, or a thunk returning any of these. + +@example + (use-module ((webid-oidc parameters) #:prefix p:)) + ;; This is the current date: + ((p:current-date)) + ;; You can override it with a thunk, or a fixed date: + (parameterize ((p:current-date 0)) + ;; Jan 1st 1970 + ((p:current-date))) +@end example @end deffn @deffn function dpop-proof-encode @var{proof} @var{key} @@ -435,13 +451,16 @@ 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} {[#:@var{access-token}=#f]} +@deffn function issue-dpop-proof @var{client-key} @var{#alg} @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 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. + +The @samp{iat} field of the DPoP proof is read from the +@var{current-date} parameter. @end deffn @node Generic JWTs @@ -492,25 +511,28 @@ line will indicate which items are dropped. The @emph{(webid-oidc cache)} module exports two functions to deal with the cache. -@deffn function clean-cache @var{[#percents]} @var{[#dir]} -Drop @var{percents}% of the cache right now, in @var{dir} (defaults to -some place within @emph{XDG_CACHE_HOME}). +@deffn function clean-cache @var{[#percents]} +Drop @var{percents}% of the cache right now. @end deffn -@deffn function with-cache @var{[#current-time]} @var{[#http-get]} @var{[#dir]} +@deffn function with-cache @var{[#http-get]} Return a function acting as @emph{http-get} from @emph{(web client)} (takes an URI as the first parameter, and an optional @var{#:headers} set, and returns 2 values, the response and its body). -The cache will be read and written in @var{dir} (defaults to some -place within @emph{XDG_CACHE_HOME}), and the @var{current-time} number -of seconds, SRFI-19 time or date, or time-returning thunk will be used -to check for the validity of responses. +The cache will be read and written in the @samp{web-cache} +subdirectory of the cache home. To check the time window validity, the +@var{current-date} parameter is used. The back-end function, @var{http-get}, defaults to that of @emph{(web client)}. @end deffn +@deffn parameter cache-home +This parameters sets the cache directory. By default, it is +@emph{XDG_CACHE_HOME}. +@end deffn + @node Content negociation @chapter Content negociation There are a number of different available syntaxes for RDF, some being @@ -682,7 +704,7 @@ copy for both. The @emph{content} API is contained in the @code{(webid-oidc server resource content)} module. -@deffn function with-session @var{f} [@var{#:dir}] +@deffn function with-session @var{f} Call @var{f} with 5 arguments: @itemize @item @@ -711,8 +733,13 @@ The first 3 functions as well as the last one are called with an etag, and the function to create a content is called with the content-type, list of contained paths, and (static) content. -By default, the contents are stored within @var{XDG_DATA_HOME}, but it -can be overriden by @var{#:dir}. +The contents are searched in the @emph{server/content} subdirectory of +@var{data-home}. +@end deffn + +@deffn parameter data-home +Defines the directory where to store persistent data. Defaults to +@emph{XDG_DATA_HOME}. @end deffn The @emph{path} API is defined in |