# 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 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)

  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`