scrypt 0.9.0

Installation

For Debian and Ubuntu, please ensure that the following packages are installed:

$ sudo apt-get install build-essential libssl-dev python-dev

For Fedora and RHEL-derivatives, please ensure that the following packages are installed:

$ sudo yum install gcc openssl-devel python-devel

For OSX, please do the following:

$ brew install openssl
$ export CFLAGS="-I$(brew --prefix openssl)/include $CFLAGS"
$ export LDFLAGS="-L$(brew --prefix openssl)/lib $LDFLAGS"

For OSX, you can also use the precompiled wheels. They are installed by:

$ pip install scrypt

For Windows, please use the precompiled wheels. They are installed by:

$ pip install scrypt

For Windows, when the package should be compiled, the development package from https://slproweb.com/products/Win32OpenSSL.html is needed. It needs to be installed to C:OpenSSL-Win64.

You can install py-scrypt from this repository if you want the latest but possibly non-compiling version:

$ git clone https://github.com/holgern/py-scrypt.git
$ cd py-scrypt
$ python setup.py build

Become superuser (or use virtualenv):
# python setup.py install

Run tests after install:
$ python setup.py test

Or you can install the latest release from PyPi:

$ pip install scrypt

Users of the Anaconda Python distribution can directly obtain pre-built Windows, Intel Linux or macOS / OSX binaries from the conda-forge channel. This can be done via:

$ conda install -c conda-forge scrypt

If you want py-scrypt for your Python 3 environment, just run the above commands with your Python 3 interpreter. Py-scrypt supports both Python 2 and 3.

From version 0.6.0 (not available on PyPi yet), py-scrypt supports PyPy as well.

Changelog

Usage

For encryption/decryption, the library exports two functions encrypt and decrypt:

>>> import scrypt
>>> data = scrypt.encrypt('a secret message', 'password', maxtime=0.1) # This will take at least 0.1 seconds
>>> data[:20]
'scrypt\x00\r\x00\x00\x00\x08\x00\x00\x00\x01RX9H'
>>> scrypt.decrypt(data, 'password', maxtime=0.1) # This will also take at least 0.1 seconds
'a secret message'
>>> scrypt.decrypt(data, 'password', maxtime=0.05) # scrypt won't be able to decrypt this data fast enough
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
scrypt.error: decrypting file would take too long
>>> scrypt.decrypt(data, 'wrong password', maxtime=0.1) # scrypt will throw an exception if the password is incorrect
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
scrypt.error: password is incorrect

From these, one can make a simple password verifier using the following functions:

import os
import scrypt

def hash_password(password, maxtime=0.5, datalength=64):
    """Create a secure password hash using scrypt encryption.

    Args:
        password: The password to hash
        maxtime: Maximum time to spend hashing in seconds
        datalength: Length of the random data to encrypt

    Returns:
        bytes: An encrypted hash suitable for storage and later verification
    """
    return scrypt.encrypt(os.urandom(datalength), password, maxtime=maxtime)

def verify_password(hashed_password, guessed_password, maxtime=0.5):
    """Verify a password against its hash with better error handling.

    Args:
        hashed_password: The stored password hash from hash_password()
        guessed_password: The password to verify
        maxtime: Maximum time to spend in verification

    Returns:
        tuple: (is_valid, status_code) where:
            - is_valid: True if password is correct, False otherwise
            - status_code: One of "correct", "wrong_password", "time_limit_exceeded",
              "memory_limit_exceeded", or "error"

    Raises:
        scrypt.error: Only raised for resource limit errors, which you may want to
                    handle by retrying with higher limits or force=True
    """
    try:
        scrypt.decrypt(hashed_password, guessed_password, maxtime, encoding=None)
        return True, "correct"
    except scrypt.error as e:
        # Check the specific error message to differentiate between causes
        error_message = str(e)
        if error_message == "password is incorrect":
            # Wrong password was provided
            return False, "wrong_password"
        elif error_message == "decrypting file would take too long":
            # Time limit exceeded
            raise  # Re-raise so caller can handle appropriately
        elif error_message == "decrypting file would take too much memory":
            # Memory limit exceeded
            raise  # Re-raise so caller can handle appropriately
        else:
            # Some other error occurred (corrupted data, etc.)
            return False, "error"

# Example usage:

# Create a hash of a password
stored_hash = hash_password("correct_password", maxtime=0.1)

# Verify with correct password
is_valid, status = verify_password(stored_hash, "correct_password", maxtime=0.1)
if is_valid:
    print("Password is correct!")  # This will be printed

# Verify with wrong password
is_valid, status = verify_password(stored_hash, "wrong_password", maxtime=0.1)
if not is_valid:
    if status == "wrong_password":
        print("Password is incorrect!")  # This will be printed

# Verify with insufficient time
try:
    # Set maxtime very low to trigger a time limit error
    is_valid, status = verify_password(stored_hash, "correct_password", maxtime=0.00001)
except scrypt.error as e:
    if "would take too long" in str(e):
        print("Time limit exceeded, try with higher maxtime or force=True")

        # Retry with force=True
        result = scrypt.decrypt(stored_hash, "correct_password", maxtime=0.00001, force=True, encoding=None)
        print("Forced decryption successful!")

The encrypt function accepts several parameters to control its behavior:

encrypt(input, password, maxtime=5.0, maxmem=0, maxmemfrac=0.5, logN=0, r=0, p=0, force=False, verbose=False)

Where:

• input: Data to encrypt (bytes or str)

• password: Password for encryption (bytes or str)

• maxtime: Maximum time to spend in seconds

• maxmem: Maximum memory to use in bytes (0 for unlimited)

• maxmemfrac: Maximum fraction of available memory to use (0.0 to 1.0)

• logN, r, p: Parameters controlling the scrypt key derivation function - If all three are zero (default), optimal parameters are chosen automatically - If provided, all three must be non-zero and will be used explicitly

• force: If True, do not check whether encryption will exceed the estimated memory or time

• verbose: If True, display parameter information

The decrypt function has a simpler interface:

decrypt(input, password, maxtime=300.0, maxmem=0, maxmemfrac=0.5, encoding='utf-8', verbose=False, force=False)

Where:

• input: Encrypted data (bytes or str)

• password: Password for decryption (bytes or str)

• maxtime: Maximum time to spend in seconds

• maxmem: Maximum memory to use in bytes (0 for unlimited)

• maxmemfrac: Maximum fraction of available memory to use

• encoding: Encoding to use for output string (None for raw bytes)

• verbose: If True, display parameter information

• force: If True, do not check whether decryption will exceed the estimated memory or time

But, if you want output that is deterministic and constant in size, you can use the hash function:

>>> import scrypt
>>> h1 = scrypt.hash('password', 'random salt')
>>> len(h1)  # The hash will be 64 bytes by default, but is overridable.
64
>>> h1[:10]
'\xfe\x87\xf3hS\tUo\xcd\xc8'
>>> h2 = scrypt.hash('password', 'random salt')
>>> h1 == h2 # The hash function is deterministic
True

The hash function accepts the following parameters:

hash(password, salt, N=1<<14, r=8, p=1, buflen=64)

Where:

• password: The password to hash (bytes or str)

• salt: Salt for the hash (bytes or str)

• N: CPU/memory cost parameter (must be a power of 2)

• r: Block size parameter

• p: Parallelization parameter

• buflen: Output buffer length

The parameters r, p, and buflen must satisfy r * p < 2^30 and buflen <= (2^32 - 1) * 32. The parameter N must be a power of 2 greater than 1. N, r, and p must all be positive.

For advanced usage, the library also provides two utility functions:

• pickparams(maxmem=0, maxmemfrac=0.5, maxtime=5.0, verbose=0): Automatically chooses optimal scrypt parameters based on system resources. Returns (logN, r, p) tuple.

• checkparams(logN, r, p, maxmem=0, maxmemfrac=0.5, maxtime=5.0, verbose=0, force=0): Verifies that the provided parameters are valid and within resource limits.

Acknowledgements

Scrypt was created by Colin Percival and is licensed as 2-clause BSD. Since scrypt does not normally build as a shared library, I have included the source for the currently latest version of the library in this repository. When a new version arrives, I will update these sources.

Kelvin Wong on Bitbucket provided changes to make the library available on Mac OS X 10.6 and earlier, as well as changes to make the library work more like the command-line version of scrypt by default. Kelvin also contributed with the unit tests, lots of cross platform testing and work on the hash function.

Burstaholic on Bitbucket provided the necessary changes to make the library build on Windows.

The python-appveyor-demo repository for setting up automated Windows builds for a multitude of Python versions.

License

This library is licensed under the same license as scrypt; 2-clause BSD.