Data Structures
struct	_authfuncs
	Describes the callback functions that should be implemented by an auth module. More...

struct	_logininfo
	Structure passed between invalidation routines. More...

struct	_mapinfo
	The map information object. More...

struct	_nodeinfo
	The RTTP node object. More...

struct	_object
	Callback that is called when an object changes initial state. More...

struct	_session
	The RTTP Session Object. More...

struct	_user
	The user object. More...

Macros
#define	MAX_OBNAME 4096

#define	MAX_USERNAME 255

#define	SESSION_ID_LEN_DEFAULT 22

#define	SESSION_ID_LEN_MAX 256

#define	SESSION_ID_LEN_MIN 6

Typedefs
typedef void(*	eventcallback_t) (void *data, short event, short code)
	Definition of the callback function for delayed events. More...

typedef struct _session_request_retry	session_request_retry_t
	Structure used to hold request retry information when things are overloaded. More...

Enumerations

Functions
AUTH_EXPORT int	auth_create_object (char *name, object_type_t type)
	Create an object within the Liberator. More...

AUTH_EXPORT void	auth_delete_object (char *name)
	Delete an object within the Liberator. More...

AUTH_EXPORT int	auth_eject_all_sessions_by_app_id (const char *app_id)
	Eject all logged in sessions that are using the specified application id. More...

AUTH_EXPORT int	auth_eject_sessions (user_t *user, int num)
	Eject sessions. More...

AUTH_EXPORT int	auth_eject_sessions_by_app_id (user_t user, int num, char app_id)
	Eject sessions with matching application id. More...

AUTH_EXPORT int	auth_eject_sessions_by_machine_id (user_t user, int num, char machine_id)
	Eject sessions based on the username by machine id. More...

AUTH_EXPORT int	auth_eject_username_by_app_id (char name, int num, char app_id)
	Wrapper for auth_eject_username_by_app_id that takes the user name instead of a _user pointer. More...

AUTH_EXPORT int	auth_eject_username_by_machine_id (char name, int num, char machine_id)
	Wrapper for auth_eject_sessions_by_machine_id that takes the user name instead of a _user pointer. More...

AUTH_EXPORT int	auth_eject_username_sessions (char *name, int num)
	Wrapper for auth_eject_sessions that takes the user name instead of a _user pointer. More...

char *	auth_filename_expand (char format, char buf, size_t buflen)
	Expand a filename pattern into a fully qualified filename. More...

AUTH_EXPORT size_t	auth_get_extra_data (char token, char buffer, size_t max_len)
	Gets the extra data from the token. The extra data is expected to be the 4th part of the ~ separated token and it is expected NOT to be the last part. If the 4th part is the end of the token then it must be the user name and there is no extra data. More...

AUTH_EXPORT int	auth_get_login_count (char *username)
	Get the number of current logins for a username. More...

AUTH_EXPORT char *	auth_get_tobouser (const char *username)
	Get the TOBO user setting. More...

AUTH_EXPORT char *	auth_get_token_parameter (const char keymaster_token, const char parameter_to_query)
	Return a value for the given field within a keymaster token. More...

AUTH_EXPORT int	auth_get_user_session_count_by_name (char *object_name)
	Return the number of active sessions. More...

AUTH_EXPORT void	auth_invalidate_all_sessions (int flags)
	Invalidate all sessions for all users in the system. More...

AUTH_EXPORT void	auth_invalidate_object (char *name, int flags)
	Invalidate an object. More...

AUTH_EXPORT void	auth_invalidate_sessions (user_t *user, int num, int flags)
	Invalidate all sessions for a user. More...

AUTH_EXPORT void	auth_invalidate_sessions_by_name (char *name, int num, int flags)
	Invalidate all sessions for a username. More...

AUTH_EXPORT void	auth_listener_throttle (char session_id, char object_name, char *command)
	Throttle an individual subscription on a user's session. More...

AUTH_EXPORT int	auth_new_subscription (char prefix, char subject, void user_context, void(loaded)(void , int, char ), void(failed)(void , int, char ), void(status)(void , int, char , int))
	Creates a subscription for use with auth_subscribe and auth_unsubscribe. More...

AUTH_EXPORT void	auth_reset_tobouser (const char *username)
	Remove the tobouser for the user specified by the session. More...

AUTH_EXPORT void	auth_session_throttle (char session_id, char command)
	Throttle a users' session. More...

AUTH_EXPORT void	auth_set_tobouser (const char username, const char tobouser)
	Set the tobo user for the specified user. More...

AUTH_EXPORT void	auth_subscribe (int subscriptionId)
	Subscribes to subject. More...

AUTH_EXPORT void	auth_unsubscribe (int subscriptionId)
	Unsubscribes to subject. More...

AUTH_EXPORT void	auth_unsubscribe_free_data (int subscriptionId, void free_context, void(free_data_cb)(void , void ))
	Unsubscribes to subject and frees the user context on the thread handling auth updates. More...

AUTH_EXPORT int	auth_verify_signature_username (char expected_username, char token)
	Verify that the supplied token is for the expected username. More...

AUTH_EXPORT void	infoob_add_data (object_t obj, const int fields, const char **values, int count)
	Adds an array of values to a system object. More...

AUTH_EXPORT void	infoob_add_data_generic (object_t obj, const char fieldnames, const char *values, int count)
	Adds an array of values to a system object. More...

AUTH_EXPORT int	infoob_add_field (const char *name, int flags)
	Creates a new field for updating system objects. More...

AUTH_EXPORT void	infoob_add_int (object_t *obj, int field, int value)
	Adds a numerical value to a system object. More...

AUTH_EXPORT void	infoob_add_int_generic (object_t obj, const char fieldname, int value)
	Adds a numerical value to a system object. More...

AUTH_EXPORT void	infoob_add_str (object_t obj, int field, const char value)
	Adds a value to a system object. More...

AUTH_EXPORT void	infoob_add_str_generic (object_t obj, const char fieldname, const char *value)
	Adds a value to a system object. More...

AUTH_EXPORT object_t *	infoob_new_object (const char *name)
	Creates a new system object. More...

AUTH_EXPORT char *	object_get_value (object_t obj, int32_t fieldnum, char buf, int len)
	The function returns the value of a specified field in an object. More...

AUTH_EXPORT int	signature_check (char key_id, char token)
	Provides a mechanism for validating a KeyMaster-generated encrypted single-use token. More...

Detailed Description

The main Liberator include file

Macro Definition Documentation

#define MAX_OBNAME 4096

Maximum size of an RTTP object name in bytes

#define MAX_USERNAME 255

Maximum size of an RTTP username in bytes

#define SESSION_ID_LEN_DEFAULT 22

default session id length

#define SESSION_ID_LEN_MAX 256

maximum session id length

#define SESSION_ID_LEN_MIN 6

minimum session id length

Typedef Documentation

typedef struct _session_request_retry session_request_retry_t

Structure used to hold request retry information when things are overloaded.

Enumeration Type Documentation

enum _auth_perm_operation

Operations for the __authfuncs::auth_global_permission_update() function.

Enumerator
AUTH_PERM_ADD	The key has been added
AUTH_PERM_DELETE	The key has been deleted
AUTH_PERM_UPDATE	Updated values are availabe for the key

enum _auth_result

Return codes for the authentication functions.

Some of these return codes are only valid for certain functions

enum _object_type

Definition of RTTP object types.

Enumerator
UNKNOWN_TYPE	Unknown object type, objects are created in this state
USER_TYPE	User-object object type
DIRECTORY_TYPE	Directory object type
PAGE_TYPE	Page object type
RECORD_TYPE	Record object type
NEWS_TYPE	News object type
STORY_TYPE	News story object type
RECORD_TYPE2	Type 2 record object type
RECORD_TYPE3	Type 3 object type
CHAT_TYPE	Chat object type
CONTAINER_TYPE	Container object type
INFO_TYPE	System-object object type
GENERIC_TYPE	Generic object type
JSON_TYPE	JSON object type

Function Documentation

AUTH_EXPORT int auth_create_object	(	char *	name,
		object_type_t	type
	)

Create an object within the Liberator.

Parameters

name	- The name of the object
type	- The type of the object that should be created

Return values

AUTH_OK	- Object created ok
AUTH_DENY	- Object not created - already exists
AUTH_ERROR	- Object not created, cannot create

AUTH_EXPORT void auth_delete_object ( char * name )

Delete an object within the Liberator.

Parameters

name	- The name of the object to delete

char* auth_filename_expand	(	char *	format,
		char *	buf,
		size_t	buflen
	)

Expand a filename pattern into a fully qualified filename.

Parameters

format	- Format of filename to expand
buf	- Buffer to expand into
buflen	- Length of the expansion buffer

Returns: The input variable buf containing an expanded filename

This function will expand the following tokens in the supplied argument:

%h The hostname
%a The application name (as set by the configuration option application-name)
%n The application name (as set by the configuration option application-name)
%r The application root (as set by the configuration option application-root)
%u The home directory of the process owner.

AUTH_EXPORT size_t auth_get_extra_data	(	char *	token,
		char *	buffer,
		size_t	max_len
	)

Gets the extra data from the token. The extra data is expected to be the 4th part of the ~ separated token and it is expected NOT to be the last part. If the 4th part is the end of the token then it must be the user name and there is no extra data.

Parameters

token	- The KeyMaster password / token to get the extra data from.
buffer	- Buffer where the resulting (null-terminated) extra data string will be written.
max_len	- The maximum available space in the destination buffer.

Returns: The length of the extra data written to the buffer (not including '\0').

AUTH_EXPORT int auth_get_login_count ( char * username )

Get the number of current logins for a username.

Parameters

username - The username to get the login count for

Return values

-	The current login count

The value returned takes into account the number of logins from other members of the Liberator cluster

AUTH_EXPORT char* auth_get_tobouser ( const char * username )

Get the TOBO user setting.

Parameters

username = The user to query for its tobo user setting

Note: This method returns a duplicate. If using the C API on the callback thread, it may be easier to query the user_t structure directly.

AUTH_EXPORT char* auth_get_token_parameter	(	const char *	keymaster_token,
		const char *	parameter_to_query
	)

Return a value for the given field within a keymaster token.

Parameters

keymaster_token	- The keymaster token
parameter_to_query	- The name of the field

Returns: The value of the field given in parameter_to_query or NULL if the field does not exist

Will return a copy of the value of a given field within the keymaster token or NULL

AUTH_EXPORT int auth_get_user_session_count_by_name ( char * username )

Return the number of active sessions.

Parameters

username - Username

Returns: The number of active sessions

Note: This routine should use a read lock to access the hash table but it can't. This is because it can be called with the write lock on and a read lock access nested within a write lock access causes problems with the subsequent write locks.

AUTH_EXPORT int auth_new_subscription	(	char *	prefix,
		char *	subject,
		void *	user_context,
		void()(void , int, char *)	loaded,
		void()(void , int, char *)	failed,
		void()(void , int, char *, int)	status
	)

Creates a subscription for use with auth_subscribe and auth_unsubscribe.

Parameters

prefix	Subject prefix to be prepended to all subjects subscribed to, must not be null.
subject	Subject without prefix, must not be null.
user_context	Only passed into loaded and failed callbacks.
loaded	Called once all data has been successfully received by the Liberator, must not be null.
failed	Called if there is an error before the subcription has been loaded, must not be null.
status	Called when a status is received, must not be null.

Returns: Id to be used with auth_subscribe and auth_unsubscribe.

AUTH_EXPORT void auth_reset_tobouser ( const char * username )

Remove the tobouser for the user specified by the session.

Parameters

username - The user to clear the tobouser setting

AUTH_EXPORT void auth_set_tobouser	(	const char *	username,
		const char *	tobouser
	)

Set the tobo user for the specified user.

Parameters

username	- The user that should be assigned the tobouser
tobouser	- The tobo username for this user

AUTH_EXPORT void auth_subscribe ( int subscriptionId )

Subscribes to subject.

Parameters

subscriptionId from auth_new_subscription.

This function enables the Liberator Auth Module subscribe to a subject. If the subject is a container its constituents will also be subscribed to (with prefix prepended). Data from all permission objects subscribed to will be passes to auth_global_permission_update. As there is no other way to access the data you should only subscribe to permissions or containers of permissions. The subject passed into loaded or failed includes the prefix. Either loaded or failed will be called once. If there is no response the request will fail after the configured request-timeout. If the subscription fails it is automatically unsubscribed.

AUTH_EXPORT void auth_unsubscribe ( int subscriptionId )

Unsubscribes to subject.

Parameters

subscriptionId the id returned from auth_subscribe.

This function unsubscribes. If the subscription fails it is automatically unsubscribed.

AUTH_EXPORT void auth_unsubscribe_free_data	(	int	subscriptionId,
		void *	free_context,
		void()(void , void *)	free_data_cb
	)

Unsubscribes to subject and frees the user context on the thread handling auth updates.

Parameters

subscriptionId	the id returned from auth_subscribe.
free_context	The context to be passed into the free_data_cb function as the second argument
free_data_cb	callback taking two void pointers as arguments, the first one representing the user context associated with the subscription, the second one representing the argument free_context

This function unsubscribes and calls the function free_data_cb after doing so such that resources can be cleaned up safely. If the subscription fails it is automatically unsubscribed.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation