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'.
Algorithm |
A PasswordHash algorithm. class Algorithm |
Salt |
A PasswordHash salt. class Salt |
VerificationResult |
A hash verification result. class VerificationResult |
<init> |
The Argon2 memory-hard hashing function. PasswordHash() |
checkHash |
Verify a password against a hash and check the hash is suitable for normal use-cases. static fun checkHash(hash: String!, password: String!): VerificationResult!
Verify a password against a hash. static fun checkHash(hash: String!, password: String!, opsLimit: Long, memLimit: Long): VerificationResult! |
checkHashForInteractive |
Verify a password against a hash and check the hash is suitable for interactive use-cases. static fun checkHashForInteractive(hash: String!, password: String!): VerificationResult! |
checkHashForSensitive |
Verify a password against a hash and check the hash is suitable for sensitive use-cases. static fun checkHashForSensitive(hash: String!, password: String!): VerificationResult! |
hash |
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!): 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 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. 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 hash from a password, using limits on operations and memory that are suitable for most use-cases. static fun hash(password: String!): String!
Compute a hash from a password. static fun hash(password: String!, opsLimit: Long, memLimit: Long): String! |
hashInteractive |
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!): 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 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 hash from a password, using limits on operations and memory that are suitable for interactive use-cases. static fun hashInteractive(password: String!): String! |
hashSensitive |
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!): 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 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 hash from a password, using limits on operations and memory that are suitable for sensitive use-cases. static fun hashSensitive(password: String!): String! |
interactiveMemLimit |
Returns a memory limit for interactive use-cases. static fun interactiveMemLimit(): Long |
interactiveOpsLimit |
Returns an operations limit for interactive use-cases static fun interactiveOpsLimit(): Long |
maxHashLength |
Returns the maximum hash length static fun maxHashLength(): Int |
maxMemLimit |
Returns the max memory limit. static fun maxMemLimit(): Long |
maxOpsLimit |
Returns the maximum operations limit. static fun maxOpsLimit(): Long |
minHashLength |
Returns the minimum hash length static fun minHashLength(): Int |
minMemLimit |
Returns the minimum memory limit. static fun minMemLimit(): Long |
minOpsLimit |
Returns the minimum operations limit static fun minOpsLimit(): Long |
moderateMemLimit |
Returns a memory limit for most use-cases static fun moderateMemLimit(): Long |
moderateOpsLimit |
Returns an operations limit for most use-cases static fun moderateOpsLimit(): Long |
needsRehash |
Check if a hash needs to be regenerated using limits on operations and memory that are suitable for most use-cases. static fun needsRehash(hash: String!): Boolean
Check if a hash needs to be regenerated. static fun needsRehash(hash: String!, opsLimit: Long, memLimit: Long): Boolean |
needsRehashForInteractive |
Check if a hash needs to be regenerated using limits on operations and memory that are suitable for interactive use-cases. static fun needsRehashForInteractive(hash: String!): Boolean |
needsRehashForSensitive |
Check if a hash needs to be regenerated using limits on operations and memory that are suitable for sensitive use-cases. static fun needsRehashForSensitive(hash: String!): Boolean |
sensitiveMemLimit |
Returns a memory limit for sensitive use-cases static fun sensitiveMemLimit(): Long |
sensitiveOpsLimit |
Returns an operations limit for sensitive use-cases (4). static fun sensitiveOpsLimit(): Long |
verify |
Verify a password against a hash. static fun verify(hash: String!, password: String!): Boolean |