nacl.pwhash

The package pwhash provides implementations of modern memory-hard password hashing construction exposing modules with a uniform API.

Functions exposed at top level

The top level module only provides the functions implementing ascii encoded hashing and verification.

nacl.pwhash.str(password, opslimit=OPSLIMIT_INTERACTIVE, memlimit=MEMLIMIT_INTERACTIVE)

Returns a password verifier hash, generated with the password hasher choosen as a default by libsodium.

Parameters:

• password (bytes) – password used to seed the key derivation procedure; it length must be between PASSWD_MIN and PASSWD_MAX

• opslimit (int) – the time component (operation count) of the key derivation procedure’s computational cost; it must be between OPSLIMIT_MIN and OPSLIMIT_MAX

• memlimit (int) – the memory occupation component of the key derivation procedure’s computational cost; it must be between MEMLIMIT_MIN and MEMLIMIT_MAX

Returns:

the ascii encoded password hash along with a prefix encoding the used hashing construct, the random generated salt and the operation and memory limits used to generate the password hash

Return type:

bytes

As of PyNaCl version 1.2 this is nacl.pwhash.argon2id.str().

Added in version 1.2.

nacl.pwhash.verify(password_hash, password)

This function checks if hashing the proposed password, with the same construction and parameters encoded in the password hash would generate the same encoded string, thus verifying the correct password has been proposed in an authentication attempt.

Added in version 1.2.

Module level constants

The top level module defines the constants related to the str() hashing construct and its corresponding verify() password verifier.

nacl.pwhash.PASSWD_MIN

nacl.pwhash.PASSWD_MAX

minimum and maximum length of the password to hash

nacl.pwhash.PWHASH_SIZE

maximum size of the encoded hash

nacl.pwhash.OPSLIMIT_MIN

nacl.pwhash.OPSLIMIT_MAX

minimum and maximum operation count for the hashing construct

nacl.pwhash.MEMLIMIT_MIN

nacl.pwhash.MEMLIMIT_MAX

minimum and maximum memory occupation for the hashing construct

and the recommended values for the opslimit and memlimit parameters

nacl.pwhash.MEMLIMIT_INTERACTIVE

nacl.pwhash.OPSLIMIT_INTERACTIVE

recommended values for the interactive user authentication password check case, leading to a sub-second hashing time

nacl.pwhash.MEMLIMIT_SENSITIVE

nacl.pwhash.OPSLIMIT_SENSITIVE

recommended values for generating a password hash/derived key meant to protect sensitive data, leading to a multi-second hashing time

nacl.pwhash.MEMLIMIT_MODERATE

nacl.pwhash.OPSLIMIT_MODERATE

values leading to a hashing time and memory cost intermediate between the interactive and the sensitive cases

Per-mechanism password hashing implementation modules

Along with the respective str() and verify() functions, the modules implementing named password hashing constructs expose also a kdf() function returning a raw pseudo-random bytes sequence derived from the input parameters

nacl.pwhash.argon2id

nacl.pwhash.argon2id.kdf(size, password, salt, opslimit=OPSLIMIT_SENSITIVE, memlimit=MEMLIMIT_SENSITIVE, encoder=nacl.encoding.RawEncoder)

Derive a size bytes long key from a caller-supplied password and salt pair using the argon2id partially data dependent memory-hard construct.

Parameters:

• size (int) – derived key size, must be between BYTES_MIN and BYTES_MAX

• password (bytes) – password used to seed the key derivation procedure; it length must be between PASSWD_MIN and PASSWD_MAX

• salt (bytes) – RANDOM salt used in the key derivation procedure; its length must be exactly SALTBYTES

• opslimit (int) – the time component (operation count) of the key derivation procedure’s computational cost; it must be between OPSLIMIT_MIN and OPSLIMIT_MAX

• memlimit (int) – the memory occupation component of the key derivation procedure’s computational cost; it must be between MEMLIMIT_MIN and MEMLIMIT_MAX

Return type:

bytes

The default settings for opslimit and memlimit are those deemed correct for generating a key, which can be used to protect sensitive data for a long time, leading to a multi-second hashing time.

Added in version 1.2.

nacl.pwhash.argon2id.str(password, opslimit=OPSLIMIT_INTERACTIVE, memlimit=MEMLIMIT_INTERACTIVE)

Returns a password verifier hash, generated with the argon2id password hasher.

See: nacl.pwhash.str() for the general API.

Added in version 1.2.

nacl.pwhash.argon2id.verify(password_hash, password)

This function verifies the proposed password, using password_hash as a password verifier.

See: nacl.pwhash.verify() for the general API.

Added in version 1.2.

Module level constants

The module defines the constants related to the kdf() raw hashing construct

nacl.pwhash.argon2id.SALTBYTES

the length of the random bytes sequence passed in as a salt to the kdf()

nacl.pwhash.argon2id.BYTES_MIN

nacl.pwhash.argon2id.BYTES_MAX

the minimum and maximum allowed values for the size parameter of the kdf()

The meaning of each of the constants

nacl.pwhash.argon2id.PASSWD_MIN

nacl.pwhash.argon2id.PASSWD_MAX

nacl.pwhash.argon2id.PWHASH_SIZE

nacl.pwhash.argon2id.OPSLIMIT_MIN

nacl.pwhash.argon2id.OPSLIMIT_MAX

nacl.pwhash.argon2id.MEMLIMIT_MIN

nacl.pwhash.argon2id.MEMLIMIT_MAX

nacl.pwhash.argon2id.MEMLIMIT_INTERACTIVE

nacl.pwhash.argon2id.OPSLIMIT_INTERACTIVE

nacl.pwhash.argon2id.MEMLIMIT_SENSITIVE

nacl.pwhash.argon2id.OPSLIMIT_SENSITIVE

nacl.pwhash.argon2id.MEMLIMIT_MODERATE

nacl.pwhash.argon2id.OPSLIMIT_MODERATE

is the same as in nacl.hash.

nacl.pwhash.argon2i

nacl.pwhash.argon2i.kdf(size, password, salt, opslimit=OPSLIMIT_SENSITIVE, memlimit=MEMLIMIT_SENSITIVE, encoder=nacl.encoding.RawEncoder)

Derive a size bytes long key from a caller-supplied password and salt pair using the argon2i data independent memory-hard construct.

See: py:func:nacl.pwhash.argon2id.kdf for the general API.

Added in version 1.2.

nacl.pwhash.argon2i.str(password, opslimit=OPSLIMIT_INTERACTIVE, memlimit=MEMLIMIT_INTERACTIVE)

Returns a password verifier hash, generated with the argon2i password hasher.

See: nacl.pwhash.str() for the general API.

Added in version 1.2.

nacl.pwhash.argon2i.verify(password_hash, password)

This function verifies the proposed password, using password_hash as a password verifier.

See: nacl.pwhash.verify() for the general API.

Added in version 1.2.

Module level constants

The meaning of each of the constants

nacl.pwhash.argon2i.PASSWD_MIN

nacl.pwhash.argon2i.PASSWD_MAX

nacl.pwhash.argon2i.PWHASH_SIZE

nacl.pwhash.argon2i.SALTBYTES

nacl.pwhash.argon2i.BYTES_MIN

nacl.pwhash.argon2i.BYTES_MAX

nacl.pwhash.argon2i.OPSLIMIT_MIN

nacl.pwhash.argon2i.OPSLIMIT_MAX

nacl.pwhash.argon2i.MEMLIMIT_MIN

nacl.pwhash.argon2i.MEMLIMIT_MAX

nacl.pwhash.argon2i.MEMLIMIT_INTERACTIVE

nacl.pwhash.argon2i.OPSLIMIT_INTERACTIVE

nacl.pwhash.argon2i.MEMLIMIT_SENSITIVE

nacl.pwhash.argon2i.OPSLIMIT_SENSITIVE

nacl.pwhash.argon2i.MEMLIMIT_MODERATE

nacl.pwhash.argon2i.OPSLIMIT_MODERATE

is the same as in nacl.pwhash and nacl.pwhash.argon2id

nacl.pwhash.scrypt

nacl.pwhash.scrypt.kdf(size, password, salt, opslimit=OPSLIMIT_SENSITIVE, memlimit=MEMLIMIT_SENSITIVE, encoder=nacl.encoding.RawEncoder)

Derive a size bytes long key from a caller-supplied password and salt pair using the scrypt data dependent memory-hard construct.

See: nacl.pwhash.argon2id.kdf() for the general API.

Raises:

nacl.exceptions.UnavailableError – If called when using a minimal build of libsodium.

Added in version 1.2.

nacl.pwhash.scrypt.str(password, opslimit=OPSLIMIT_INTERACTIVE, memlimit=MEMLIMIT_INTERACTIVE)

Returns a password verifier hash, generated with the scrypt password hasher.

See: nacl.pwhash.str() for the general API.

Raises:

nacl.exceptions.UnavailableError – If called when using a minimal build of libsodium.

Added in version 1.2.

nacl.pwhash.scrypt.verify(password_hash, password)

This function verifies the proposed password, using password_hash as a password verifier.

See: py:func:nacl.pwhash.verify for the general API.

Raises:

nacl.exceptions.UnavailableError – If called when using a minimal build of libsodium.

Added in version 1.2.

Module level constants

The meaning of each of the constants

nacl.pwhash.scrypt.PASSWD_MIN

nacl.pwhash.scrypt.PASSWD_MAX

nacl.pwhash.scrypt.PWHASH_SIZE

nacl.pwhash.scrypt.SALTBYTES

nacl.pwhash.scrypt.BYTES_MIN

nacl.pwhash.scrypt.BYTES_MAX

nacl.pwhash.scrypt.OPSLIMIT_MIN

nacl.pwhash.scrypt.OPSLIMIT_MAX

nacl.pwhash.scrypt.MEMLIMIT_MIN

nacl.pwhash.scrypt.MEMLIMIT_MAX

nacl.pwhash.scrypt.MEMLIMIT_INTERACTIVE

nacl.pwhash.scrypt.OPSLIMIT_INTERACTIVE

nacl.pwhash.scrypt.MEMLIMIT_SENSITIVE

nacl.pwhash.scrypt.OPSLIMIT_SENSITIVE

nacl.pwhash.scrypt.MEMLIMIT_MODERATE

nacl.pwhash.scrypt.OPSLIMIT_MODERATE

is the same as in nacl.pwhash and nacl.pwhash.argon2id