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 using the construction choosen as preferred by the upstream libsodium library.

str(password, opslimit=OPSLIMIT_INTERACTIVE, memlimit=MEMLIMIT_INTERACTIVE)[source]

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().

New in version 1.2.

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.

New 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.

PASSWD_MIN
PASSWD_MAX

minimum and maximum length of the password to hash

PWHASH_SIZE

maximum size of the encoded hash

OPSLIMIT_MIN
OPSLIMIT_MAX

minimum and maximum operation count for the hashing construct

MEMLIMIT_MIN
MEMLIMIT_MAX

minimum and maximum memory occupation for the hashing construct

and the recommended values for the opslimit and memlimit parameters

MEMLIMIT_INTERACTIVE
OPSLIMIT_INTERACTIVE

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

MEMLIMIT_SENSITIVE
OPSLIMIT_SENSITIVE

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

MEMLIMIT_MODERATE
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.argon2i

kdf(size, password, salt, opslimit=8, memlimit=536870912, encoder=<class 'nacl.encoding.RawEncoder'>)[source]

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

the enclosing module provides the constants

  • OPSLIMIT_INTERACTIVE
  • MEMLIMIT_INTERACTIVE
  • OPSLIMIT_MODERATE
  • MEMLIMIT_MODERATE
  • OPSLIMIT_SENSITIVE
  • MEMLIMIT_SENSITIVE

as a guidance for correct settings.

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

New in version 1.2.

str(password, opslimit=4, memlimit=33554432)[source]

Hashes a password with a random salt, using the memory-hard argon2i construct and returning an ascii string that has all the needed info to check against a future password

The default settings for opslimit and memlimit are those deemed correct for the interactive user login case.

Parameters:
  • password (bytes) –
  • opslimit (int) –
  • memlimit (int) –
Return type:

bytes

New in version 1.2.

nacl.pwhash.argon2id

kdf(size, password, salt, opslimit=4, memlimit=1073741824, encoder=<class 'nacl.encoding.RawEncoder'>)[source]

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

the enclosing module provides the constants

  • OPSLIMIT_INTERACTIVE
  • MEMLIMIT_INTERACTIVE
  • OPSLIMIT_MODERATE
  • MEMLIMIT_MODERATE
  • OPSLIMIT_SENSITIVE
  • MEMLIMIT_SENSITIVE

as a guidance for correct settings.

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

New in version 1.2.

str(password, opslimit=2, memlimit=67108864)[source]

Hashes a password with a random salt, using the memory-hard argon2id construct and returning an ascii string that has all the needed info to check against a future password

The default settings for opslimit and memlimit are those deemed correct for the interactive user login case.

Parameters:
  • password (bytes) –
  • opslimit (int) –
  • memlimit (int) –
Return type:

bytes

New in version 1.2.

nacl.pwhash.scrypt

kdf(size, password, salt, opslimit=33554432, memlimit=1073741824, encoder=<class 'nacl.encoding.RawEncoder'>)[source]

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

the enclosing module provides the constants

  • OPSLIMIT_INTERACTIVE
  • MEMLIMIT_INTERACTIVE
  • OPSLIMIT_SENSITIVE
  • MEMLIMIT_SENSITIVE
  • OPSLIMIT_MODERATE
  • MEMLIMIT_MODERATE

as a guidance for correct settings respectively for the interactive login and the long term key protecting sensitive data use cases.

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

New in version 1.2.

str(password, opslimit=524288, memlimit=16777216)[source]

Hashes a password with a random salt, using the memory-hard scryptsalsa208sha256 construct and returning an ascii string that has all the needed info to check against a future password

The default settings for opslimit and memlimit are those deemed correct for the interactive user login case.

Parameters:
  • password (bytes) –
  • opslimit (int) –
  • memlimit (int) –
Return type:

bytes

New in version 1.2.

verify(password_hash, password)[source]

Takes the output of scryptsalsa208sha256 and compares it against a user provided password to see if they are the same

Parameters:
  • password_hash – bytes
  • password – bytes
Return type:

boolean

New in version 1.2.