Matrix Science header
Public Member Functions

ms_security_options Class Reference
[Mascot security and authentication module]

Options for the Mascot security system. More...

#include <ms_security_options.hpp>

Inheritance diagram for ms_security_options:
Inheritance graph
[legend]
Collaboration diagram for ms_security_options:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 ms_security_options ()
 Loads the options file into memory.
 ms_security_options (const ms_security_options &src)
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_security_options *right)
void copyFrom (const ms_errors *right)
 Use this member to make a copy of another instance.
time_t getDefaultPasswordExpiryTime () const
 Returns the time in days before a password expires.
const ms_errsgetErrorHandler () const
 Retrive the error object using this function to get access to all errors and error parameters.
std::string getIntegraAppServerURL () const
 Returns the URL to the Integra Application server host.
std::string getIntegraDatabaseName () const
 Returns the name of the Integra database.
std::string getIntegraOracleServerName () const
 Returns the name of the oracle server for Mascot Integra.
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.
std::string getLogFileName ()
 Returns the log file name.
matrix_science::ms_errs::msg_sev getLoggingLevel () const
 Returns the logging level.
unsigned int getMinimumPasswordLength () const
 Returns the minimum password length.
time_t getSessionTimeout () const
 Returns the time in seconds before a user is logged out.
bool getUseSessionCookies () const
 Returns true if session (rather than file) cookies are to be used.
bool getVerifySessionIPAddress () const
 Returns true if a session will be invalid if used from a different IP address from the original session request.
bool isSecurityEnabled () const
 Will return true if the Mascot security system is enabled.
bool isValid () const
 Call this function to determine if there have been any errors.
ms_security_optionsoperator= (const ms_security_options &right)
void setDefaultPasswordExpiryTime (time_t newVal)
 Sets the time in days before a password expires.
void setIntegraAppServerURL (std::string newVal)
 Sets the URL to the Integra Application server host.
void setIntegraDatabaseName (std::string newVal)
 Sets the name of the Integra database.
void setIntegraOracleServerName (std::string newVal)
 Sets the name of the oracle server for Mascot Integra.
void setLogFileName (std::string newVal)
 Sets the log file name.
void setLoggingLevel (ms_errs::msg_sev newVal)
 Sets the logging level.
void setMinimumPasswordLength (unsigned int newVal)
 Sets the minimum password length.
void setSecurityEnabled (bool newVal)
 Enables the Mascot security system.
void setSessionTimeout (time_t newVal)
 Sets the time in seconds before a user is logged out.
void setUseSessionCookies (bool newVal)
 Set whether session or file cookies should be used.
void setVerifySessionIPAddress (bool newVal)
 Set if a session will be invalid if used from a different IP address from the original session request.

Detailed Description

Options for the Mascot security system.

This class will generally only be used by the security administration utility. It is used by the ms_security and ms_session classes.


Constructor & Destructor Documentation

Loads the options file into memory.

If the file cannot be found, the following defaults are set:

Security enabled
false
Session timeout
21,600 seconds (6 hours)
Default password expiry time
365 (days)
Minimum password length
5 characters
Use session cookies
false
Verify IP address for sessions
false
Mascot Integra application server URL
"http://integra:8080/topaz"
Mascot Integra database name
"integra"
Mascot Integra Oracle server name
Integra

It will often be faster to call ms_security::getMascotSecurityOptions() if a ms_security object is already available.

Parameters:
srcis the source to initialise from

Member Function Documentation

void appendErrors ( const ms_errors src ) [inherited]

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

Parameters:
srcThe 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_security_options right )
Parameters:
rightis the source to initialise from
void copyFrom ( const ms_errors right ) [inherited]

Use this member to make a copy of another instance.

Parameters:
rightis the source to initialise from
time_t getDefaultPasswordExpiryTime (  ) const

Returns the time in days before a password expires.

When a new user is created using ms_security::addNewUser(), the password expiry is explicity set using that function. A value of 1 will typically be passed to that function to force the user to choose a new password when they first log in. However, the administration utility could take the current time, and add this default value to set the new expiry time.

This default value is used to set the expiry time for the password when ms_security::updatePassword() is called. If the default expiry time is zero, then the user's password will be set to never expire.

See also:
ms_user::getPasswordExpiry(), setDefaultPasswordExpiryTime()
Returns:
The expiry time in days.
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.
std::string getIntegraAppServerURL (  ) const

Returns the URL to the Integra Application server host.

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

Mascot Integra users should be able to use the same login for the Mascot search engine and Mascot Integra. This is the URL to the Mascot Integra system. Should be blank where there is no local Mascot Integra installation. It will typically be of the form http://integra:8080/topaz.

See also:
setIntegraAppServerURL()
Returns:
The URL for Mascot Integra server.
std::string getIntegraDatabaseName (  ) const

Returns the name of the Integra database.

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

Mascot Integra users should be able to use the same login for the Mascot search engine and Mascot Integra. This is the database name on the Mascot Integra system. Should be blank where there is no local Mascot Integra installation. It will typically be 'integra'.

See also:
setIntegraDatabaseName()
Returns:
The Mascot Integra database name.
std::string getIntegraOracleServerName (  ) const

Returns the name of the oracle server for Mascot Integra.

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

Mascot Integra users should be able to use the same login for the Mascot search engine and Mascot Integra. This is the location of the Oracle server used by Mascot Integra, which may not be on the same system as Mascot Integra. Should be blank where there is no local Mascot Integra installation. It will typically be 'integra'.

See also:
setIntegraOracleServerName().
Returns:
The Mascot Integra Oracle database server name.
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.
std::string getLogFileName (  )

Returns the log file name.

Any changes to security settings are logged in the log file.

Returns:
The log file name.
ms_errs::msg_sev getLoggingLevel (  ) const

Returns the logging level.

Any changes to security settings are logged in the log file. The number of messages depends on the logging level.

Returns:
The logging level.
unsigned int getMinimumPasswordLength (  ) const

Returns the minimum password length.

A value of zero can be used to indicate that passwords are not required. This value is checked when ms_security::addNewUser() or ms_security::updatePassword() are called. If the entered password is less than this length, then the error ms_errs::ERR_MSP_SECURITY_PASSWORD_TOO_SHORT will be generated.

See also:
setMinimumPasswordLength()
Returns:
The minimum password length.
time_t getSessionTimeout (  ) const

Returns the time in seconds before a user is logged out.

Accessing a session using ms_session (normally done viewing any page that uses the session) will start the clock ticking again for that session. Session timeouts are not used for guest sessions, or if the user type is one of

See also:
setSessionTimeout()
Returns:
The session timeout value in seconds which will be in the range 60 to 31,449,600 (one year).
bool getUseSessionCookies (  ) const

Returns true if session (rather than file) cookies are to be used.

A session, or non persistent cookie is not saved on the end users disk, and just lasts for the time that the browser is open. A file or persistent cookie is saved on the end users disk so that it will be available when the browser is opened again.

The name of the cookie that saves the session ID should be MascotSessionID -- see ms_session::ms_session() for details of how the cookie is used.

The only time that a cookie should be set is when the user logs in. If this option to use session cookies is set, then the 'expires' value must not be set. See also setUseSessionCookies().

Returns:
True if session rather than persistent cookies should be used.
bool getVerifySessionIPAddress (  ) const

Returns true if a session will be invalid if used from a different IP address from the original session request.

When a session is created, the IP address of the originator and the value of this flag is saved in the session file. If this flag is set to true, and there is a request to open the session from a different IP address, then that request will be denied with the error ms_errs::ERR_MSP_SECURITY_DIFFERENTIPADDR. Guest users, or any user with the type ms_user::USER_WEBAUTH will never generate that error.

See also:
setVerifySessionIPAddress(), ms_session::getIPAddress()
Returns:
True if IP addresses should be checked.
bool isSecurityEnabled (  ) const

Will return true if the Mascot security system is enabled.

Most applications will not need to call this function, since they will need to create a ms_session object anyway, and can then use the ms_session::isSecurityEnabled() function.

Returns:
True if security is enabled.
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.
ms_security_options & operator= ( const ms_security_options right )
Parameters:
rightis the source to initialise from
Returns:
reference to the current object
void setDefaultPasswordExpiryTime ( time_t  newVal )

Sets the time in days before a password expires.

When a new user is created using ms_security::addNewUser(), the password expiry is explicity set using that function. A value of 1 will typically be passed to that function to force the user to choose a new password when they first log in. However, the administration utility could take the current time, and add this default value to set the new expiry time.

This default value is used to set the expiry time for the password when ms_security::updatePassword is called. If the default expiry time is zero, then the user's password will be set to never expire.

See also:
ms_user::getPasswordExpiry(), getDefaultPasswordExpiryTime()
Parameters:
newValis the new expiry time in days.
void setIntegraAppServerURL ( std::string  newVal )

Sets the URL to the Integra Application server host.

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

Mascot Integra users should be able to use the same login for the Mascot search engine and Mascot Integra. This is the URL to the Mascot Integra system. Should be blank where there is no local Mascot Integra installation. It will typically be of the form http://integra:8080/topaz.

See also:
getIntegraAppServerURL()
Parameters:
newValThe URL for Mascot Integra server.
void setIntegraDatabaseName ( std::string  newVal )

Sets the name of the Integra database.

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

Mascot Integra users should be able to use the same login for the Mascot search engine and Mascot Integra. This is the database name on the Mascot Integra system. Should be blank where there is no local Mascot Integra installation. It will typically be 'integra'.

See also:
setIntegraDatabaseName()
Parameters:
newValThe Mascot Integra database name.
void setIntegraOracleServerName ( std::string  newVal )

Sets the name of the oracle server for Mascot Integra.

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

Mascot Integra users should be able to use the same login for the Mascot search engine and Mascot Integra. This is the location of the Oracle server used by Mascot Integra, which may not be on the same system as Mascot Integra. Should be blank where there is no local Mascot Integra installation. It will typically be 'integra'.

See also:
getIntegraOracleServerName()
Parameters:
newValThe Mascot Integra Oracle database server name.
void setLogFileName ( std::string  newVal )

Sets the log file name.

Any changes to security settings are logged in the log file.

Parameters:
newValThe new log file name.
void setLoggingLevel ( ms_errs::msg_sev  newVal )

Sets the logging level.

Any changes to security settings are logged in the log file. (../logs/security.log). The number of messages depends on the logging level:

  • 1 - Errors
  • 2 - Warnings
  • 3 - Information (Default)
  • 4 - Debug level 1
  • 5 - Debug level 2
  • 6 - Debug level 3
Parameters:
newValThe new logging level.
void setMinimumPasswordLength ( unsigned int  newVal )

Sets the minimum password length.

A value of zero can be used to indicate that passwords are not required. This value is checked when ms_security::addNewUser() or ms_security::updatePassword() are called. If the entered password is less than this length, then the error ms_errs::ERR_MSP_SECURITY_PASSWORD_TOO_SHORT will be generated.

See also:
getMinimumPasswordLength()
Parameters:
newValis the new minimum password length.
void setSecurityEnabled ( bool  newVal )

Enables the Mascot security system.

Used by the security administration utility. See also isSecurityEnabled().

Parameters:
newValShould be set to true to enable security or false to disable it.
void setSessionTimeout ( time_t  newVal )

Sets the time in seconds before a user is logged out.

Viewing any page that uses the session timeout will start the clock ticking again. Session timeouts are not used for guest sessions, or if the user type is one of

See also:
getSessionTimeout()
Parameters:
newValis the new session timeout in seconds. It must be in the range 60 to 31,449,600 (one year).
void setUseSessionCookies ( bool  newVal )

Set whether session or file cookies should be used.

A session, or non persistent cookie is not saved on the end users disk, and just lasts for the time that the browser is open. A file or persistent cookie is saved on the end users disk so that it will be available when the browser is opened again.

The name of the cookie that saves the session ID should be MascotSessionID -- see ms_session::ms_session() for details of how the cookie is used.

The only time that a cookie should be set is when the user logs in. If this option to use session cookies is set, then the 'expires' value must not be set. See also getUseSessionCookies().

Parameters:
newValShould be set to true to specify that session rather than persistent cookies should be used.
void setVerifySessionIPAddress ( bool  newVal )

Set if a session will be invalid if used from a different IP address from the original session request.

When a session is created, the IP address of the originator and the value of this flag is saved in the session file. If this flag is set to true, and there is a request to open the session from a different IP address, then that request will be denied with the error ms_errs::ERR_MSP_SECURITY_DIFFERENTIPADDR. Guest users, or any user with the type ms_user::USER_WEBAUTH will never generate that error.

See also:
setVerifySessionIPAddress(), ms_session::getIPAddress()
Parameters:
newValShould be set to true if IP addresses should be checked.

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

Copyright © 2022 Matrix Science Ltd.  All Rights Reserved. Generated on Thu Mar 31 2022 01:12:38