org.owasp.esapi.interfaces
Interface IUser

All Known Implementing Classes:

User

public interface IUser

The IUser interface represents an application user or user account. There is quite a lot of information that an application must store for each user in order to enforce security properly. There are also many rules that govern authentication and identity management.

A user account can be in one of several states. When first created, a User should be disabled, not expired, and unlocked. To start using the account, an administrator should enable the account. The account can be locked for a number of reasons, most commonly because they have failed login for too many times. Finally, the account can expire after the expiration date has been reached. The User must be enabled, not expired, and unlocked in order to pass authentication.

Since:

June 1, 2007

Author:

Jeff Williams at Aspect Security

Field Summary

static IUser

ANONYMOUS

Method Summary

void	addRole(java.lang.String role) Adds a role to an account.
void	addRoles(java.util.Set newRoles) Adds the roles.
void	changePassword(java.lang.String oldPassword, java.lang.String newPassword1, java.lang.String newPassword2) Sets the user's password, performing a verification of the user's old password, the equality of the two new passwords, and the strength of the new password.
void	disable() Disable account.
void	enable() Enable account.
java.lang.String	getAccountName() Gets the account name.
java.lang.String	getCSRFToken() Gets the CSRF token.
int	getFailedLoginCount() Returns the number of failed login attempts since the last successful login for an account.
java.util.Date	getLastFailedLoginTime() Returns the date of the last failed login time for a user.
java.lang.String	getLastHostAddress() Returns the last host address used by the user.
java.util.Date	getLastLoginTime() Returns the date of the last successful login time for a user.
java.util.Date	getLastPasswordChangeTime() Gets the last password change time.
java.util.Set	getRoles() Gets the roles assigned to a particular account.
java.lang.String	getScreenName() Gets the screen name.
void	incrementFailedLoginCount() Increment failed login count.
boolean	isAnonymous() Checks if is anonymous.
boolean	isEnabled() Checks if an account is currently enabled.
boolean	isExpired() Checks if an account is expired.
boolean	isInRole(java.lang.String role) Checks if an account has been assigned a particular role.
boolean	isLocked() Checks if an account is unlocked.
boolean	isLoggedIn() Tests to see if the user is currently logged in.
boolean	isSessionAbsoluteTimeout() Tests to see if the user's session has exceeded the absolute time out.
boolean	isSessionTimeout() Tests to see if the user's session has timed out from inactivity.
void	lock() Lock the user's account.
void	loginWithPassword(java.lang.String password) Login with password.
void	logout() Logout this user.
void	removeRole(java.lang.String role) Removes a role from an account.
java.lang.String	resetCSRFToken() Returns a token to be used as a prevention against CSRF attacks.
java.lang.String	resetRememberToken() Returns a token to be used as a "remember me" cookie.
void	setAccountName(java.lang.String accountName) Sets the account name.
void	setRoles(java.util.Set roles) Sets the roles.
void	setScreenName(java.lang.String screenName) Sets the screen name.
void	unlock() Unlock account.
boolean	verifyPassword(java.lang.String password) Verify that the supplied password matches the password for this user.

Field Detail

ANONYMOUS

public static final IUser ANONYMOUS

Method Detail

addRole

public void addRole(java.lang.String role)
             throws AuthenticationException

Adds a role to an account.

Parameters:

role - the role

Throws:

AuthenticationException - the authentication exception

addRoles

public void addRoles(java.util.Set newRoles)
              throws AuthenticationException

Adds the roles.

Parameters:

newRoles - the new roles

Throws:

AuthenticationException - the authentication exception

changePassword

public void changePassword(java.lang.String oldPassword,
                           java.lang.String newPassword1,
                           java.lang.String newPassword2)
                    throws AuthenticationException,
                           EncryptionException

Sets the user's password, performing a verification of the user's old password, the equality of the two new passwords, and the strength of the new password.

Parameters:

oldPassword - the old password

newPassword1 - the new password1

newPassword2 - the new password2

Throws:

AuthenticationException - the authentication exception

EncryptionException

disable

public void disable()

Disable account.

Throws:

AuthenticationException - the authentication exception

enable

public void enable()

Enable account.

Throws:

AuthenticationException - the authentication exception

getAccountName

public java.lang.String getAccountName()

Gets the account name.

Returns:

the account name

getCSRFToken

public java.lang.String getCSRFToken()

Gets the CSRF token.

Returns:

the CSRF token

getFailedLoginCount

public int getFailedLoginCount()

Returns the number of failed login attempts since the last successful login for an account. This method is intended to be used as a part of the account lockout feature, to help protect against brute force attacks. However, the implementor should be aware that lockouts can be used to prevent access to an application by a legitimate user, and should consider the risk of denial of service.

Returns:

the number of failed login attempts since the last successful login

getLastHostAddress

public java.lang.String getLastHostAddress()

Returns the last host address used by the user. This will be used in any log messages generated by the processing of this request.

Returns:

getLastFailedLoginTime

public java.util.Date getLastFailedLoginTime()
                                      throws AuthenticationException

Returns the date of the last failed login time for a user. This date should be used in a message to users after a successful login, to notify them of potential attack activity on their account.

Returns:

date of the last failed login

Throws:

AuthenticationException - the authentication exception

getLastLoginTime

public java.util.Date getLastLoginTime()

Returns the date of the last successful login time for a user. This date should be used in a message to users after a successful login, to notify them of potential attack activity on their account.

Returns:

date of the last successful login

getLastPasswordChangeTime

public java.util.Date getLastPasswordChangeTime()

Gets the last password change time.

Returns:

the last password change time

getRoles

public java.util.Set getRoles()

Gets the roles assigned to a particular account.

Returns:

an immutable set of roles

getScreenName

public java.lang.String getScreenName()

Gets the screen name.

Returns:

the screen name

incrementFailedLoginCount

public void incrementFailedLoginCount()

Increment failed login count.

isAnonymous

public boolean isAnonymous()

Checks if is anonymous.

Returns:

true, if is anonymous

isEnabled

public boolean isEnabled()

Checks if an account is currently enabled.

Returns:

true, if is enabled account

isExpired

public boolean isExpired()

Checks if an account is expired.

Returns:

true, account is expired

isInRole

public boolean isInRole(java.lang.String role)

Checks if an account has been assigned a particular role.

Parameters:

role - the role

Returns:

true, if is user in role

isLocked

public boolean isLocked()

Checks if an account is unlocked.

Returns:

true, account is unlocked

isLoggedIn

public boolean isLoggedIn()

Tests to see if the user is currently logged in.

Returns:

true if the user is logged out

isSessionAbsoluteTimeout

public boolean isSessionAbsoluteTimeout()

Tests to see if the user's session has exceeded the absolute time out.

Returns:

whether user's session has exceeded the absolute time out

isSessionTimeout

public boolean isSessionTimeout()

Tests to see if the user's session has timed out from inactivity.

Returns:

whether user's session has timed out from inactivity

lock

public void lock()

Lock the user's account.

loginWithPassword

public void loginWithPassword(java.lang.String password)
                       throws AuthenticationException

Login with password.

Parameters:

password - the password

Throws:

AuthenticationException - the authentication exception

logout

public void logout()

Logout this user.

removeRole

public void removeRole(java.lang.String role)
                throws AuthenticationException

Removes a role from an account.

Parameters:

role - the role

Throws:

AuthenticationException - the authentication exception

resetCSRFToken

public java.lang.String resetCSRFToken()
                                throws AuthenticationException

Returns a token to be used as a prevention against CSRF attacks. This token should be added to all links and forms. The application should verify that all requests contain the token, or they may have been generated by a CSRF attack. It is generally best to perform the check in a centralized location, either a filter or controller. See the verifyCSRFToken method.

Returns:

the string

Throws:

AuthenticationException - the authentication exception

resetRememberToken

public java.lang.String resetRememberToken()
                                    throws AuthenticationException

Returns a token to be used as a "remember me" cookie. The cookie is not seen by the user and can be fairly long, at least 20 digits is suggested to prevent brute force attacks. See loginWithRememberToken.

Returns:

the string

Throws:

AuthenticationException - the authentication exception

setAccountName

public void setAccountName(java.lang.String accountName)

Sets the account name.

Parameters:

accountName - the new account name

setRoles

public void setRoles(java.util.Set roles)
              throws AuthenticationException

Sets the roles.

Parameters:

roles - the new roles

Throws:

AuthenticationException

setScreenName

public void setScreenName(java.lang.String screenName)

Sets the screen name.

Parameters:

screenName - the new screen name

unlock

public void unlock()

Unlock account.

verifyPassword

public boolean verifyPassword(java.lang.String password)
                       throws EncryptionException

Verify that the supplied password matches the password for this user. This method is typically used for "reauthentication" for the most sensitive functions, such as transactions, changing email address, and changing other account information.

Parameters:

password -

Returns:

Throws:

EncryptionException