From 04bf8ca1a1c9a85b396bb5491b1e8b4003f0466c Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Tue, 7 Mar 2023 00:28:52 +0000 Subject: [PATCH] Document Uia API. --- TODO.txt | 4 +- man/man3/Uia.3 | 123 ++++++++++++++++++++++++++++++++++++++++++++++ src/Uia.c | 4 +- src/include/Uia.h | 2 +- 4 files changed, 128 insertions(+), 5 deletions(-) create mode 100644 man/man3/Uia.3 diff --git a/TODO.txt b/TODO.txt index a0d915d..2ee645c 100644 --- a/TODO.txt +++ b/TODO.txt @@ -22,11 +22,11 @@ Milestone: v0.2.0 [x] User login [x] Logout all -[~] Documentation +[x] Documentation [x] User functions [x] Json functions [x] Db functions - [ ] Uia (move docs from Matrix) + [x] Uia (move docs from Matrix) [x] Convert proposals to man pages diff --git a/man/man3/Uia.3 b/man/man3/Uia.3 new file mode 100644 index 0000000..4c303a8 --- /dev/null +++ b/man/man3/Uia.3 @@ -0,0 +1,123 @@ +.Dd $Mdocdate: March 7 2023 $ +.Dt UIA 3 +.Os Telodendria Project +.Sh NAME +.Nm Uia +.Nd User Interactive Authentication API. +.Sh SYNOPSIS +.In Uia.h +.Ft UiaStage * +.Fn UiaStageBuild "char *" "HashMap *" +.Ft Array * +.Fn UiaDummyFlow "void" +.Ft void +.Fn UiaCleanup "MatrixHttpHandlerArgs *" +.Ft int +.Fn UiaComplete "Array *" "HttpServerContext *" "Db *" "HashMap *" "HashMap **" "TelodendriaConfig *" +.Ft void +.Fn UiaFlowsFree "Array *" +.Sh DESCRIPTION +.Nm +takes care of all the logic for performing user interactive +authentication as defined by the Matrix specification. API endpoints +that require authentication via user interactive authentication +build up flows and any necessary parameters, and pass them into +.Fn UiaComplete , +which validates +.Dv auth +objects and maintains session state to track the progress of a +client through the user interactive authentication flows. The idea +is that an API endpoint will not progress until user interactive +authentication has succeeded. +.Nm +makes it easy for the numerous API endpoints that utilize this +authentication mechanism to implement it. +.Pp +.Fn UiaStageBuild +builds a single stage. A stage consists of a string identifying its +type, which is used to instruct the client as to what should be +done, and parameters, which is a JSON object that contains +implementation-specific parameters for completing the stage. This +function takes those two parameters in that order. +.Pp +.Fn UiaDummyFlow +builds a flow that consists only of a dummy stage. This is useful +when an endpoint is required to use user interactive authentication, +but doesn't actually want to require the user to do anything. Since +the dummy flow is a pretty common flow, it seemed sensible to have +a function for it. Other flows are built by the caller that wishes +to perform user interactive authentication. +.Pp +.Fn UiaCleanup +should be called periodically to purge old sessions. Session are +only valid for a few minutes after their last access. After that, they +should be purged so the database doesn't fill up with session files. +This function is specifically designed to be called via +.Xr Cron 3 . +.Pp +.Fn UiaComplete +does the bulk of the work for user interactive authentication. It +takes many paramters: +.Bl -bullet +.It +An array of arrays of stages. Stages should be created with +.Fn UiaStageBuild , +and then put into an array to create a flow. Those flows should then +be put into an array and passed as this paramter. Do note that +because of the loose typing of Telodendria's Array API, it is very +easy to make mistakes here; if you are implementing a new route that +requires user interactive authentication, then refer to an existing +route so you can see how it works. +.It +An HTTP server context. This is required to set the response headers +in the event of an error. +.It +The database where user interactive authentication sessons are +persisted. +.It +The JSON request body that contains the client's +.Dv auth +object, which will be read, parsed, and handled as appropriate. +.It +A pointer to a pointer where a JSON response can be placed if +necessary. If +.Fn UiaComplete +encounters a client error, such as a failure to authenticate, or +outstanding stages that have not been completed, it will place a +JSON response here that is expected to be returned to the client. +This response will include a description of all the flows, stages, +and their parameters. +.It +A valid Telodendria configuration structure, because a few values +are read from the configuration during certain stages of the +authentication. +.El +.Pp +.Fn UiaFlowsFree +frees an array of flows, as described above. Even though the +caller constructs this array, it is convenient to free it in its +entirety in a single function call. +.Sh RETURN VALUES +.Pp +.Fn UiaStageBuild +returns an opaque structure that represents a user interactive +authentication stage, and any parameters the client needs to complete +it. It may return NULL if there is an error allocating memory. +.Pp +.Fn UiaDummyFlow +returns an array that represents a dummy authentication flow, or +NULL if it could not allocate memory for it. +.Pp +.Fn UiaComplete +returns an integer less than zero if it experiences an internal +failure, such as a failure to allocate memory, or a corrupted +database. It returns 0 if the client has remaining stages to +complete. In this case, it will have set the response headers +and the passed response pointer, so the caller should immediately +return the response to the client. This function returns 1 if the +user has successfully completed all stages. Only in this case shall +the caller proceed with its logic. +.Sh SEE ALSO +.Xr User 3 , +.Xr Db 3 , +.Xr Cron 3 diff --git a/src/Uia.c b/src/Uia.c index 71575ef..d63008c 100644 --- a/src/Uia.c +++ b/src/Uia.c @@ -181,13 +181,13 @@ UiaDummyFlow(void) return NULL; } - ArrayAdd(response, UiaBuildStage("m.login.dummy", NULL)); + ArrayAdd(response, UiaStageBuild("m.login.dummy", NULL)); return response; } UiaStage * -UiaBuildStage(char *type, HashMap * params) +UiaStageBuild(char *type, HashMap * params) { UiaStage *stage = Malloc(sizeof(UiaStage)); diff --git a/src/include/Uia.h b/src/include/Uia.h index 209ce91..17fdec0 100644 --- a/src/include/Uia.h +++ b/src/include/Uia.h @@ -32,7 +32,7 @@ typedef struct UiaStage UiaStage; extern UiaStage * - UiaBuildStage(char *, HashMap *); + UiaStageBuild(char *, HashMap *); extern Array * UiaDummyFlow(void);