The main security class to be used by the administration application. More...

#include <ms_security.hpp>

Inheritance diagram for ms_security:

Collaboration diagram for ms_security:

Public Types
enum	USERID_SORTBY { USERID_SORTBY_ID = 1, USERID_SORTBY_LOGINNAME = 2, USERID_SORTBY_FULLNAME = 3 }
	Sorting criterion to retrieve all users. More...
Public Member Functions
	ms_security ()
	The constructor loads all the groups and users information from the `../config` directory.
bool	addNewGroup (const std::string sessionID, const int groupID, const std::string groupName)
	Add a new group to the current list of groups.
bool	addNewUser (const std::string sessionID, const int userID, const std::string userName, const std::string password, const time_t passwordExpiry, const std::string fullName, const std::string emailAddress, const ms_user::usertype userType, const bool enabled)
	Add a new user to the current list of users.
void	appendErrors (const ms_errors &src)
	Copies all errors from another instance and appends them at the end of own list.
void	clearAllErrors ()
	Remove all errors from the current list of errors.
void	copyFrom (const ms_errors *right)
	Use this member to make a copy of another instance.
bool	createDefaults (const std::string sessionID="")
	Create default users, groups and sessions.
bool	deleteGroup (const std::string sessionID, const std::string groupName)
	Delete a group from the system.
bool	deleteUser (const std::string sessionID, const std::string userName)
	Delete a user from the system.
ms_user::customParams_t	getAllCustomParamsForUser (const ms_user &user) const
	Return a 'map' of all the custom parameters for a user.
std::vector< int >	getAllGroupIDs () const
	Return a list of all group IDs.
std::vector< int >	getAllUserIDs (const USERID_SORTBY sortby=USERID_SORTBY_ID) const
	Return a list of all user IDs.
const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.
ms_group	getGroup (const std::string groupName) const
	Return a group given the name .
ms_group	getGroupFromID (const int groupID) const
	Return a group given the ID.
std::vector< std::string >	getIntegraUsers () const
	Returns a list of Integra users.
int	getLastError () const
	Return the error description of the last error that occurred.
std::string	getLastErrorString () const
	Return the error description of the last error that occurred.
ms_security_options	getMascotSecurityOptions () const
	Return the security options.
ms_security_tasks	getPermittedTasksForUser (const std::string name) const
	Return a list of the tasks permitted for the user.
ms_security_tasks	getTasks () const
	Return the complete list of possible tasks available.
ms_user	getUser (const std::string userName) const
	Return a user given the name.
ms_user	getUserFromID (const int userID) const
	Return a user given the ID.
bool	isTaskExists (const int taskID) const
	Return true if a security task with the given ID exists.
bool	isUserExists (const int userID) const
	Return true if a user with this ID exists.
bool	isValid () const
	Call this function to determine if there have been any errors.
std::vector< int >	sortUsers (std::vector< ms_user * > &vecUsers, const USERID_SORTBY sortby) const
	Sort a list of users and return a list of user IDs.
bool	updateAllSessionFiles (bool deleteOnly=false)
	Update all the session files after making a change to parameters.
bool	updateGroup (const std::string sessionID, const ms_group &group)
	Call this after updating any details for a group.
bool	updatePassword (const std::string sessionID, const std::string userName, const std::string oldPassword, const std::string newPassword)
	Update the password for an existing user.
bool	updateUser (const std::string sessionID, const ms_user user)
	Update an existing user int the system.

Detailed Description

The main security class to be used by the administration application.

Other applications should just need to use ms_session.

When an object of this class is created, it loads all the users, groups tasks and options into memory.

Member Enumeration Documentation

enum USERID_SORTBY

Sorting criterion to retrieve all users.

Enumerator:

USERID_SORTBY_ID	Sort the list of users id by id.
USERID_SORTBY_LOGINNAME	Sort the list of users id by login name (its displayed name)
USERID_SORTBY_FULLNAME	Sort the list of users id by full name.

Constructor & Destructor Documentation

ms_security ( )

The constructor loads all the groups and users information from the ../config directory.

The administration program should use this constructor to load all users, groups and tasks. New users and groups should be added through this interface.

Member Function Documentation

bool addNewGroup	(	const std::string	sessionID,
		const int	groupID,
		const std::string	groupName
	)

Add a new group to the current list of groups.

To add a new group, call this function first. If the function returns true, then get the group using getGroup(), add users and tasks to the group and then call updateGroup().

Parameters:

sessionID This is the session id for the administrator who is adding the user. A valid session ID with administrator rights is required, and all additions of users and groups are logged using the details in the session ID.

groupID Can be set to -1 in which case the system provides a new unique ID. If a value is provided, and there is already a group with this ID, then the function will return false and the error ms_errs::ERR_MSP_SECURITY_DUPE_GROUP_ID.

groupName

Is the name of the new group to be added. This must not contain spaces or any of the following characters:

><\\/`;,+*"

If there is already a group with this name, then the function will return false and set the error ms_errs::ERR_MSP_SECURITY_DUPE_GROUP_NAME.

Returns:: True if the function succeeds. The function will fail if the session is invalid, or doesn't have administrator rights. The function will also fail if there is a group with a the same name or the same ID.

bool addNewUser	(	const std::string	sessionID,
		const int	userID,
		const std::string	userName,
		const std::string	password,
		const time_t	passwordExpiry,
		const std::string	fullName,
		const std::string	emailAddress,
		const ms_user::usertype	userType,
		const bool	enabled
	)

Add a new user to the current list of users.

Use this function, rather than ms_user::ms_user to add a new user to the system.

Possible errors are:

Parameters:

sessionID	This is the session id for the administrator who is adding the user. A valid session ID with administrator rights is required, and all additions of users and groups are logged using the details in the session ID.
userID	Can be set to -1 in which case the system provides a new unique ID. If a value is provided, and there is already a user with this ID, then the function will return false and set the error ms_errs::ERR_MSP_SECURITY_DUPE_USER_ID.
userName	The user name must not contain spaces or any of the following characters: ><\\/`;,+*" If there is already a user with this name, then the function will return false and set the error ms_errs::ERR_MSP_SECURITY_DUPE_USER_NAME.
password	The password length must be greater than or equal to ms_security_options::getMinimumPasswordLength() unless the passwordExpiry parameter is set to 1, in which case the user will be prompted for a new password when they log in.
passwordExpiry	is the time in seconds since Jan 1, 1970 when the password will expire. See ms_security_options::getDefaultPasswordExpiryTime() for details. A value of '0'is used to indicate that the password should never expire. A value of 'now' or 1 can be used to force the user to change their password next time they log in.
fullName	Can be any number of characters, but ideally should not be left blank.
emailAddress	Can be any number of characters, but ideally should not be left blank. No error checking is performed in this function.
userType	must be ascertained correctly by the calling application, since there is no error checking in this function. Normally, this function should only be called with one of ms_user::USER_NORMAL ms_user::USER_COMPUTER_NAME ms_user::USER_IP_ADDRESS ms_user::USER_AGENT_STRING or ms_user::USER_WEBAUTH The type should never be ms_user::USER_SECURITY_DISABLED
enabled	Should normally be set to true to allow the user to login.

Returns:: True if successful.

void appendErrors ( const ms_errors & src ) [inherited]

Copies all errors from another instance and appends them at the end of own list.

Parameters:

src	The object to copy the errors across from. See Maintaining object references: two rules of thumb.

void clearAllErrors ( ) [inherited]

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also:: isValid(), getLastError(), getLastErrorString(), getErrorHandler()

Examples:: common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.

void copyFrom ( const ms_errors * right ) [inherited]

Use this member to make a copy of another instance.

Parameters:

right is the source to initialise from

bool createDefaults ( const std::string sessionID = "" )

Create default users, groups and sessions.

This function should be called by the installation program to create all the default users, default groups, default sessions etc. if they don't already exist.

This function creates:

An 'admin' user with ID: ms_user::USERID_ADMINISTRATOR.
A 'guest' user with ID: ms_user::USERID_GUEST. This user account is however disabled.
An 'Administrators' group with ID: ms_group::GROUPID_ADMINISTRATORS. The admin user is added to this group, which also has ms_security_tasks::SECTASK_ADMINPAGES, ms_security_tasks::SECTASK_KILLALLTASK, ms_security_tasks::SECTASK_ACCESSDBSETUP, and ms_security_tasks::SECTASK_VIEWCONFIGUSINGMSSTATUS rights assigned.
A 'Guests' group with the ID: ms_group::GROUPID_GUESTS. The guest user is added, along with a few minimal access rights.

Parameters:

sessionID Will generally be the built in command line session that is automatically created for any programs not being run from the web server.

Returns:: True if the function succeeds. Possible errors are: ms_errs::ERR_MSP_SECURITY_INVALID_SESSION_ID, ms_errs::ERR_MSP_SECURITY_NOT_ADMIN_SESSION and all errors that can be set from calling addNewUser() and addNewGroup().

bool deleteGroup	(	const std::string	sessionID,
		const std::string	groupName
	)

Delete a group from the system.

Possible error values are:

Parameters:

sessionID	This is the session id for the administrator who is deleting the group. A valid session ID with administrator rights is required, and all deletions of users and groups are logged using the details in the session ID.
groupName	Needs to be a valid user name.

Returns:: Will return true if the function succeeds in deleting the group. Otherwise, it will return false and set just one of the above errors.

bool deleteUser	(	const std::string	sessionID,
		const std::string	userName
	)

Delete a user from the system.

Possible error values are:

Parameters:

sessionID	This is the session id for the administrator who is deleting the user. A valid session ID with administrator rights is required, and all deletions of users and groups are logged using the details in the session ID.
userName	Needs to be a valid user name.

Returns:: Will return true if the function succeeds in deleting the user Otherwise, it will return false and set just one of the above errors.

ms_user::customParams_t getAllCustomParamsForUser ( const ms_user & user ) const

Return a 'map' of all the custom parameters for a user.

If an invalid user object is passed, then the returned object will be empty

Customer parameters for a user can originate from the user or group settings. Values at the user level overwrite values at the group level. See Using custom parameters

Parameters:

user	Needs to be a valid user object.

Returns:: a 'map' of custom parameters and values.

std::vector< int > getAllGroupIDs ( ) const

Return a list of all group IDs.

To find details of each group, call getGroupFromID().

Returns:: An array of user IDs. See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

std::vector< int > getAllUserIDs ( const USERID_SORTBY sortby = USERID_SORTBY_ID ) const

Return a list of all user IDs.

To find details of each user, call getUserFromID().

Parameters:

sortby The field on which to sort the users whose IDs are returned, by default they are sorted by id

Returns:: An array of user IDs. See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

const ms_errs * getErrorHandler ( ) const [inherited]

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns:: Constant pointer to the error handler

See also:: isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:: common_error.cpp, and http_helper_getstring.cpp.

ms_group getGroup ( const std::string groupName ) const

Return a group given the name .

If an invalid group name is passed, then for the returned object, ms_group::getID() will return -1.

Parameters:

groupName Needs to be a valid group name.

Returns:: an ms_group object.

ms_group getGroupFromID ( const int groupID ) const

Return a group given the ID.

If an invalid group ID is passed, then for the returned object, ms_group::getUserID() will return -1.

Parameters:

groupID Needs to be a valid group ID.

Returns:: an ms_group object.

std::vector< std::string > getIntegraUsers ( ) const

Returns a list of Integra users.

Deprecated:: Mascot Integra is not supported in Mascot Parser 2.5 and later.

Will return an empty list if there is no local Mascot Integra system or the definitions in the option file are not correct. These users have not neccessarily been added to the list of Mascot users.

Returns:: An array of Integra user names. See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

int getLastError ( ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also:: isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Returns:: the error number of the last error, or 0 if there have been no errors.

Reimplemented in ms_mascotresfile.

std::string getLastErrorString ( ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns:: Most recent error, warning, information or debug message

See Error Handling.

See also:: isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Reimplemented in ms_mascotresfile.

Examples:: common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.

ms_security_options getMascotSecurityOptions ( ) const

Return the security options.

If an ms_security object is available, it is faster to call this than creating a new matrix_science::ms_security_options object because there will be no need to load the options file from disk.

Note that this function returns a copy of the security options, so changing the options will have no effect on the ms_security object. To have the changes take effect, a new ms_security object will have to be created.

Returns:: The security options. If the configuration file is not present, defaults will be used.

ms_security_tasks getPermittedTasksForUser ( const std::string name ) const

Return a list of the tasks permitted for the user.

If an invalid user name is passed, then for the returned object, ms_security_tasks::getNumberOfTasks() will return 0.

Parameters:

name	Needs to be a valid user name.

Returns:: A ms_security_tasks object.

ms_security_tasks getTasks ( ) const

Return the complete list of possible tasks available.

The administration module will use this function to display a list of possible tasks to the end user.

Returns:: The complete list of tasks.

ms_user getUser ( const std::string userName ) const

Return a user given the name.

If an invalid user name is passed, then for the returned object, ms_user::getID() will return -1.

Parameters:

userName Needs to be a valid user name.

Returns:: an ms_user object.

ms_user getUserFromID ( const int userID ) const

Return a user given the ID.

If an invalid user ID is passed, then for the returned object, ms_user::getUserID() will return -1.

Parameters:

userID Needs to be a valid user ID.

Returns:: an ms_user object.

bool isTaskExists ( const int taskID ) const

Return true if a security task with the given ID exists.

Parameters:

taskID Task ID to check.

Returns:: true if a task with this ID exists; false otherwise.

bool isUserExists ( const int userID ) const

Return true if a user with this ID exists.

Parameters:

userID User ID to check.

Returns:: true if a user with this ID exists; false otherwise.

bool isValid ( ) const [inherited]

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns:: True if no fatal error occured

See also:: getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:: common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

std::vector< int > sortUsers	(	std::vector< ms_user * > &	vecUsers,
		const USERID_SORTBY	sortby
	)		const

Sort a list of users and return a list of user IDs.

Sorts a list of users by the given field

Parameters:

vecUsers	A vector of users to sort
sortby	The field on which to sort the users whose IDs are returned

Returns:: An array of user IDs sorted by id, login name or full name

bool updateAllSessionFiles ( bool deleteOnly = false )

Update all the session files after making a change to parameters.

This function is called by addNewUser(), deleteUser(), updateUser(), addNewGroup(), deleteGroup() and updateGroup().

Parameters:

deleteOnly is set to true when this function is called from ms-monitor.exe. This prevents session files from being created with the incorrect file permissions.

Returns:: always returns true

bool updateGroup	(	const std::string	sessionID,
		const ms_group &	group
	)

Call this after updating any details for a group.

Groups can be changed by adding/deleting users, changing the name or adding/deleting tasks. To make any of these changes, call getGroup() or getGroupFromID() to get the group and then make changes using the ms_group member functions. Finally, call this function to make the changes permanent. Do not change the groupID, or this function will fail.

Possible errors are:

Parameters:

sessionID	This is the session id for the administrator who is updating the group. A valid session ID with administrator rights is required, and all updates of users and groups are logged using the details in the session ID.
group	The group returned from getGroup() or getGroupFromID().

Returns:: True if the group already exists and has been successfully updated.

bool updatePassword	(	const std::string	sessionID,
		const std::string	userName,
		const std::string	oldPassword,
		const std::string	newPassword
	)

Update the password for an existing user.

If the old password is empty, or is supplied, then anyone can call this function. If the sessionID is for a valid session with Administrator privileges, then the old password is not required.

Possible errors are:

Parameters:

sessionID	Is the session ID for a session with Administrator permissions or a session for the named user.
userName	Needs to be an existing user name.
oldPassword	The old password must be correct.
newPassword	The password will be updated with the new value.

Returns:: Will return true if the password has been updated successfully.

bool updateUser	(	const std::string	sessionID,
		const ms_user	user
	)

Update an existing user int the system.

Most properties of a user account can be changed -- for example the login name, or the full name or email address. The ID cannot be changed. The password must be changed using updatePassword(). To change which groups a user belongs to, see updateGroup().

To call this function, the session must either have ms_security_tasks::SECTASK_ADMINPAGES or ms_security_tasks::SECTASK_MODIFYOWNPROFILE rights. In the latter case, the user to be updated must be the same as the session user, and the only things that can be changed are the full name and the email address.

Possible errors are:

Parameters:

sessionID	Is the session ID for a session with Administrator permissions.
user	Needs to be an existing user. All details will be reset with the passed information, including the password.

Returns:: Will return false and set ms_errs::ERR_MSP_SECURITY_USERNAME_NOT_FOUND if the named user cannot be found.

The documentation for this class was generated from the following files:

ms_security.hpp
ms_security.cpp

ms_security Class Reference [Mascot security and authentication module]

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

ms_security Class Reference
[Mascot security and authentication module]