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). <p/> It is expected that the string returned from this method will be presented to the {@link #passwordsMatch(Object, string) passwordsMatch(plaintext,encrypted)} method when performing a password comparison check. <h3>Usage</h3> The input argument type can be any 'byte backed' {@code 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 {@link ByteSourceUtil#isCompatible(Object)} is valid. <p/> For example: <pre> string rawPassword = ... string encryptedValue = passwordService.encryptPassword(rawPassword); </pre> or, identically: <pre> char[] rawPasswordChars = ... string encryptedValue = passwordService.encryptPassword(rawPasswordChars); </pre> <p/> The resulting {@code encryptedValue} should be stored with the account to be retrieved later during a login attempt. For example: <pre> string encryptedValue = passwordService.encryptPassword(rawPassword); ... userAccount.setPassword(encryptedValue); userAccount.save(); //create or update to your data store </pre>
Returns {@code true} if the {@code submittedPlaintext} password matches the existing {@code saved} password, {@code false} otherwise. <h3>Usage</h3> The {@code submittedPlaintext} argument type can be any 'byte backed' {@code 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 {@link ByteSourceUtil#isCompatible(Object)} is valid. <p/> For example: <pre> string submittedPassword = ... passwordService.passwordsMatch(submittedPassword, encryptedPassword); </pre> or similarly: <pre> char[] submittedPasswordCharacters = ... passwordService.passwordsMatch(submittedPasswordCharacters, encryptedPassword); </pre>
<pre> string submittedPlaintextPassword = ... string encryptedValue = passwordService.encryptPassword(submittedPlaintextPassword); ... userAccount.setPassword(encryptedValue); userAccount.save(); //create or update to your data store </pre> Be sure to save this encrypted password in your data store and never the original/raw submitted password. <h3>Login Password Comparison</h3> Shiro performs the comparison during login automatically. Along with your {@code PasswordService}, you just have to configure a {@link PasswordMatcher} on a realm that has password-based accounts. During a login attempt, shiro will use the {@code PasswordMatcher} and the {@code PasswordService} to automatically compare submitted passwords. <p/> For example, if using Shiro's INI, here is how you might configure the PasswordMatcher and PasswordService: <pre> main
... passwordService = hunt.shiro.authc.credential.DefaultPasswordService # configure the passwordService to use the settings you desire ... passwordMatcher = hunt.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 </pre>
@see DefaultPasswordService @see PasswordMatcher
A {@code PasswordService} supports common use cases when using passwords as a credentials mechanism. <p/> Most importantly, implementations of this interface are expected to employ best-practices to ensure that passwords remain as safe as possible in application environments. <h2>Usage</h2> A {@code PasswordService} is used at two different times during an application's lifecycle: <ul> <li>When creating a user account or resetting their password</li> <li>When a user logs in, when passwords must be compared</li> </ul> <h3>Account Creation or Password Reset</h3> 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 {@link #encryptPassword(Object)} method to create the safer value. For