Matrix Science header
Public Types | Public Member Functions

ms_user Class Reference
[Mascot security and authentication module]

This class will normally only be used by Mascot Security Administration applications. More...

#include <ms_security_user.hpp>

List of all members.

Public Types

enum  systemids {
  USERID_SECURITY_DISABLED = 0x0000,
  USERID_GUEST = 0x0001,
  USERID_ADMINISTRATOR = 0x0002,
  USERID_CMDLINE = 0x0003,
  USERID_DAEMON = 0x0004,
  USERID_PUBLIC_SEARCHES = 0x0005,
  USERID_INTEGRA_SYSTEM = 0x0006,
  USERID_LAST = 0x0007
}
 

Definitions for predefined users.

More...
enum  usertype {
  USER_SECURITY_DISABLED = 0x0000,
  USER_NORMAL = 0x0001,
  USER_INTEGRA = 0x0002,
  USER_COMPUTER_NAME = 0x0003,
  USER_IP_ADDRESS = 0x0004,
  USER_AGENT_STRING = 0x0005,
  USER_WEBAUTH = 0x0006
}
 

Definitions for types of user.

More...

Public Member Functions

 ms_user (const int userID, const std::string userName, const std::string password, const long passwordExpiry, const std::string fullName, const std::string emailAddress, const usertype userType, const bool enabled)
 Create a new user.
 ms_user ()
 Create a new 'empty' user with no name, password, ID.
bool clearParam (const std::string name)
 Remove an additional user parameter associated with the user.
std::string getEmailAddress () const
 Returns the email address of the user.
std::string getEncryptedPassword () const
 Returns the encrypted password.
std::string getFullName () const
 Return the full user name.
int getID () const
 Return the unique user ID.
std::string getName () const
 Return the user login name.
time_t getPasswordExpiry () const
 Returns the time that the password will expire.
bool getStringParam (const std::string name, std::string &param) const
 Return a custom parameter for the user.
std::string getStringParam (const std::string name) const
 Return a custom parameter for the user.
usertype getUserType () const
 Return the 'type' of user.
bool hasPasswordExpired () const
 Returns true if the password has expired.
bool isAccountEnabled () const
 Return true if the account is enabled.
bool saveStringParam (const std::string name, const std::string param)
 Save an additional 'string' parameter for the user.
void setAccountEnabled (bool newVal)
 Pass true to enable the account.
void setEmailAddress (std::string newVal)
 Sets the email address of the user.
void setEncryptedPassword (std::string newVal)
 Update the encrypted password - details are saved immediately.
void setFullName (std::string newVal)
 Update the full user name -- details are saved immediately.
void setID (int newVal)
 Set the unique user ID.
void setName (std::string newVal)
 Set the user login name.
void setPassword (std::string barePassword)
 Encrypt and save the passed password.
void setPasswordExpiry (time_t newVal)
 Set the password expiry time.
void setUserType (usertype newVal)
 Update the user type -- details are saved immediately.
bool validatePassword (const std::string pwd, int &errorFlag) const
 Checks to see if the password is correct for the user.

Detailed Description

This class will normally only be used by Mascot Security Administration applications.

Call ms_security::addNewUser() to create a new user or ms_security::getUser() or ms_security::getUserFromID() to get an existing user, and then use the ms_user member functions to query or modify the ms_user object.

To make the changes permanent, use ms_security::updateUser().


Member Enumeration Documentation

enum systemids

Definitions for predefined users.

See Using enumerated values in Perl, Java, Python and C#.

Enumerator:
USERID_SECURITY_DISABLED 

Only valid if security is disabled.

USERID_GUEST 

The built in guest user. Note that this accound is disabled by default.

USERID_ADMINISTRATOR 

The built in administrator account. Cannot be deleted or disabled.

USERID_CMDLINE 

Applications run from the command line rather than as a cgi application use this by default.

USERID_DAEMON 

Mascot Daemon will use this user to run searches.

USERID_PUBLIC_SEARCHES 

Example files use this user id. matrix_science::ms_session::canResultsFileBeViewed always returns true for this ID.

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

Placeholder.

enum usertype

Definitions for types of user.

See Using enumerated values in Perl, Java, Python and C#.

Enumerator:
USER_SECURITY_DISABLED 

Not a real user, but the USERID if security is disabled.

USER_NORMAL 

A 'normal' Mascot user, that doesn't fit into any of the other categories below.

USER_INTEGRA 
Deprecated:
Mascot Integra is not supported in Mascot Parser 2.5 and later. Login etc. is done through Mascot Insight.
USER_COMPUTER_NAME 

This type of user is defined by a computer name. Should only be used for 3rd party applications.

USER_IP_ADDRESS 

This type of user is defined by an IP address. Should only be used for 3rd party applications.

USER_AGENT_STRING 

This type of user is defined by a client agent string. Should only be used for 3rd party applications as a last resort.

USER_WEBAUTH 

The configuration is to use web server authentication, so this user has no password.


Member Function Documentation

bool clearParam ( const std::string  name )

Remove an additional user parameter associated with the user.

Additional custom data for a user are saved in a <mss:custom_parameters> section in the user.xml file.

Use this function when you no longer want a value associated with a key name for a user.

To make the changes permanent, use ms_security::updateUser().

See also Using custom parameters

Parameters:
nameName of the key value. Do not use an name with a leading underscore as these are reserved for system values.
Returns:
boolean value to indicate if the value was successfully removed.
std::string getEmailAddress (  ) const

Returns the email address of the user.

This is not a required field, which means the return value may be the empty string.

Returns:
email address
std::string getEncryptedPassword (  ) const

Returns the encrypted password.

Unlikely to be useful for most applications. It is not possible to retrieve the unencrypted password from the system, and the value returned from this function will not be the same as the value passed to ms_user::setPassword().

Returns:
The encrypted password.
std::string getFullName (  ) const

Return the full user name.

Useful for displaying the full name in reports etc.

Returns:
The current full (long) user name.
int getID (  ) const

Return the unique user ID.

The unique user ID for the user. This should never be changed, since all searches are saved with the USERID equal to this value. Special user IDs are the same as the values in ms_user::systemids.

Returns:
The current user ID.
time_t getPasswordExpiry (  ) const

Returns the time that the password will expire.

The time in seconds since January 1st 1970. A value of '0'is used to indicate that the password should never expire.

Returns:
The current password expiry date.
bool getStringParam ( const std::string  name,
std::string &  param 
) const

Return a custom parameter for the user.

Additional custom data for a user are saved in a <mss:custom_parameters> section in the user.xml file.

Note:
This function should not be used from programming languages other than C++. Use getStringParam(const std::string) const instead.
See also:
saveStringParam()

See also Using custom parameters

Parameters:
nameName of the key value. Do not use an name with a leading underscore as these are reserved for system values.
paramIs the value of the parameter associated with the key name.
Returns:
boolean value to indicate if the value was successfully retrieved.
std::string getStringParam ( const std::string  name ) const

Return a custom parameter for the user.

Additional custom data for a user are saved in a <mss:custom_parameters> section in the user.xml file.

If an empty string is returned, it is not possible to determine if this is because there is no key value or if an empty string was set for the key.

See also:
saveStringParam()

See also Using custom parameters

Parameters:
nameName of the key value. Do not use an name with a leading underscore as these are reserved for system values.
Returns:
Is the value of the parameter associated with the key name or an empty string if there is no key.
ms_user::usertype getUserType (  ) const

Return the 'type' of user.

See also:
ms_user::setUserType().
Returns:
user type
bool hasPasswordExpired (  ) const

Returns true if the password has expired.

If the password expiry value is zero, the password will never expire. An expiry value of 1 may be used to indicate that the user should change their password when they first log in.

Returns:
True if the password has expired.
bool saveStringParam ( const std::string  name,
const std::string  param 
)

Save an additional 'string' parameter for the user.

Additional custom data for a user are saved in a <mss:custom_parameters> section in the user.xml file.

The value can be retrieved using getStringParam().

To make the changes permanent, use ms_security::updateUser().

See also Using custom parameters

Parameters:
nameName of the key value. Do not use an name with a leading underscore as these are reserved for system values.
paramThe value to be assigned to the key.
Returns:
true if the value is successfully saved.
void setAccountEnabled ( bool  newVal )

Pass true to enable the account.

To make the changes permanent, use ms_security::updateUser().

Parameters:
newValSet to true to enable the account, and false to disable the account.
void setEmailAddress ( std::string  newVal )

Sets the email address of the user.

To make the changes permanent, use ms_security::updateUser().

Parameters:
newValis the new email address of the user.
void setFullName ( std::string  newVal )

Update the full user name -- details are saved immediately.

Useful for displaying the full name in reports etc.

To make the changes permanent, use ms_security::updateUser().

Parameters:
newValis the new full (long) name for the user.
void setID ( int  newVal )

Set the unique user ID.

The unique user ID for the user. This should never be changed, since all searches are saved with the USERID equal to this value. Special user IDs are the same as the values in ms_user::systemids.

To make the changes permanent, use ms_security::updateUser().

Parameters:
newValis the new user ID.
void setName ( std::string  newVal )

Set the user login name.

The login name for a user. It is safe to change this for an existing user (as long as the user ID is not changed).

To make the changes permanent, use ms_security::updateUser().

Parameters:
newValis the new login name for the user.
void setPasswordExpiry ( time_t  newVal )

Set the password expiry time.

The time in seconds since January 1st 1970. A value of '0' is used to indicate that the password should never expire.

To make the changes permanent, use ms_security::updateUser().

Parameters:
newValIs the new date for the password expiry.
void setUserType ( ms_user::usertype  newVal )

Update the user type -- details are saved immediately.

See ms_user::ms_user for restrictions on setting the user type. To make the changes permanent, use ms_security::updateUser().

See also:
ms_user::setUserType()
Parameters:
newValis the new user type.
bool validatePassword ( const std::string  pwd,
int &  errorFlag 
) const

Checks to see if the password is correct for the user.

Parameters:
pwdis the the unencrypted password to be checked against the encrypted password saved in the user's file.
errorFlagwill contain 0 if the function returns true. If the function returns false, then a value of 1 indicates an incorrect password and a value of 2 indicates an internal problem with the seed value.
Returns:
Will return true if the password is correct, or if there is no saved password.

The documentation for this class was generated from the following files:
Copyright © 2016 Matrix Science Ltd.  All Rights Reserved. Generated on Fri Jun 2 2017 01:44:55