Metadata-Version: 1.1
Name: multikdf
Version: 0.01.31
Summary: multikdf
Home-page: https://github.com/sundarnagarajan/pymultikdf
Author: Sundar Nagarajan
Author-email: UNKNOWN
License: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Download-URL: https://github.com/sundarnagarajan/pymultikdf/tree/0.01.31
Description: pymultikdf
        ==========
        
        | This python module provides wrappers for C functions implementing the
        | following Key Derivation Functions (KDF)s:
        
        -  PBKDF2
        -  bcrypt
        -  scrypt
        
        What is a Key Derivation Function?
        ----------------------------------
        
        From wikipedia (https://en.wikipedia.org/wiki/Key_derivation_function):
        
        In cryptography, a key derivation function (or KDF) derives one or more
        secret keys from a secret value such as a master key, a password, or a
        passphrase using a pseudo-random function.[1][2] KDFs can be used to
        stretch keys into longer keys or to obtain keys of a required format,
        such as converting a group element that is the result of a
        Diffie–Hellman key exchange into a symmetric key for use with AES. Keyed
        cryptographic hash functions are popular examples of pseudo-random
        functions used for key derivation.
        
        What is PBKDF2?
        ~~~~~~~~~~~~~~~
        
        PBKDF2 (Password-Based Key Derivation Function 2) is a key derivation
        function that is part of RSA Laboratories' Public-Key Cryptography
        Standards (PKCS) series, specifically PKCS #5 v2.0, also published as
        Internet Engineering Task Force's RFC 2898. It replaces an earlier
        standard, PBKDF1, which could only produce derived keys up to 160 bits
        long.
        
        See: https://en.wikipedia.org/wiki/PBKDF2
        
        What is bcrypt?
        ~~~~~~~~~~~~~~~
        
        bcrypt is a key derivation function for passwords designed by Niels
        Provos and David Mazières, based on the Blowfish cipher, and presented
        at USENIX in 1999.[1] Besides incorporating a salt to protect against
        rainbow table attacks, bcrypt is an adaptive function: over time, the
        iteration count can be increased to make it slower, so it remains
        resistant to brute-force search attacks even with increasing computation
        power.
        
        The bcrypt function is the default password hash algorithm for BSD and
        other systems including some Linux distributions such as SUSE Linux.[2]
        The prefix "$2a$" or "$2b$" (or "$2y$") in a hash string in a shadow
        password file indicates that hash string is a bcrypt hash in modular
        crypt format.[3] The rest of the hash string includes the cost
        parameter, a 128-bit salt (base-64 encoded as 22 characters), and 184
        bits of the resulting hash value (base-64 encoded as 31 characters).[4]
        The cost parameter specifies a key expansion iteration count as a power
        of two, which is an input to the crypt algorithm.
        
        See: https://en.wikipedia.org/wiki/Bcrypt
        
        What is scrypt?
        ~~~~~~~~~~~~~~~
        
        In cryptography, scrypt is a password-based key derivation function
        created by Colin Percival, originally for the Tarsnap online backup
        service.[1] The algorithm was specifically designed to make it costly to
        perform large-scale custom hardware attacks by requiring large amounts
        of memory. In 2012, the scrypt algorithm was published by IETF as an
        Internet Draft, intended to become an informational RFC.[2]
        
        See: https://en.wikipedia.org/wiki/Scrypt
        
        Relationship to existing packages
        =================================
        
        Existing python packages for PBKDF2, bcrypt, scrypt
        
        -  pip install fastpbkdf2
        -  pip install bcrypt
        -  pip install scrypt
        
        Why a new module?
        -----------------
        
        Sometimes one wants to try or use MULTIPLE different Key Derivation
        Functions. In such cases, instead of installing MULTIPLE SEPARATE
        python, packages, just this single module can be installed and used.
        
        This may also be a convenience when porting your code to run under
        'Python For Android (https://github.com/kivy/python-for-android)
        
        Are there any differences?
        --------------------------
        
        Exactly and ONLY the following C functions have been wrapped
        
        From fastpbkdf2:
        
        ::
        
            fastpbkdf2_hmac_sha1
            fastpbkdf2_hmac_sha256
            fastpbkdf2_hmac_sha512
        
        From bcrypt:
        
        ::
        
            bcrypt_kdf
        
        From scrypt:
        
        ::
        
            crypto_scrypt
        
        The following methods should be exactly equivalent to the corresponding
        methods in the existing python wrappers:
        
        ::
        
                ---------------------------------------------------------------
                Module.method                       Identical to
                ---------------------------------------------------------------
                multikdf.fastpbkdf2.pbkdf2_hmac     fastpbkdf2.pbkdf2_hmac
                multikdf.bcrypt.kdf                 bcrypt.kdf
                multikdf.scrypt.hash                scrypt.hash
                ---------------------------------------------------------------
        
        Test code
        =========
        
        See multikdf.test (test.py under the multikdf module directory)
        
        .. code:: python
        
                import os
                from .fastpbkdf2 import pbkdf2, algorithm as hash_algorithms
                from .bcrypt import bcrypt_kdf
                from .scrypt import scrypt_kdf
        
                min_passwd_len = 8
                max_passwd_len = 10
        
                min_pbkdf_rounds = 1000
                max_pbkdf_rounds = 5000
                step_pbkdf_rounds = 200
        
                min_bcrypt_rounds = 2
                max_bcrypt_rounds = 8
        
                min_scrypt_r = 7
                max_scrypt_r = 8
                min_scrypt_p = 1
                max_scrypt_p = 2
                min_scrypt_n = 13
                max_scrypt_n = 14
        
                def test_pbkdf2(s):
                    for l in range(min_passwd_len, max_passwd_len + 1):
                        i = os.urandom(l)
                        for r in range(min_pbkdf_rounds,
                                       max_pbkdf_rounds + 1,
                                       step_pbkdf_rounds):
                            for h in hash_algorithms.keys():
                                print('Testing pbkdf2: l=%d, r=%d, h=%s' % (l, r, h))
                                pbkdf2(i, s, r=r, kl=kl, h=h)
        
                def test_bcrypt(s):
                    for l in range(min_passwd_len, max_passwd_len + 1):
                        i = os.urandom(l)
                        for r in range(min_bcrypt_rounds, max_bcrypt_rounds + 1):
                            print('Testing bcrypt: l=%d, r=%d' % (l, r))
                            bcrypt_kdf(i, s, r=r, kl=kl)
        
                def test_scrypt(s):
                    for l in range(min_passwd_len, max_passwd_len + 1):
                        i = os.urandom(l)
                        for r in range(min_scrypt_r, max_scrypt_r + 1):
                            for p in range(min_scrypt_p, max_scrypt_p + 1):
                                for n in range(min_scrypt_n, max_scrypt_n + 1):
                                    print('Testing scrypt: l=%d, r=%d, p=%d, n=%d' % (
                                        l, r, p, n))
                                    scrypt_kdf(i, s, r=r, p=p, n=n, kl=kl)
        
                s = os.urandom(64)
                kl = 64
        
                test_pbkdf2(s)
                test_bcrypt(s)
                test_scrypt(s)
        
        INSTALLING:
        ===========
        
        From github directly using pip:
        
        ::
        
            pip install 'git+https://github.com/sundarnagarajan/pymultikdf.git'
        
        From github after downloading / cloning:
        
        ::
        
            python setup.py install
        
        From pypi:
        
        ::
        
            pip install multikdf
        
        LICENSE
        =======
        
        The files under multikdf/c/fastpbkdf2 are from ctz and are copied
        unchanged from https://github.com/ctz/fastpbkdf2.git These files under
        the terms of the CC0 1.0 Universal License - see the file named LICENSE
        under multikdf/c/fastpbkdf2
        
        The files under multikdf/c/py-bcrypt are from py-bcrypt (automatically
        exported from code.google.com/p/py-bcrypt) and imported unchanged. These
        files under the terms of the ISC/BSD licence. See the file named LICENSE
        under multikdf/c/py-bcrypt
        
        The files under multikdf/c/scrypt are from Tarsnap and are copied
        unchanged from https://github.com/Tarsnap/scrypt.git The files under
        multikdf/c/scrypt/lib are licensed under the terms of the 2-clause BSD
        license. See the file named README.md under the directory
        multikdf/c/scrypt/lib.
        
        The files under multikdf/c/scrypt/libcperciva are licensed under the
        terms of the license specified in the file
        multikdf/c/scrypt/libcperciva/COPYRIGHT.
        
        All remaining files in this package are licensed under the GNU General
        Public License version 3 or (at your option) any later version. See the
        file LICENSE-GPLv3.txt for details of the GNU General Public License
        version 3.
        
        Documentation (pydoc)
        =====================
        
        Package multikdf
        ----------------
        
        PACKAGE CONTENTS
        ~~~~~~~~~~~~~~~~
        
        ::
        
            bcrypt
            fastpbkdf2
            libmultikdf
            scrypt
            test
        
        FUNCTIONS
        ~~~~~~~~~
        
        ::
        
            getbuf(l)
        
        multikdf.fastpbkdf2
        -------------------
        
        FUNCTIONS
        ~~~~~~~~~
        
        ::
        
            pbkdf2(i, s, r=1000, kl=64, h='SHA512')
                i-->bytes: input data (password etc)
                s-->bytes: salt
                r-->int: rounds
                kl-->int: desired key length in bytes
                h-->str: hash function (name)
                
                Returns-->bytes:
        
            pbkdf2_hmac(h, i, s, r, kl=None)
                Should be identical to original fastpbkdf2.pbkdf2_hmac
                h-->str: hash function (name)
                i-->bytes: input data (password etc)
                s-->bytes: salt
                r-->int: rounds
                kl-->int: desired key length in bytes
                
                Returns-->bytes:
        
        DATA
        ~~~~
        
        ::
        
            algorithm = {'sha1': None, 'sha256': None, 'sha512': None}
        
        multikdf.bcrypt
        ---------------
        
        FUNCTIONS
        ~~~~~~~~~
        
        ::
        
            bcrypt_kdf(i, s, r=10, kl=64)
                i-->bytes: input data (password etc)
                s-->bytes: salt (os.urandom)
                r-->int: rounds
                kl-->int: desired key length in bytes
                Returns-->bytes:
                
                (rounds * PerSec) = Machine-specific constant
        
            kdf(password, salt, desired_key_bytes, rounds)
                Should be identical to original bcrypt.kdf
                password-->bytes: input data (password etc)
                salt-->bytes: salt
                desired_key_bytes-->int: desired key length in bytes
                rounds-->int: rounds
                
                Returns-->bytes:
        
        multikdf.scrypt
        ---------------
        
        FUNCTIONS
        ~~~~~~~~~
        
        ::
        
            hash(i, s, N=16384, r=8, p=1, buflen=64)
                Should be identical to scrypt.hash
                i-->bytes: input data (password etc)
                s-->bytes: salt
                N-->int: General work factor. Should be a power of 2
                         if N < 2, it is set to 2. Defaults to 16384
                r-->int: Memory cost - defaults to 8
                p-->int: Compuation (parallelization) cost - defaults to 1
                buflen-->int: Desired key length in bytes
                Returns-->bytes:
        
            scrypt_kdf(i, s, r=8, p=1, n=14, kl=64)
                i-->bytes: input data (password etc)
                s-->bytes: salt (os.urandom)
                r-->int: Memory cost - defaults to 8
                p-->int: Compuation (parallelization) cost - defaults to 1
                n-->int: General work factor. passed to scrypt as 2^n
                         if n < 1, it is set to 1. Defaults to 14 (scrypt n=16384)
                Returns-->bytes:
                
                (r * p) should be < 2^30
                see pydoc scrypt.hash
                
                (2^n) * r * p * PerSec = Machine-specific constant
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
