org.apache.shiro.authc.credential
Interface PasswordService

All Known Subinterfaces:

HashingPasswordService

All Known Implementing Classes:

DefaultPasswordService

public interface PasswordService

A PasswordService supports common use cases when using passwords as a credentials mechanism.

Most importantly, implementations of this interface are expected to employ best-practices to ensure that passwords remain as safe as possible in application environments.

Usage

A PasswordService is used at two different times during an application's lifecycle:

• When creating a user account or resetting their password
• When a user logs in, when passwords must be compared

Account Creation or Password Reset

Whenever you create a new user account or reset that account's password, we must translate the end-user submitted raw/plaintext password value to a string format that is much safer to store. You do that by calling the encryptPassword(Object) method to create the safer value. For example:

 String submittedPlaintextPassword = ...
 String encryptedValue = passwordService.encryptPassword(submittedPlaintextPassword);
 ...
 userAccount.setPassword(encryptedValue);
 userAccount.save(); //create or update to your data store
 

Be sure to save this encrypted password in your data store and never the original/raw submitted password.

Login Password Comparison

Shiro performs the comparison during login automatically. Along with your PasswordService, you just have to configure a PasswordMatcher on a realm that has password-based accounts. During a login attempt, shiro will use the PasswordMatcher and the PasswordService to automatically compare submitted passwords.

For example, if using Shiro's INI, here is how you might configure the PasswordMatcher and PasswordService:

 [main]
 ...
 passwordService = org.apache.shiro.authc.credential.DefaultPasswordService
 # configure the passwordService to use the settings you desire
 ...
 passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher
 passwordMatcher.passwordService = $passwordService
 ...
 # Finally, set the matcher on a realm that requires password matching for account authentication:
 myRealm = ...
 myRealm.credentialsMatcher = $passwordMatcher
 

Since:

1.2

See Also:

DefaultPasswordService, PasswordMatcher

Method Summary

String	encryptPassword(Object plaintextPassword) Converts the specified plaintext password (usually acquired from your application's 'new user' or 'password reset' workflow) into a formatted string safe for storage.
boolean	passwordsMatch(Object submittedPlaintext, String encrypted) Returns true if the submittedPlaintext password matches the existing saved password, false otherwise.

Method Detail

encryptPassword

String encryptPassword(Object plaintextPassword)
                       throws IllegalArgumentException

Converts the specified plaintext password (usually acquired from your application's 'new user' or 'password reset' workflow) into a formatted string safe for storage. The returned string can be safely saved with the corresponding user account record (e.g. as a 'password' attribute).

It is expected that the String returned from this method will be presented to the passwordsMatch(plaintext,encrypted) method when performing a password comparison check.

Usage

The input argument type can be any 'byte backed' Object - almost always either a String or character array representing passwords (character arrays are often a safer way to represent passwords as they can be cleared/nulled-out after use. Any argument type supported by ByteSource.Util#isCompatible(Object) is valid.

For example:

 String rawPassword = ...
 String encryptedValue = passwordService.encryptPassword(rawPassword);
 

or, identically:

 char[] rawPasswordChars = ...
 String encryptedValue = passwordService.encryptPassword(rawPasswordChars);
 

The resulting encryptedValue should be stored with the account to be retrieved later during a login attempt. For example:

 String encryptedValue = passwordService.encryptPassword(rawPassword);
 ...
 userAccount.setPassword(encryptedValue);
 userAccount.save(); //create or update to your data store
 

Parameters:

plaintextPassword - the raw password as 'byte-backed' object (String, character array, ByteSource, etc) usually acquired from your application's 'new user' or 'password reset' workflow.

Returns:

the encrypted password, formatted for storage.

Throws:

IllegalArgumentException - if the argument cannot be easily converted to bytes as defined by ByteSource.Util#isCompatible(Object).

See Also:

ByteSource.Util#isCompatible(Object)

passwordsMatch

boolean passwordsMatch(Object submittedPlaintext,
                       String encrypted)

Returns true if the submittedPlaintext password matches the existing saved password, false otherwise.

Usage

The submittedPlaintext argument type can be any 'byte backed' Object - almost always either a String or character array representing passwords (character arrays are often a safer way to represent passwords as they can be cleared/nulled-out after use. Any argument type supported by ByteSource.Util#isCompatible(Object) is valid.

For example:

 String submittedPassword = ...
 passwordService.passwordsMatch(submittedPassword, encryptedPassword);
 

or similarly:

 char[] submittedPasswordCharacters = ...
 passwordService.passwordsMatch(submittedPasswordCharacters, encryptedPassword);
 

Parameters:

submittedPlaintext - a raw/plaintext password submitted by an end user/Subject.

encrypted - the previously encrypted password known to be associated with an account. This value is expected to have been previously generated from the encryptPassword method (typically when the account is created or the account's password is reset).

Returns:

true if the submittedPlaintext password matches the existing saved password, false otherwise.

See Also:

ByteSource.Util#isCompatible(Object)