internal

For more information on the internal authentication backend and usage examples see Authentication. More...

Data Structures
struct	ua_authentication_legacy_decrypt_ctx
struct	ua_authentication_username_pw_info
	Information from a username/password token sent by a client in the ActivateSessionRequest. More...
struct	ua_authentication_issuedtoken_info
	Information from a issuedtoken token sent by a client in the ActivateSessionRequest. More...

Macros
#define	UA_AUTH_HASH_NONE   0
	Identifier for no hash algorithm (cleartext password)
#define	UA_AUTH_HASH_SHA256   1
	Identifier for SHA-256 hash algorithm.
#define	UA_AUTH_HASH_SHA512   2
	Identifier for SHA-512 hash algorithm.

Typedefs
typedef void(*	ua_authentication_legacy_decrypt_finished_cb) (void *cb_data, ua_statuscode result)
	Callback when decryption is finished. More...
typedef int(*	ua_authentication_check_username_pw_cb) (struct ua_authentication_username_pw_info *in, struct uasession_user_info *out, void *username_pw_auth_ctx)
	Callback for checking the authenticity of a username/password token. More...
typedef int(*	ua_authentication_check_issuedtoken_cb) (struct ua_authentication_issuedtoken_info *in, struct uasession_user_info *out, void *issuedtoken_auth_ctx)
	Callback for checking the authenticity of a issued token. More...

Functions
SERVER_EXPORT ua_statuscode	ua_authentication_legacy_decrypt_prepare (struct ua_authentication_legacy_decrypt_ctx *ctx, const struct uasession_channel *channel, const struct uasession_session *session, const struct seconv_params *params)
	Prepare a context for decrypting a user token payload in the legacy encrypted secret format. More...
SERVER_EXPORT ua_statuscode	ua_authentication_legacy_decrypt_begin (struct ua_authentication_legacy_decrypt_ctx *ctx, struct ua_bytestring *buffer)
	Start the asynchronous decryption of user token data. More...
SERVER_EXPORT void	ua_authentication_legacy_decrypt_clear (struct ua_authentication_legacy_decrypt_ctx *ctx)
	Clears resources from the ctx, may be freed afterwards.
ua_statuscode	ua_authentication_issuedtoken (struct ua_authentication_ctx *ctx, struct ua_issuedidentitytoken *token, struct uasession_user_info *user)
void	ua_authentication_finish_issuedtoken_check (void *issuedtoken_auth_ctx)
	Must be called after user authentication is finished. More...
int	ua_authentication_check_issuedtoken (struct ua_authentication_issuedtoken_info *in, struct uasession_user_info *out, void *auth_ctx)
	Default implementation of ua_authentication_check_username_pw_cb which currently only sets a proper bad statuscode. More...
ua_statuscode	ua_authentication_username (struct ua_authentication_ctx *ctx, struct ua_usernameidentitytoken *token, struct uasession_user_info *user)
void	ua_authentication_finish_username_pw_check (void *username_pw_auth_ctx)
	Must be called after user authentication is finished. More...
int	ua_authentication_check_username_pw (struct ua_authentication_username_pw_info *in, struct uasession_user_info *out, void *auth_ctx)
	Default implementation of ua_authentication_check_username_pw_cb which uses the internal user management.
void	ua_authentication_dispatch_username_pw (void *username_pw_auth_ctx, struct ua_authentication_username_pw_info *in, struct uasession_user_info *out)
SERVER_EXPORT int	ua_authentication_set_username_pw_callback (ua_authentication_check_username_pw_cb cb)
	Set the username/password authentication callback. More...
void	ua_authentication_dispatch_issuedtoken (void *issuedtoken_auth_ctx, struct ua_authentication_issuedtoken_info *in, struct uasession_user_info *out)
SERVER_EXPORT int	ua_authentication_set_issuedtoken_callback (ua_authentication_check_issuedtoken_cb cb)
	Set the IssuedToken authentication callback. More...
SERVER_EXPORT bool	ua_authentication_user_exists (const struct ua_string *username)
	Check if a user exists for authentication. More...
SERVER_EXPORT ua_statuscode	ua_authentication_check_password (const struct ua_string *username, const struct ua_bytestring *password)
	Check the password for a user. More...
SERVER_EXPORT int	ua_authentication_add_user (uint8_t hash_alg, const char *username, const char *salt, const char *hash)
	Add a user to authentication. More...
SERVER_EXPORT int	ua_authentication_change_password (uint8_t hash_alg, const char *username, const char *salt, const char *hash)
	Change the password of an existing user. More...
SERVER_EXPORT int	ua_authentication_remove_user (const char *username)
	Remove a user from authentication. More...
SERVER_EXPORT int	ua_authorization_write_to_filestream (struct ua_filestream *stream)
	Write current users with passwords to a filedescriptor. More...

Detailed Description

For more information on the internal authentication backend and usage examples see Authentication.

Typedef Documentation

ua_authentication_check_issuedtoken_cb

typedef int(* ua_authentication_check_issuedtoken_cb) (struct ua_authentication_issuedtoken_info *in, struct uasession_user_info *out, void *issuedtoken_auth_ctx)

Callback for checking the authenticity of a issued token.

The data from the token is provided via the in argument. For this callback the token_data is the raw data from the token and may still be encrypted, if required by the token policy. The callback is responsible for checking the token is correctly encrypted according to the policy configured in the server, decrypting the token and checking its content.

The result of the check must be written to the out argument. For this callback the token_type and policy_id are already set correctly, the result is initialized to a bad statuscode. The client_user_id and token specific data must be set in the callback.

The callback finishes asynchronous, to indicate the check is finished ua_authentication_finish_issuedtoken_check must be called with issuedtoken_auth_ctx. Synchronous implementations may call that function directly from within the callback.

The return value must always be 0.

ua_authentication_check_username_pw_cb

typedef int(* ua_authentication_check_username_pw_cb) (struct ua_authentication_username_pw_info *in, struct uasession_user_info *out, void *username_pw_auth_ctx)

Callback for checking the authenticity of a username/password token.

The data from the token is provided via the in argument.

The result of the check must be written to the out argument. For this callback all the fields of that struct are already set accordingly, only the result must be set to zero to accept a user. However an application which wants to implement an additional user mapping may change the username.

The callback finishes asynchronous, to indicate the check is finished ua_authentication_finish_username_pw_check must be called with username_pw_auth_ctx. Synchronous implementations may call that function directly from within the callback.

The return value must always be 0.

ua_authentication_legacy_decrypt_finished_cb

typedef void(* ua_authentication_legacy_decrypt_finished_cb) (void *cb_data, ua_statuscode result)

Callback when decryption is finished.

In case of a good result the decrypted data is in the buffer given to ua_authentication_legacy_decrypt_begin.

Function Documentation

ua_authentication_add_user()

SERVER_EXPORT int ua_authentication_add_user	(	uint8_t	hash_alg,
		const char *	username,
		const char *	salt,
		const char *	hash
	)

Add a user to authentication.

For an example how to use this function see Authentication.

Parameters

hash_alg	Hash algorithm to use e.g. UA_AUTH_HASH_SHA256.
username	Name of the user add.
salt	Salt to hash the password with.
hash	The password hash as hexadecimal string.

Returns

Zero on success or errorcode on failure.

ua_authentication_change_password()

SERVER_EXPORT int ua_authentication_change_password	(	uint8_t	hash_alg,
		const char *	username,
		const char *	salt,
		const char *	hash
	)

Change the password of an existing user.

If the user does not yet exist an errorcode is returned. If the function fails the previous password will stay valid.

The parameters for this function are the same as for ua_authentication_add_user.

Returns

Zero on success or errorcode on failure.

ua_authentication_check_issuedtoken()

int ua_authentication_check_issuedtoken	(	struct ua_authentication_issuedtoken_info *	in,
		struct uasession_user_info *	out,
		void *	auth_ctx
	)

Default implementation of ua_authentication_check_username_pw_cb which currently only sets a proper bad statuscode.

In future versions this implementation may be able to handle specific issued tokens.

ua_authentication_check_password()

SERVER_EXPORT ua_statuscode ua_authentication_check_password	(	const struct ua_string *	username,
		const struct ua_bytestring *	password
	)

Check the password for a user.

Parameters

username	Name of the user.
password	Cleartext password the user provided.

Returns

Zero if the password is correct, bad statuscode otherwise.

ua_authentication_finish_issuedtoken_check()

void ua_authentication_finish_issuedtoken_check

(

void *

issuedtoken_auth_ctx

)

Must be called after user authentication is finished.

May be called truly asynchronously or from within the authentication callback.

Parameters

issuedtoken_auth_ctx

Pointer passed to ua_authentication_check_issuedtoken_cb

ua_authentication_finish_username_pw_check()

void ua_authentication_finish_username_pw_check

(

void *

username_pw_auth_ctx

)

Must be called after user authentication is finished.

May be called truly asynchronously or from within the authentication callback.

Parameters

username_pw_auth_ctx

Pointer passed to ua_authentication_check_username_pw_cb

ua_authentication_legacy_decrypt_begin()

SERVER_EXPORT ua_statuscode ua_authentication_legacy_decrypt_begin	(	struct ua_authentication_legacy_decrypt_ctx *	ctx,
		struct ua_bytestring *	buffer
	)

Start the asynchronous decryption of user token data.

Parameters

ctx	A decrypt context prepared with ua_authentication_legacy_decrypt_prepare.
buffer	The buffer with data to decrypt, the data is decrypted inplace, so after successfull decryption the buffer contains the decrypted data.

Returns

Zero on success, in this case the callback with the actual decryption result will be called when finished.

ua_authentication_legacy_decrypt_prepare()

SERVER_EXPORT ua_statuscode ua_authentication_legacy_decrypt_prepare	(	struct ua_authentication_legacy_decrypt_ctx *	ctx,
		const struct uasession_channel *	channel,
		const struct uasession_session *	session,
		const struct seconv_params *	params
	)

Prepare a context for decrypting a user token payload in the legacy encrypted secret format.

The context ctx must be allocated by caller and cleared with ua_authentication_legacy_decrypt_clear if this function succeeds. A context may only be used for a single decryption.

The fields cb and cb_data must be set directly in the struct.

ua_authentication_remove_user()

SERVER_EXPORT int ua_authentication_remove_user

(

const char *

username

)

Remove a user from authentication.

Parameters

username

Name of the user to remove.

Returns

Zero on success or errorcode on failure.

ua_authentication_set_issuedtoken_callback()

SERVER_EXPORT int ua_authentication_set_issuedtoken_callback

(

ua_authentication_check_issuedtoken_cb

cb

)

Set the IssuedToken authentication callback.

For a description of the callback see ua_authentication_check_issuedtoken_cb.

The default callback returns an error as there is no IssuedToken implementation provided by the SDK.

ua_authentication_set_username_pw_callback()

SERVER_EXPORT int ua_authentication_set_username_pw_callback

(

ua_authentication_check_username_pw_cb

cb

)

Set the username/password authentication callback.

For a description of the callback see ua_authentication_check_username_pw_cb.

The default callback uses the internal user management.

ua_authentication_user_exists()

SERVER_EXPORT bool ua_authentication_user_exists

(

const struct ua_string *

username

)

Check if a user exists for authentication.

Parameters

username

Name of the user.

Returns

True if user exists, false otherwise.

ua_authorization_write_to_filestream()

SERVER_EXPORT int ua_authorization_write_to_filestream

(

struct ua_filestream *

stream

)

Write current users with passwords to a filedescriptor.

Parameters

stream

File stream to write information to.

Returns

Zero on success or errorcode on failure.