forked from Telodendria/Telodendria
220 lines
6.5 KiB
Groff
220 lines
6.5 KiB
Groff
.Dd $Mdocdate: March 6 2023 $
|
|
.Dt USER 3
|
|
.Os Telodendria Project
|
|
.Sh NAME
|
|
.Nm User
|
|
.Nd Convenience functions for working with local users.
|
|
.Sh SYNOPSIS
|
|
.In User.h
|
|
.Ft int
|
|
.Fn UserValidate "char *" "char *"
|
|
.Ft int
|
|
.Fn UserHistoricalValidate "char *" "char *"
|
|
.Ft int
|
|
.Fn UserExists "Db *" "char *"
|
|
.Ft User *
|
|
.Fn UserCreate "Db *" "char *" "char *"
|
|
.Ft User *
|
|
.Fn UserLock "Db *" "char *"
|
|
.Ft User *
|
|
.Fn UserAuthenticate "Db *" "char *"
|
|
.Ft int
|
|
.Fn UserUnlock "User *"
|
|
.Ft UserLoginInfo *
|
|
.Fn UserLogin "User *" "char *" "char *" "char *" "int"
|
|
.Ft char *
|
|
.Fn UserGetName "User *"
|
|
.Ft int
|
|
.Fn UserCheckPassword "User *" "char *"
|
|
.Ft int
|
|
.Fn UserSetPassword "User *" "char *"
|
|
.Ft int
|
|
.Fn UserDeactivate "User *"
|
|
.Ft HashMap *
|
|
.Fn UserGetDevices "User *"
|
|
.Ft UserAccessToken *
|
|
.Fn UserGenerateAccessToken "User *" "char *" "int"
|
|
.Ft int
|
|
.Fn UserAccessTokenSave "Db *" "UserAccessToken *"
|
|
.Ft void
|
|
.Fn UserAccessTokenFree "UserAccessToken *"
|
|
.Ft int
|
|
.Fn UserDeleteToken "User *" "char *"
|
|
.Ft int
|
|
.Fn UserDeleteTokens "User *"
|
|
.Ft UserId *
|
|
.Fn UserIdParse "char *" "char *"
|
|
.Ft void
|
|
.Fn UserIdFree "UserId *"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
API provides a wrapper over the database and offers an easy way for managing
|
|
local users. It supports all of the locking mechanisms that the database does,
|
|
and provides features for authenticating local users, among other tasks.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
typedef struct UserLoginInfo
|
|
{
|
|
UserAccessToken *accessToken;
|
|
char *refreshToken;
|
|
} UserLoginInfo;
|
|
|
|
typedef struct UserAccessToken
|
|
{
|
|
char *user;
|
|
char *string;
|
|
char *deviceId;
|
|
long lifetime;
|
|
} UserAccessToken;
|
|
|
|
typedef struct UserId
|
|
{
|
|
char *localpart;
|
|
char *server;
|
|
} UserId;
|
|
.Ed
|
|
.Pp
|
|
.Fn UserValidate
|
|
takes a localpart and domain as separate parameters and validates it against the
|
|
rules of the Matrix specification. The reason the domain is required is because
|
|
the spec imposes limitations on the length of the user name, and the longer the
|
|
domain name is, the shorter the local part can be. This function is used to
|
|
ensure that client-provided localparts are valid on this server.
|
|
.Fn UserHistoricalValidate
|
|
is called the exact same way, except it is a little more lenient. It is used to
|
|
validate user parts on other servers, since some usernames might exist that are
|
|
not fully spec compliant, but remain in use due to historical reasons.
|
|
.Pp
|
|
.Fn UserExists
|
|
takes a localpart and checks whether or not it exists in the database.
|
|
.Pp
|
|
.Fn UserCreate
|
|
creates a new user. It takes a localpart, which is assumed to be valid, and
|
|
a password.
|
|
.Pp
|
|
.Fn UserLock
|
|
takes a localpart and obtains a database reference to the user represented by that
|
|
localpart. It behaves analogously to
|
|
.Fn DbLock ,
|
|
and in fact uses it under the hood to ensure that the user can only be modified
|
|
by the thread that has locked the user.
|
|
.Fn UserUnlock
|
|
returns the user reference back to the database. It uses
|
|
.Fn DbUnlock
|
|
under the hood.
|
|
.Pp
|
|
.Fn UserAuthenticate
|
|
takes an access token, figures out what user it belongs to, and returns the
|
|
reference to that user. This function should be used by most endpoints that
|
|
require valid user authentication, since most endpoints are authenticated via
|
|
access tokens.
|
|
.Pp
|
|
.Fn UserLogin
|
|
is used for logging in a user. It takes the user's password, device ID, device
|
|
display name, and a boolean value indicating whether or not the client supports
|
|
refresh tokens. This function logs in the user and generates an access token to be
|
|
returned to the client.
|
|
.Pp
|
|
.Fn UserGetName
|
|
gets the name attached to a user object. It can be used for the few cases where
|
|
it's necessary to know the localpart of a user.
|
|
.Pp
|
|
.Fn UserCheckPassword
|
|
takes a password and verifies it against a user object. Telodendria does not
|
|
store passwords in plain text, so this function hashes the password and and
|
|
checks it against what's stored in the database.
|
|
.Pp
|
|
.Fn UserSetPassword
|
|
resets the given user's password by hashing a plain text password and
|
|
storing it in the database.
|
|
.Pp
|
|
.Fn UserDeactivate
|
|
deactivates a user such that it can no longer be used to log in, but
|
|
the username is still taken. This is to prevent future users from
|
|
pretending to be previous users of a given localpart.
|
|
.Pp
|
|
.Fn UserGetDevices
|
|
fetches the devices that belong to the user, in JSON format,
|
|
identical to what's stored in the database. In fact, this JSON is
|
|
still linked to the database, so it should not be freed with
|
|
.Fn JsonFree .
|
|
.Pp
|
|
.Fn UserAccessTokenGenerate ,
|
|
.Fn UserAccessTokenSave ,
|
|
and
|
|
.Fn UserAccessTokenFree
|
|
are used for managing individual access tokens on a user. They
|
|
operate on the UserAccessToken structure.
|
|
.Fn UserAccessTokenGenerate
|
|
takes the user localpart to generate the token for, the device ID,
|
|
for the token, and a boolean value indicating whether or not the token
|
|
should expire.
|
|
.Fn UserAccessTokenSave
|
|
writes the access token to the database.
|
|
.Pp
|
|
.Fn UserDeleteToken
|
|
and
|
|
.Fn UserDeleteTokens
|
|
delete a specific access token/refresh token pair, or all the access
|
|
and refresh tokens for a given user, respectively.
|
|
.Pp
|
|
.Fn UserIdParse
|
|
parses either a localpart or a fully-qualified Matrix ID.
|
|
.Fn UserIdFree
|
|
frees the result of this parsing.
|
|
.Sh RETURN VALUES
|
|
.Pp
|
|
.Fn UserValidate ,
|
|
.Fn UserHistoricalValidate ,
|
|
.Fn UserExists ,
|
|
.Fn UserUnlock ,
|
|
.Fn UserCheckPassword ,
|
|
.Fn UserSetPassword ,
|
|
.Fn UserDeactivate ,
|
|
.Fn UserAccessTokenSave ,
|
|
.Fn UserDeleteToken ,
|
|
and
|
|
.Fn UserDeleteTokens
|
|
all return a boolean value. Non-zero values indicate success, and zero values
|
|
indicate failure.
|
|
.Pp
|
|
.Fn UserCreate ,
|
|
.Fn UserLock ,
|
|
and
|
|
.Fn UserAuthenticate
|
|
return a pointer to a User, or NULL if an error occurred.
|
|
.Pp
|
|
.Fn UserGetName
|
|
returns a pointer to the string that holds the localpart of the user represented
|
|
by the given user pointer. This pointer should not be freed by the caller , as it
|
|
is used internally and will be freed when the user is unlocked.
|
|
.Pp
|
|
.Fn UserLogin
|
|
returns a UserLoginInfo struct, or
|
|
.Dv NULL
|
|
if something goes wrong.
|
|
All this information should be returned to the client that is logging in. If the
|
|
client doesn't support refresh tokens, then refreshToken will be NULL.
|
|
.Pp
|
|
.Fn UserGetDevices
|
|
returns a JSON object that is linked to the database, or NULL if
|
|
there was an error. The result should not be freed with
|
|
.Fn JsonFree
|
|
because it is still directly attached to the database. This object
|
|
is an exact representation of what is stored on the disk.
|
|
.Pp
|
|
.Fn UserAccessTokenGenerate
|
|
generates an access token structure that should be freed when it is
|
|
no longer needed, or
|
|
.Dv NULL
|
|
if there was a memory error.
|
|
.Pp
|
|
.Fn UserIdParse
|
|
returns a UserId structure that should be freed when it is no longer
|
|
needed, or
|
|
.Dv NULL
|
|
if there was a memory error.
|
|
.Sh SEE ALSO
|
|
.Xr Db 3
|