Class CryptoUtil
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringAlgorithm used for new password entries unless configured otherwise.static final StringPrefix of PBKDF2-HMAC-SHA256 password entries, the format used by default.static final StringName of the PBKDF2-HMAC-SHA256 algorithm, as used injspwiki.credentials.hash.algorithm.static final StringName of the PBKDF2-HMAC-SHA512 algorithm, as used injspwiki.credentials.hash.algorithm.static final StringPrefix of PBKDF2-HMAC-SHA512 password entries. -
Method Summary
Modifier and TypeMethodDescriptionstatic intdefaultPbkdf2Iterations(String algorithm) Returns the iteration count used for an algorithm unless configured otherwise.static StringgetPbkdf2SaltedPassword(byte[] password) Creates an iterated, salted PBKDF2-HMAC-SHA256 hash of the given password, suitable for storage.static StringgetPbkdf2SaltedPassword(byte[] password, String algorithm, int iterations) Creates an iterated, salted PBKDF2 hash of the given password with the given algorithm and iteration count, in the format{algorithm}iterations$base64(salt)$base64(hash).static StringgetSaltedPassword(byte[] password, String algorithm) Creates an RFC 2307-compliant salted, hashed password with the SHA1 or SHA-256 MessageDigest algorithm.static booleanhasPbkdf2Parameters(String entry, String algorithm, int iterations) Tells if a stored entry was created with exactly the given algorithm and iteration count, which is how to find out that an entry has to be hashed again after the settings changed.static booleanisPbkdf2Entry(String entry) Tells if the entry is a PBKDF2 password entry of any of the supported algorithms.static booleanisSupportedPbkdf2Algorithm(String algorithm) Tells if the algorithm is one of those that can be used to hash new passwords.static voidConvenience method for hashing and verifying salted SHA-1 or SHA-256 passwords from the command line.static booleanverifyPbkdf2SaltedPassword(byte[] password, String entry) Verifies a password against a PBKDF2 entry created bygetPbkdf2SaltedPassword(byte[])orgetPbkdf2SaltedPassword(byte[], String, int), with whatever algorithm and iteration count it was created with.static booleanverifySaltedPassword(byte[] password, String entry) Compares a password to a given entry and returns true, if it matches.
-
Field Details
-
PBKDF2_SHA256
Name of the PBKDF2-HMAC-SHA256 algorithm, as used injspwiki.credentials.hash.algorithm.- See Also:
-
PBKDF2_SHA512
Name of the PBKDF2-HMAC-SHA512 algorithm, as used injspwiki.credentials.hash.algorithm.- See Also:
-
PBKDF2_PREFIX
Prefix of PBKDF2-HMAC-SHA256 password entries, the format used by default.- See Also:
-
PBKDF2_SHA512_PREFIX
Prefix of PBKDF2-HMAC-SHA512 password entries.- See Also:
-
DEFAULT_PBKDF2_ALGORITHM
Algorithm used for new password entries unless configured otherwise.- See Also:
-
-
Method Details
-
main
Convenience method for hashing and verifying salted SHA-1 or SHA-256 passwords from the command line. This method requires
commons-codec-1.3.jar(or a newer version) to be on the classpath. Command line arguments are as follows:--hash password SSHA- hashes password and prints a password digest that looks like this:{SSHA}yfT8SRT/WoOuNuA6KbJeF10OznZmb28=--verify password digest- verifies password by extracting the salt from digest (which is identical to what is printed by--hash) and re-computing the digest again using the password and salt. If the password supplied is the same as the one used to create the original digest,truewill be printed; otherwisefalse
For example, one way to use this utility is to change to JSPWiki's
builddirectory and type the following command:java -cp JSPWiki.jar:../lib/commons-codec-1.3.jar org.apache.wiki.util.CryptoUtil --hash mynewpassword- Parameters:
args- arguments for this method as described above- Throws:
Exception- Catches nothing; throws everything up.
-
getSaltedPassword
public static String getSaltedPassword(byte[] password, String algorithm) throws NoSuchAlgorithmException Creates an RFC 2307-compliant salted, hashed password with the SHA1 or SHA-256 MessageDigest algorithm. After the password is digested, the first 20 or 32 bytes of the digest will be the actual password hash; the remaining bytes will be a randomly generated salt of length
DEFAULT_SALT_SIZE, for example:{SSHA}3cGWem65NCEkF5Ew5AEk45ak8LHUWAwPVXAyyw==In layman's terms, the formula is
digest( secret + salt ) + salt. The resulting digest is Base64-encoded.Note that successive invocations of this method with the same password will result in different hashes! (This, of course, is exactly the point.)
- Parameters:
password- the password to be digested- Returns:
- the Base64-encoded password hash, prepended by
{SSHA}or{SHA256}. - Throws:
NoSuchAlgorithmException- If your JVM does not supply the necessary algorithm. Should not happen.
-
getPbkdf2SaltedPassword
Creates an iterated, salted PBKDF2-HMAC-SHA256 hash of the given password, suitable for storage. Unlike the single-iteration digests above, the work factor makes offline cracking of a disclosed user database expensive. The format is
{PBKDF2-SHA256}iterations$base64(salt)$base64(hash), so the iteration count of stored entries can be raised in the future without breaking old entries.- Parameters:
password- the password to be hashed- Returns:
- the password entry, prepended by
{PBKDF2-SHA256} - Throws:
NoSuchAlgorithmException- If your JVM does not supply the necessary algorithm. Should not happen.
-
getPbkdf2SaltedPassword
public static String getPbkdf2SaltedPassword(byte[] password, String algorithm, int iterations) throws NoSuchAlgorithmException Creates an iterated, salted PBKDF2 hash of the given password with the given algorithm and iteration count, in the format{algorithm}iterations$base64(salt)$base64(hash).- Parameters:
password- the password to be hashedalgorithm- one ofPBKDF2_SHA256andPBKDF2_SHA512iterations- the iteration count, which must be positive- Returns:
- the password entry, prepended by the algorithm
- Throws:
NoSuchAlgorithmException- If your JVM does not supply the necessary algorithm. Should not happen.IllegalArgumentException- if the algorithm is not supported or the iteration count is not positive- Since:
- 3.0.1
-
verifyPbkdf2SaltedPassword
public static boolean verifyPbkdf2SaltedPassword(byte[] password, String entry) throws NoSuchAlgorithmException Verifies a password against a PBKDF2 entry created bygetPbkdf2SaltedPassword(byte[])orgetPbkdf2SaltedPassword(byte[], String, int), with whatever algorithm and iteration count it was created with. The comparison is constant-time.- Parameters:
password- the password to verifyentry- the stored password entry- Returns:
- true if the password matches the entry
- Throws:
NoSuchAlgorithmException- If your JVM does not supply the necessary algorithm. Should not happen.
-
isPbkdf2Entry
Tells if the entry is a PBKDF2 password entry of any of the supported algorithms.- Parameters:
entry- a stored password entry, which may benull- Returns:
trueif the entry starts with the prefix of a supported PBKDF2 algorithm- Since:
- 3.0.1
-
hasPbkdf2Parameters
Tells if a stored entry was created with exactly the given algorithm and iteration count, which is how to find out that an entry has to be hashed again after the settings changed.- Parameters:
entry- a stored password entryalgorithm- one ofPBKDF2_SHA256andPBKDF2_SHA512iterations- the iteration count- Returns:
trueif the entry is a well formed PBKDF2 entry of that algorithm and iteration count- Since:
- 3.0.1
-
isSupportedPbkdf2Algorithm
Tells if the algorithm is one of those that can be used to hash new passwords.- Parameters:
algorithm- the name of an algorithm, which may benull- Returns:
trueforPBKDF2_SHA256andPBKDF2_SHA512- Since:
- 3.0.1
-
defaultPbkdf2Iterations
Returns the iteration count used for an algorithm unless configured otherwise.- Parameters:
algorithm- one ofPBKDF2_SHA256andPBKDF2_SHA512- Returns:
- the default iteration count
- Throws:
IllegalArgumentException- if the algorithm is not supported- Since:
- 3.0.1
-
verifySaltedPassword
public static boolean verifySaltedPassword(byte[] password, String entry) throws NoSuchAlgorithmException Compares a password to a given entry and returns true, if it matches.- Parameters:
password- The password in bytes.entry- The password entry, typically starting with {SSHA}.- Returns:
- True, if the password matches.
- Throws:
NoSuchAlgorithmException- If there is no SHA available.
-