org.owasp.esapi.reference

Class FileBasedAuthenticator

java.lang.Object

org.owasp.esapi.reference.AbstractAuthenticator

org.owasp.esapi.reference.FileBasedAuthenticator

All Implemented Interfaces:

Authenticator

public class FileBasedAuthenticator
extends AbstractAuthenticator

Reference implementation of the Authenticator interface. This reference implementation is backed by a simple text file that contains serialized information about users. Many organizations will want to create their own implementation of the methods provided in the Authenticator interface backed by their own user repository. This reference implementation captures information about users in a simple text file format that contains user information separated by the pipe "|" character. Here's an example of a single line from the users.txt file:

 

 account id | account name | hashed password | roles | lockout | status | old password hashes | last
 hostname | last change | last login | last failed | expiration | failed
 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 1203123710837 | mitch | 44k/NAzQUlrCq9musTGGkcMNmdzEGJ8w8qZTLzpxLuQ= | admin,user | unlocked | enabled |
 u10dW4vTo3ZkoM5xP+blayWCz7KdPKyKUojOn9GJobg= | 192.168.1.255 | 1187201000926 | 1187200991568 | 1187200605330 |
 2187200605330 | 1
 

 

Since:

June 1, 2007

See Also:

Authenticator

Field Summary

Fields

Modifier and Type	Field and Description
private long	checkInterval How frequently to check the user db for external modifications
private long	lastChecked The last time we checked if the user db had been modified externally
private long	lastModified The last modified time we saw on the user db.
private Logger	logger The logger.
private static int	MAX_ACCOUNT_NAME_LENGTH
private java.util.Map<User,java.util.List<java.lang.String>>	passwordMap
private static Authenticator	singletonInstance
private java.io.File	userDB The file that contains the user db
private java.util.Map<java.lang.Long,User>	userMap The user map.

Fields inherited from class org.owasp.esapi.reference.AbstractAuthenticator

USER

Constructor Summary

Constructors

Modifier	Constructor and Description
private	FileBasedAuthenticator()

Method Summary

Modifier and Type	Method and Description
void	changePassword(User user, java.lang.String currentPassword, java.lang.String newPassword, java.lang.String newPassword2) Changes the password for the specified user.
private DefaultUser	createUser(java.lang.String line) Create a new user with all attributes from a String.
User	createUser(java.lang.String accountName, java.lang.String password1, java.lang.String password2) Creates a new User with the information provided.
private java.lang.String	dump(java.util.Collection<java.lang.String> c) Dump a collection as a comma-separated list.
java.lang.String	generateStrongPassword() Generate a strong password.
private java.lang.String	generateStrongPassword(java.lang.String oldPassword) Generate a strong password that is not similar to the specified old password.
java.lang.String	generateStrongPassword(User user, java.lang.String oldPassword) Generate strong password that takes into account the user's information and old password.
(package private) java.util.List<java.lang.String>	getAllHashedPasswords(User user, boolean create) Returns all of the specified User's hashed passwords.
(package private) java.lang.String	getHashedPassword(User user) Return the specified User's current hashed password.
static Authenticator	getInstance()
(package private) java.util.List<java.lang.String>	getOldPasswordHashes(User user) Get a List of the specified User's old password hashes.
User	getUser(long accountId) Returns the User matching the provided accountId.
User	getUser(java.lang.String accountName) Returns the User matching the provided accountName.
java.util.Set	getUserNames() Gets a collection containing all the existing user names.
java.lang.String	hashPassword(java.lang.String password, java.lang.String accountName) Returns a string representation of the hashed password, using the accountName as the salt.
protected void	loadUsersIfNecessary() Load users if they haven't been loaded in a while.
protected void	loadUsersImmediately()
static void	main(java.lang.String[] args) Fail safe main program to add or update an account in an emergency.
void	removeUser(java.lang.String accountName) Removes the account of the specified accountName.
private java.lang.String	save(DefaultUser user) Save.
void	saveUsers() Saves the user database to the file system.
protected void	saveUsers(java.io.PrintWriter writer) Save users.
private void	setHashedPassword(User user, java.lang.String hash) Add a hash to a User's hashed password list.
(package private) void	setOldPasswordHashes(User user, java.util.List<java.lang.String> oldHashes) Set the specified User's old password hashes.
void	verifyAccountNameStrength(java.lang.String newAccountName) Ensures that the account name passes site-specific complexity requirements, like minimum length.
boolean	verifyPassword(User user, java.lang.String password) Verify that the supplied password matches the password for this user.
void	verifyPasswordStrength(java.lang.String oldPassword, java.lang.String newPassword, User user) Ensures that the password meets site-specific complexity requirements, like length or number of character sets.

Methods inherited from class org.owasp.esapi.reference.AbstractAuthenticator

clearCurrent, exists, getCurrentUser, getUserFromRememberToken, getUserFromSession, login, login, logout, setCurrentUser

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

singletonInstance

private static volatile Authenticator singletonInstance

logger

private final Logger logger

The logger.

userDB

private java.io.File userDB

The file that contains the user db

checkInterval

private long checkInterval

How frequently to check the user db for external modifications

lastModified

private long lastModified

The last modified time we saw on the user db.

lastChecked

private long lastChecked

The last time we checked if the user db had been modified externally

MAX_ACCOUNT_NAME_LENGTH

private static final int MAX_ACCOUNT_NAME_LENGTH

See Also:

Constant Field Values

userMap

private java.util.Map<java.lang.Long,User> userMap

The user map.

passwordMap

private java.util.Map<User,java.util.List<java.lang.String>> passwordMap

Constructor Detail

FileBasedAuthenticator

private FileBasedAuthenticator()

Method Detail

getInstance

public static Authenticator getInstance()

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Fail safe main program to add or update an account in an emergency.

Warning: this method does not perform the level of validation and checks generally required in ESAPI, and can therefore be used to create a username and password that do not comply with the username and password strength requirements.

Example: Use this to add the alice account with the admin role to the users file:

 

 java -Dorg.owasp.esapi.resources="/path/resources" -classpath esapi.jar org.owasp.esapi.Authenticator alice password admin
 

 

Parameters:

args - the arguments (username, password, role)

Throws:

java.lang.Exception - the exception

setHashedPassword

private void setHashedPassword(User user,
                               java.lang.String hash)

Add a hash to a User's hashed password list. This method is used to store a user's old password hashes to be sure that any new passwords are not too similar to old passwords.

Parameters:

user - the user to associate with the new hash

hash - the hash to store in the user's password hash list

getHashedPassword

java.lang.String getHashedPassword(User user)

Return the specified User's current hashed password.

Parameters:

user - this User's current hashed password will be returned

Returns:

the specified User's current hashed password

setOldPasswordHashes

void setOldPasswordHashes(User user,
                          java.util.List<java.lang.String> oldHashes)

Set the specified User's old password hashes. This will not set the User's current password hash.

Parameters:

user - the User whose old password hashes will be set

oldHashes - a list of the User's old password hashes *

getAllHashedPasswords

java.util.List<java.lang.String> getAllHashedPasswords(User user,
                                                       boolean create)

Returns all of the specified User's hashed passwords. If the User's list of passwords is null, and create is set to true, an empty password list will be associated with the specified User and then returned. If the User's password map is null and create is set to false, an exception will be thrown.

Parameters:

user - the User whose old hashes should be returned

create - true - if no password list is associated with this user, create one false - if no password list is associated with this user, do not create one

Returns:

a List containing all of the specified User's password hashes

getOldPasswordHashes

java.util.List<java.lang.String> getOldPasswordHashes(User user)

Get a List of the specified User's old password hashes. This will not return the User's current password hash.

Parameters:

user - he user whose old password hashes should be returned

Returns:

the specified User's old password hashes

createUser

public User createUser(java.lang.String accountName,
                       java.lang.String password1,
                       java.lang.String password2)
                throws AuthenticationException

Creates a new User with the information provided. Implementations should check accountName and password for proper format and strength against brute force attacks ( verifyAccountNameStrength(String), verifyPasswordStrength(String, String) ). Two copies of the new password are required to encourage user interface designers to include a "re-type password" field in their forms. Implementations should verify that both are the same.

Parameters:

accountName - the account name of the new user

password1 - the password of the new user

password2 - the password of the new user. This field is to encourage user interface designers to include two password fields in their forms.

Returns:

the User that has been created

Throws:

AuthenticationException - if user creation fails due to any of the qualifications listed in this method's description

generateStrongPassword

public java.lang.String generateStrongPassword()

Generate a strong password. Implementations should use a large character set that does not include confusing characters, such as i I 1 l 0 o and O. There are many algorithms to generate strong memorable passwords that have been studied in the past.

Returns:

a password with strong password strength

generateStrongPassword

private java.lang.String generateStrongPassword(java.lang.String oldPassword)

Generate a strong password that is not similar to the specified old password.

Parameters:

oldPassword - the password to be compared to the new password for similarity

Returns:

a new strong password that is dissimilar to the specified old password

changePassword

public void changePassword(User user,
                           java.lang.String currentPassword,
                           java.lang.String newPassword,
                           java.lang.String newPassword2)
                    throws AuthenticationException

Changes the password for the specified user. This requires the current password, as well as the password to replace it with. The new password should be checked against old hashes to be sure the new password does not closely resemble or equal any recent passwords for that User. Password strength should also be verified. This new password must be repeated to ensure that the user has typed it in correctly.

Parameters:

user - the user to change the password for

currentPassword - the current password for the specified user

newPassword - the new password to use

newPassword2 - a verification copy of the new password

Throws:

AuthenticationException - if any errors occur

verifyPassword

public boolean verifyPassword(User user,
                              java.lang.String password)

Verify that the supplied password matches the password for this user. Password should be stored as a hash. It is recommended you use the hashPassword(password, accountName) method in this class. This method is typically used for "reauthentication" for the most sensitive functions, such as transactions, changing email address, and changing other account information.

Parameters:

user - the user who requires verification

password - the hashed user-supplied password

Returns:

true, if the password is correct for the specified user

generateStrongPassword

public java.lang.String generateStrongPassword(User user,
                                               java.lang.String oldPassword)

Generate strong password that takes into account the user's information and old password. Implementations should verify that the new password does not include information such as the username, fragments of the old password, and other information that could be used to weaken the strength of the password.

Parameters:

user - the user whose information to use when generating password

oldPassword - the old password to use when verifying strength of new password. The new password may be checked for fragments of oldPassword.

Returns:

a password with strong password strength

getUser

public User getUser(long accountId)

Returns the User matching the provided accountId. If the accoundId is not found, an Anonymous User or null may be returned.

Parameters:

accountId - the account id

Returns:

the matching User object, or the Anonymous User if no match exists

getUser

public User getUser(java.lang.String accountName)

Returns the User matching the provided accountName. If the accoundId is not found, an Anonymous User or null may be returned.

Parameters:

accountName - the account name

Returns:

the matching User object, or the Anonymous User if no match exists

getUserNames

public java.util.Set getUserNames()

Gets a collection containing all the existing user names.

Returns:

a set of all user names

hashPassword

public java.lang.String hashPassword(java.lang.String password,
                                     java.lang.String accountName)
                              throws EncryptionException

Returns a string representation of the hashed password, using the accountName as the salt. The salt helps to prevent against "rainbow" table attacks where the attacker pre-calculates hashes for known strings. This method specifies the use of the user's account name as the "salt" value. The Encryptor.hash method can be used if a different salt is required.

Parameters:

password - the password to hash

accountName - the account name to use as the salt

Returns:

the hashed password

Throws:

EncryptionException

loadUsersIfNecessary

protected void loadUsersIfNecessary()

Load users if they haven't been loaded in a while.

loadUsersImmediately

protected void loadUsersImmediately()

createUser

private DefaultUser createUser(java.lang.String line)
                        throws AuthenticationException

Create a new user with all attributes from a String. The format is: accountId | accountName | password | roles (comma separated) | unlocked | enabled | old password hashes (comma separated) | last host address | last password change time | last long time | last failed login time | expiration time | failed login count This method verifies the account name and password strength, creates a new CSRF token, then returns the newly created user.

Parameters:

line - parameters to set as attributes for the new User.

Returns:

the newly created User

Throws:

AuthenticationException

removeUser

public void removeUser(java.lang.String accountName)
                throws AuthenticationException

Removes the account of the specified accountName.

Parameters:

accountName - the account name to remove

Throws:

AuthenticationException - the authentication exception if user does not exist

saveUsers

public void saveUsers()
               throws AuthenticationException

Saves the user database to the file system. In this implementation you must call save to commit any changes to the user file. Otherwise changes will be lost when the program ends.

Throws:

AuthenticationException - if the user file could not be written

saveUsers

protected void saveUsers(java.io.PrintWriter writer)
                  throws AuthenticationCredentialsException

Save users.

Parameters:

writer - the print writer to use for saving

Throws:

AuthenticationCredentialsException

save

private java.lang.String save(DefaultUser user)

Save.

Parameters:

user - the User to save

Returns:

a line containing properly formatted information to save regarding the user

dump

private java.lang.String dump(java.util.Collection<java.lang.String> c)

Dump a collection as a comma-separated list.

Parameters:

c - the collection to convert to a comma separated list

Returns:

a comma separated list containing the values in c

verifyAccountNameStrength

public void verifyAccountNameStrength(java.lang.String newAccountName)
                               throws AuthenticationException

Ensures that the account name passes site-specific complexity requirements, like minimum length.

This implementation simply verifies that account names are at least 5 characters long. This helps to defeat a brute force attack, however the real strength comes from the name length and complexity.

Parameters:

newAccountName -

Throws:

AuthenticationException - if account name does not meet complexity requirements

verifyPasswordStrength

public void verifyPasswordStrength(java.lang.String oldPassword,
                                   java.lang.String newPassword,
                                   User user)
                            throws AuthenticationException

Ensures that the password meets site-specific complexity requirements, like length or number of character sets. This method takes the old password so that the algorithm can analyze the new password to see if it is too similar to the old password. Note that this has to be invoked when the user has entered the old password, as the list of old credentials stored by ESAPI is all hashed. Additionally, the user object is taken in order to verify the password and account name differ.

This implementation checks: - for any 3 character substrings of the old password - for use of a length * character sets > 16 (where character sets are upper, lower, digit, and special jtm - 11/16/2010 - added check to verify pw != username (fix for http://code.google.com/p/owasp-esapi-java/issues/detail?id=108)

Parameters:

oldPassword - the old password

newPassword - the new password

user - the user

Throws:

AuthenticationException - if newPassword is too similar to oldPassword or if newPassword does not meet complexity requirements