UIA(3) Library Functions Manual UIA(3)

UiaUser Interactive Authentication API.

#include <Uia.h>

UiaStage *
UiaStageBuild(char *, HashMap *);

Array *

UiaCleanup(MatrixHttpHandlerArgs *);

UiaComplete(Array *, HttpServerContext *, Db *, HashMap *, HashMap **, TelodendriaConfig *);

UiaFlowsFree(Array *);

Uia 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 (), which validates 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. Uia makes it easy for the numerous API endpoints that utilize this authentication mechanism to implement it.

() 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.

() 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.

() 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 Cron(3).

() does the bulk of the work for user interactive authentication. It takes many paramters:

() 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.

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.

UiaDummyFlow() returns an array that represents a dummy authentication flow, or NULL if it could not allocate memory for it.

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.

User(3), Db(3), Cron(3)

March 7, 2023 Telodendria Project