public interface PasswordService
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.
PasswordService
is used at two different times during an application's lifecycle:
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 storeBe sure to save this encrypted password in your data store and never the original/raw submitted password.
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
DefaultPasswordService
,
PasswordMatcher
Modifier and Type | Method and Description |
---|---|
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. |
String encryptPassword(Object plaintextPassword) throws IllegalArgumentException
passwordsMatch(plaintext,encrypted)
method when performing a
password comparison check.
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
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.IllegalArgumentException
- if the argument cannot be easily converted to bytes as defined by
ByteSource.Util#isCompatible(Object)
.ByteSource.Util#isCompatible(Object)
boolean passwordsMatch(Object submittedPlaintext, String encrypted)
true
if the submittedPlaintext
password matches the existing saved
password,
false
otherwise.
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);
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).true
if the submittedPlaintext
password matches the existing saved
password,
false
otherwise.ByteSource.Util#isCompatible(Object)
Copyright © 2004–2020 The Apache Software Foundation. All rights reserved.