tuweni / org.apache.tuweni.crypto.sodium / PasswordHash

PasswordHash

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 parameters

Start 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'.

Types

Algorithm

class Algorithm

A PasswordHash algorithm.

Salt

class Salt

A PasswordHash salt.

VerificationResult

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.

Constructors

<init>

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 parameters

Start 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'.

Functions

checkHash

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 verify(hash, password, moderateOpsLimit(), moderateMemLimit()).

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.

checkHashForInteractive

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 verify(hash, password, interactiveOpsLimit(), interactiveMemLimit()).

Note: only supported when the sodium native library version >= 10.0.14 is available.

checkHashForSensitive

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 verify(hash, password, sensitiveOpsLimit(), sensitiveMemLimit()).

Note: only supported when the sodium native library version >= 10.0.14 is available.

hash

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 hash(password, moderateOpsLimit(), moderateMemLimit()).

static fun hash(password: String, opsLimit: Long, memLimit: Long): String

Compute a hash from a password.

hashInteractive

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 hash(password, sensitiveOpsLimit(), sensitiveMemLimit()).

hashSensitive

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 hash(password, sensitiveOpsLimit(), sensitiveMemLimit()).

interactiveMemLimit

static fun interactiveMemLimit(): Long

interactiveOpsLimit

static fun interactiveOpsLimit(): Long

maxHashLength

static fun maxHashLength(): Int

maxMemLimit

static fun maxMemLimit(): Long

maxOpsLimit

static fun maxOpsLimit(): Long

minHashLength

static fun minHashLength(): Int

minMemLimit

static fun minMemLimit(): Long

minOpsLimit

static fun minOpsLimit(): Long

moderateMemLimit

static fun moderateMemLimit(): Long

moderateOpsLimit

static fun moderateOpsLimit(): Long

needsRehash

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 needsRehash(hash, moderateOpsLimit(), moderateMemLimit()).

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.

needsRehashForInteractive

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 needsRehash(hash, interactiveOpsLimit(), interactiveMemLimit()).

Note: only supported when the sodium native library version >= 10.0.14 is available.

needsRehashForSensitive

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 needsRehash(hash, sensitiveOpsLimit(), sensitiveMemLimit()).

Note: only supported when the sodium native library version >= 10.0.14 is available.

sensitiveMemLimit

static fun sensitiveMemLimit(): Long

sensitiveOpsLimit

static fun sensitiveOpsLimit(): Long

verify

static fun verify(hash: String, password: String): Boolean

Verify a password against a hash.