class PasswordHash
(source)
The Argon2 memory-hard hashing function.
Argon2 summarizes the state of the art in the design of memory-hard functions.
It aims at the highest memory filling rate and effective use of multiple computing units, while still providing defense against tradeoff attacks.
It prevents ASICs from having a significant advantage over software implementations.
Guidelines for choosing the parametersStart by determining how much memory the function can use. What will be the highest number of threads/processes evaluating the function simultaneously (ideally, no more than 1 per CPU core)? How much physical memory is guaranteed to be available?
Set memlimit to the amount of memory you want to reserve for password hashing.
Then, set opslimit to 3 and measure the time it takes to hash a password.
If this it is way too long for your application, reduce memlimit, but keep opslimit set to 3.
If the function is so fast that you can afford it to be more computationally intensive without any usability issues, increase opslimit.
For online use (e.g. login in on a website), a 1 second computation is likely to be the acceptable maximum.
For interactive use (e.g. a desktop application), a 5 second pause after having entered a password is acceptable if the password doesn't need to be entered more than once per session.
For non-interactive use and infrequent use (e.g. restoring an encrypted backup), an even slower computation can be an option.
This class depends upon the JNR-FFI library being available on the classpath, along with its dependencies. See https://github.com/jnr/jnr-ffi. JNR-FFI can be included using the gradle dependency 'com.github.jnr:jnr-ffi'.
class Algorithm
A PasswordHash algorithm. |
|
class Salt
A PasswordHash salt. |
|
class VerificationResult
A hash verification result. Note: methods returning this result are only supported when the sodium native library version >= 10.0.14 is available. |
PasswordHash()
The Argon2 memory-hard hashing function. Argon2 summarizes the state of the art in the design of memory-hard functions. It aims at the highest memory filling rate and effective use of multiple computing units, while still providing defense against tradeoff attacks. It prevents ASICs from having a significant advantage over software implementations. Guidelines for choosing the parametersStart by determining how much memory the function can use. What will be the highest number of threads/processes evaluating the function simultaneously (ideally, no more than 1 per CPU core)? How much physical memory is guaranteed to be available? Set memlimit to the amount of memory you want to reserve for password hashing. Then, set opslimit to 3 and measure the time it takes to hash a password. If this it is way too long for your application, reduce memlimit, but keep opslimit set to 3. If the function is so fast that you can afford it to be more computationally intensive without any usability issues, increase opslimit. For online use (e.g. login in on a website), a 1 second computation is likely to be the acceptable maximum. For interactive use (e.g. a desktop application), a 5 second pause after having entered a password is acceptable if the password doesn't need to be entered more than once per session. For non-interactive use and infrequent use (e.g. restoring an encrypted backup), an even slower computation can be an option. This class depends upon the JNR-FFI library being available on the classpath, along with its dependencies. See https://github.com/jnr/jnr-ffi. JNR-FFI can be included using the gradle dependency 'com.github.jnr:jnr-ffi'. |
static fun checkHash(hash: String, password: String): VerificationResult
Verify a password against a hash and check the hash is suitable for normal use-cases. Equivalent to Note: only supported when the sodium native library version >= 10.0.14 is available. static fun checkHash(hash: String, password: String, opsLimit: Long, memLimit: Long): VerificationResult
Verify a password against a hash. Note: only supported when the sodium native library version >= 10.0.14 is available. |
|
static fun checkHashForInteractive(hash: String, password: String): VerificationResult
Verify a password against a hash and check the hash is suitable for interactive use-cases. Equivalent to Note: only supported when the sodium native library version >= 10.0.14 is available. |
|
static fun checkHashForSensitive(hash: String, password: String): VerificationResult
Verify a password against a hash and check the hash is suitable for sensitive use-cases. Equivalent to Note: only supported when the sodium native library version >= 10.0.14 is available. |
|
static fun hash(password: String, length: Int, salt: Salt): Bytes static fun hash(password: Bytes, length: Int, salt: Salt): Bytes static fun hash(password: ByteArray, length: Int, salt: Salt): ByteArray
Compute a key from a password, using the currently recommended algorithm and limits on operations and memory that are suitable for most use-cases. static fun hash(password: String, length: Int, salt: Salt, algorithm: Algorithm): Bytes static fun hash(password: Bytes, length: Int, salt: Salt, algorithm: Algorithm): Bytes static fun hash(password: ByteArray, length: Int, salt: Salt, algorithm: Algorithm): ByteArray
Compute a key from a password, using limits on operations and memory that are suitable for most use-cases. static fun hash(password: String, length: Int, salt: Salt, opsLimit: Long, memLimit: Long, algorithm: Algorithm): Bytes static fun hash(password: Bytes, length: Int, salt: Salt, opsLimit: Long, memLimit: Long, algorithm: Algorithm): Bytes static fun hash(password: ByteArray, length: Int, salt: Salt, opsLimit: Long, memLimit: Long, algorithm: Algorithm): ByteArray
Compute a key from a password. static fun hash(password: String): String
Compute a hash from a password, using limits on operations and memory that are suitable for most use-cases. Equivalent to static fun hash(password: String, opsLimit: Long, memLimit: Long): String
Compute a hash from a password. |
|
static fun hashInteractive(password: String, length: Int, salt: Salt): Bytes static fun hashInteractive(password: Bytes, length: Int, salt: Salt): Bytes static fun hashInteractive(password: ByteArray, length: Int, salt: Salt): ByteArray
Compute a key from a password, using the currently recommended algorithm and limits on operations and memory that are suitable for interactive use-cases. static fun hashInteractive(password: String, length: Int, salt: Salt, algorithm: Algorithm): Bytes static fun hashInteractive(password: Bytes, length: Int, salt: Salt, algorithm: Algorithm): Bytes static fun hashInteractive(password: ByteArray, length: Int, salt: Salt, algorithm: Algorithm): ByteArray
Compute a key from a password, using limits on operations and memory that are suitable for interactive use-cases. static fun hashInteractive(password: String): String
Compute a hash from a password, using limits on operations and memory that are suitable for interactive use-cases. Equivalent to |
|
static fun hashSensitive(password: String, length: Int, salt: Salt): Bytes static fun hashSensitive(password: Bytes, length: Int, salt: Salt): Bytes static fun hashSensitive(password: ByteArray, length: Int, salt: Salt): ByteArray
Compute a key from a password, using the currently recommended algorithm and limits on operations and memory that are suitable for sensitive use-cases. static fun hashSensitive(password: String, length: Int, salt: Salt, algorithm: Algorithm): Bytes static fun hashSensitive(password: Bytes, length: Int, salt: Salt, algorithm: Algorithm): Bytes static fun hashSensitive(password: ByteArray, length: Int, salt: Salt, algorithm: Algorithm): ByteArray
Compute a key from a password, using limits on operations and memory that are suitable for sensitive use-cases. static fun hashSensitive(password: String): String
Compute a hash from a password, using limits on operations and memory that are suitable for sensitive use-cases. Equivalent to |
|
static fun interactiveMemLimit(): Long |
|
static fun interactiveOpsLimit(): Long |
|
static fun maxHashLength(): Int |
|
static fun maxMemLimit(): Long |
|
static fun maxOpsLimit(): Long |
|
static fun minHashLength(): Int |
|
static fun minMemLimit(): Long |
|
static fun minOpsLimit(): Long |
|
static fun moderateMemLimit(): Long |
|
static fun moderateOpsLimit(): Long |
|
static fun needsRehash(hash: String): Boolean
Check if a hash needs to be regenerated using limits on operations and memory that are suitable for most use-cases. Equivalent to Note: only supported when the sodium native library version >= 10.0.14 is available. static fun needsRehash(hash: String, opsLimit: Long, memLimit: Long): Boolean
Check if a hash needs to be regenerated. Check if a hash matches the parameters opslimit and memlimit, and the current default algorithm. Note: only supported when the sodium native library version >= 10.0.14 is available. |
|
static fun needsRehashForInteractive(hash: String): Boolean
Check if a hash needs to be regenerated using limits on operations and memory that are suitable for interactive use-cases. Equivalent to Note: only supported when the sodium native library version >= 10.0.14 is available. |
|
static fun needsRehashForSensitive(hash: String): Boolean
Check if a hash needs to be regenerated using limits on operations and memory that are suitable for sensitive use-cases. Equivalent to Note: only supported when the sodium native library version >= 10.0.14 is available. |
|
static fun sensitiveMemLimit(): Long |
|
static fun sensitiveOpsLimit(): Long |
|
static fun verify(hash: String, password: String): Boolean
Verify a password against a hash. |