auth.h File Reference

---

Detailed Description

The web authentication module interface of Netzer.

Software License

See the MBCSL for details.

Author:

Sven Schlender (kontakt at mobacon dot de)

Date:

2011-02-03

enum	AuthReturnCodes_t { AUTH_PENDING = 0, AUTH_FAILED, AUTH_OK, AUTH_READONLY }
	This state enumerator is used for authentication handling on a generic socket (see AuthHandleAuthentification for more details). More...
void	AuthReload (void)
	Call this function for initial or repeated loading of all user/password combinations from persistent storage (EEPROM) to quick accessable RAM.
void	AuthStoreInEEPROM (CHAR UserID)
	Store the authentication data for the given user from RAM to persistent storage (EEPROM).
void	AuthReset (CHAR UserID)
	The given user is reseted to a well known factory state.
void	AuthProcessPostData (BYTE *pControl, BYTE *pValue, DWORD Value)
	The function handles the call from the user set webpage form and processes new user data.
void	AuthExecuteApplCommand (BYTE RawCommandFromWeb)
	Commands to application (like restart, shut down, reset to factory settings) are filtered through this function.
BYTE	HTTPCheckAuth (BYTE *cUser, BYTE *cPass)
	The function is called after authentication is entered.
void	AuthSetUserForDialog (BYTE UserID)
	Call this function during the session of a HTTP POST of the user set webpage.
void	AuthInit (void)
	Call this function to initialize the socket based authentication here.
void	AuthStartAuthentification (TCP_SOCKET Socket)
	If a socket needs authentication than call this function directly once after the connection.
AuthReturnCodes_t	AuthHandleAuthentification (TCP_SOCKET Socket)
	Call this function periodically from the socket handler until one of the final states is reached (answer is not AUTH_PENDING).

---

Enumeration Type Documentation

enum AuthReturnCodes_t

This state enumerator is used for authentication handling on a generic socket (see AuthHandleAuthentification for more details).

Enumerator:

AUTH_PENDING	State handling is pending, call again later.
AUTH_FAILED	Authentication has failed due unknown user name or pass.
AUTH_OK	Authentication was successful.
AUTH_READONLY	Authentication was successful. Guest has logged in.

---

Function Documentation

void AuthExecuteApplCommand

(

BYTE

RawCommandFromWeb

)

Commands to application (like restart, shut down, reset to factory settings) are filtered through this function.

Only a authenticated user with enough permissions can execute dedicated application commands.

Parameters:

RawCommandFromWeb

The command as numeric value directly from a GET call (see webpage index.htm for expressions).

AuthReturnCodes_t AuthHandleAuthentification

(

TCP_SOCKET

Socket

)

Call this function periodically from the socket handler until one of the final states is reached (answer is not AUTH_PENDING).

The function uses the given socket as handle for managing several authentication sessions in parallel. Also it uses the socket to print login informations and receive username and password.

Parameters:

Socket

Give the TCP socket handler to associate the socket with the authentication data state.

Returns:

If the answer is AUTH_PENDING than later call this function again. Else check the code for further processing - a further call is not necessary.

void AuthInit

(

void

)

Call this function to initialize the socket based authentication here.

Do the calling once on startup.

void AuthProcessPostData	(	BYTE *	pControl,
		BYTE *	pValue,
		DWORD	Value
	)

The function handles the call from the user set webpage form and processes new user data.

Parameters:

	pControl	A pointer to the name of the form control.
	pValue	A pointer to the value of the control as a string.
	Value	The preprocessed numeric version of the value.

void AuthReset

(

CHAR

UserID

)

The given user is reseted to a well known factory state.

Parameters:

UserID

The zero based user id for which username and password are restored. -1 restores all known users at once.

void AuthSetUserForDialog

(

BYTE

UserID

)

Call this function during the session of a HTTP POST of the user set webpage.

The process function than operates with the given SetID.

Parameters:

UserID

The zero based user id on which the form processing is be done.

void AuthStartAuthentification

(

TCP_SOCKET

Socket

)

If a socket needs authentication than call this function directly once after the connection.

The function initializes the state machine and other socket based data to start the authentication process.

Parameters:

Socket

Give the TCP socket handler to bind the socket to authentication data state. The caller can use the socket handle for later state machine handling of the authentication (AuthHandleAuthentification).

void AuthStoreInEEPROM

(

CHAR

UserID

)

Store the authentication data for the given user from RAM to persistent storage (EEPROM).

Parameters:

UserID

The zero based user id for which username and password are stored. -1 stores all known users at once.

BYTE HTTPCheckAuth	(	BYTE *	cUser,
		BYTE *	cPass
	)

The function is called after authentication is entered.

It must check whether the user/password combination is valid.

Parameters:

	cUser	Pointer to the string of the requesting user.
	cPass	Pointer to the string of the password of requesting user.

Return values:

	0	User/password combination is invalid.
	Other	User/password combination is valid.