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)[source]

Returns a password verifier hash, generated with the password hasher chosen 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)[source]: 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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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