path: root/passlib/utils/__init__.py

"""passlib utility functions"""
#=================================================================================
#imports
#=================================================================================
#core
from base64 import b64encode, b64decode
from codecs import lookup as _lookup_codec
##from functools import update_wrapper
from hashlib import sha256
import logging; log = logging.getLogger(__name__)
from math import log as logb
import os
import sys
import random
import stringprep
import time
import unicodedata
from warnings import warn
#site
#pkg
from passlib.utils.compat import irange, PY3, sys_bits, unicode, bytes, u, b, \
                                 _add_doc
#local
__all__ = [
    #decorators
    "classproperty",
##    "memoized_class_property",
##    "abstractmethod",
##    "abstractclassmethod",

    #byte compat aliases
    'bytes', 'native_str',

    #misc
    'os_crypt',

    #tests
    'is_crypt_handler',
    'is_crypt_context',

    #bytes<->unicode
    'to_bytes',
    'to_unicode',
    'to_native_str',
    'is_same_codec',

    # string manipulation
    'consteq',
    'saslprep',

    #byte manipulation
    "xor_bytes",

    #random
    'rng',
    'getrandbytes',
    'getrandstr',

    #constants
    'pypy_vm', 'jython_vm',
    'unix_crypt_schemes',
]

#=================================================================================
#constants
#=================================================================================

#: detect what we're running on
pypy_vm = hasattr(sys, "pypy_version_info")
jython_vm = sys.platform.startswith('java')

#: list of names of hashes found in unix crypt implementations...
unix_crypt_schemes = [
    "sha512_crypt", "sha256_crypt",
    "sha1_crypt", "bcrypt",
    "md5_crypt",
    "bsdi_crypt", "des_crypt"
    ]

#: list of rounds_cost constants
rounds_cost_values = [ "linear", "log2" ]

#: special byte string containing all possible byte values, used in a few places.
#XXX: treated as singleton by some of the code for efficiency.
if PY3:
    ALL_BYTE_VALUES = bytes(irange(256))
else:
    ALL_BYTE_VALUES = ''.join(chr(x) for x in irange(256))

#NOTE: Undef is only used in *one* place now, could just remove it
class UndefType(object):
    _undef = None

    def __new__(cls):
        if cls._undef is None:
            cls._undef = object.__new__(cls)
        return cls._undef

    def __repr__(self):
        return '<Undef>'

    def __eq__(self, other):
        return False

    def __ne__(self, other):
        return True

#: singleton used as default kwd value in some functions, indicating "NO VALUE"
Undef = UndefType()

NoneType = type(None)

class MissingBackendError(RuntimeError):
    """Error raised if multi-backend handler has no available backends;
    or if specifically requested backend is not available.

    :exc:`!MissingBackendError` derives
    from :exc:`RuntimeError`, since this usually indicates
    lack of an external library or OS feature.

    This is primarily used by handlers which derive
    from :class:`~passlib.utils.handlers.HasManyBackends`.
    """

class PasslibPolicyWarning(UserWarning):
    """Warning issued when non-fatal issue is found in policy configuration.

    This occurs primarily in one of two cases:

    * the policy contains rounds limits which exceed the hard limits
      imposed by the underlying algorithm.
    * an explicit rounds value was provided which exceeds the limits
      imposed by the policy.

    In both of these cases, the code will perform correctly & securely;
    but the warning is issued as a sign the configuration may need updating.
    """

#==========================================================
#bytes compat aliases - bytes, native_str, b()
#==========================================================

# NOTE: most of this has been moved to compat()

native_str = str

#=================================================================================
#os crypt helpers
#=================================================================================

#expose crypt function as 'os_crypt', set to None if not available.
try:
    from crypt import crypt as os_crypt
except ImportError: #pragma: no cover
    safe_os_crypt = os_crypt = None
else:
    # NOTE: see docstring below as to why we're wrapping os_crypt()
    if PY3:
        def safe_os_crypt(secret, hash):
            if isinstance(secret, bytes):
                # decode secret using utf-8, and make sure it re-encodes to
                # match the original - otherwise the call to os_crypt()
                # will encode the wrong password.
                orig = secret
                try:
                    secret = secret.decode("utf-8")
                except UnicodeDecodeError:
                    return False, None
                if secret.encode("utf-8") != orig:
                    # just in case original encoding wouldn't be reproduced
                    # during call to os_crypt. not sure if/how this could
                    # happen, but being paranoid.
                    warn("utf-8 password didn't re-encode correctly!")
                    return False, None
            result = os_crypt(secret, hash)
            return (result is not None), result
    else:
        def safe_os_crypt(secret, hash):
            # NOTE: this guard logic is designed purely to match py3 behavior,
            # with the exception that it accepts secret as bytes.
            if isinstance(secret, unicode):
                secret = secret.encode("utf-8")
            if isinstance(hash, bytes):
                raise TypeError("hash must be unicode")
            else:
                hash = hash.encode("utf-8")
            result = os_crypt(secret, hash)
            if result is None:
                return False, None
            else:
                return True, result.decode("ascii")

    _add_doc(safe_os_crypt, """wrapper around stdlib's crypt.

        Python 3's crypt behaves slightly differently from Python 2's crypt.
        for one, it takes in and returns unicode.
        internally, it converts to utf-8 before hashing.
        Annoyingly, *there is no way to call it using bytes*.
        thus, it can't be used to hash non-ascii passwords
        using any encoding but utf-8 (eg, using latin-1).

        This wrapper attempts to gloss over all those issues:
        Under Python 2, it accept passwords as unicode or bytes,
        accepts hashes only as unicode, and always returns unicode.
        Under Python 3, it will signal that it cannot hash a password
        if provided as non-utf-8 bytes, but otherwise behave the same as crypt.

        :arg secret: password as bytes or unicode
        :arg hash: hash/salt as unicode
        :returns:
            ``(False, None)`` if the password can't be hashed (3.x only),
            or ``(True, result: unicode)`` otherwise.
        """)

#=================================================================================
#decorators and meta helpers
#=================================================================================
class classproperty(object):
    """Function decorator which acts like a combination of classmethod+property (limited to read-only properties)"""

    def __init__(self, func):
        self.im_func = func

    def __get__(self, obj, cls):
        return self.im_func(cls)

    @property
    def __func__(self):
        "py3 compatible alias"
        return self.im_func

#works but not used
##class memoized_class_property(object):
##    """function decorator which calls function as classmethod, and replaces itself with result for current and all future invocations"""
##    def __init__(self, func):
##        self.im_func = func
##
##    def __get__(self, obj, cls):
##        func = self.im_func
##        value = func(cls)
##        setattr(cls, func.__name__, value)
##        return value
##
##    @property
##    def __func__(self):
##        "py3 compatible alias"

#works but not used...
##def abstractmethod(func):
##    """Method decorator which indicates this is a placeholder method which
##    should be overridden by subclass.
##
##    If called directly, this method will raise an :exc:`NotImplementedError`.
##    """
##    msg = "object %(self)r method %(name)r is abstract, and must be subclassed"
##    def wrapper(self, *args, **kwds):
##        text = msg % dict(self=self, name=wrapper.__name__)
##        raise NotImplementedError(text)
##    update_wrapper(wrapper, func)
##    return wrapper

#works but not used...
##def abstractclassmethod(func):
##    """Class Method decorator which indicates this is a placeholder method which
##    should be overridden by subclass, and must be a classmethod.
##
##    If called directly, this method will raise an :exc:`NotImplementedError`.
##    """
##    msg = "class %(cls)r method %(name)r is abstract, and must be subclassed"
##    def wrapper(cls, *args, **kwds):
##        text = msg % dict(cls=cls, name=wrapper.__name__)
##        raise NotImplementedError(text)
##    update_wrapper(wrapper, func)
##    return classmethod(wrapper)

#==========================================================
#protocol helpers
#==========================================================
def is_crypt_handler(obj):
    "check if object follows the :ref:`password-hash-api`"
    return all(hasattr(obj, name) for name in (
        "name",
        "setting_kwds", "context_kwds",
        "genconfig", "genhash",
        "verify", "encrypt", "identify",
        ))

def is_crypt_context(obj):
    "check if object appears to be a :class:`~passlib.context.CryptContext` instance"
    return all(hasattr(obj, name) for name in (
        "hash_needs_update",
        "genconfig", "genhash",
        "verify", "encrypt", "identify",
        ))

##def has_many_backends(handler):
##    "check if handler provides multiple baceknds"
##    #NOTE: should also provide get_backend(), .has_backend(), and .backends attr
##    return hasattr(handler, "set_backend")

def has_rounds_info(handler):
    "check if handler provides the optional :ref:`rounds information <optional-rounds-attributes>` attributes"
    return 'rounds' in handler.setting_kwds and getattr(handler, "min_rounds", None) is not None

def has_salt_info(handler):
    "check if handler provides the optional :ref:`salt information <optional-salt-attributes>` attributes"
    return 'salt' in handler.setting_kwds and getattr(handler, "min_salt_size", None) is not None

##def has_raw_salt(handler):
##    "check if handler takes in encoded salt as unicode (False), or decoded salt as bytes (True)"
##    sc = getattr(handler, "salt_chars", None)
##    if sc is None:
##        return None
##    elif isinstance(sc, unicode):
##        return False
##    elif isinstance(sc, bytes):
##        return True
##    else:
##        raise TypeError("handler.salt_chars must be None/unicode/bytes")

#==========================================================
#bytes <-> unicode conversion helpers
#==========================================================

def to_bytes(source, encoding="utf-8", source_encoding=None, errname="value"):
    """helper to encoding unicode -> bytes

    this function takes in a ``source`` string.
    if unicode, encodes it using the specified ``encoding``.
    if bytes, returns unchanged - unless ``source_encoding``
    is specified, in which case the bytes are transcoded
    if and only if the source encoding doesn't match
    the desired encoding.
    all other types result in a :exc:`TypeError`.

    :arg source: source bytes/unicode to process
    :arg encoding: target character encoding or ``None``.
    :param source_encoding: optional source encoding
    :param errname: optional name of variable/noun to reference when raising errors

    :raises TypeError: if unicode encountered but ``encoding=None`` specified;
                       or if source is not unicode or bytes.

    :returns: bytes object

    .. note::

        if ``encoding`` is set to ``None``, then unicode strings
        will be rejected, and only byte strings will be allowed through.
    """
    if isinstance(source, bytes):
        if source_encoding and encoding and \
                not is_same_codec(source_encoding, encoding):
            return source.decode(source_encoding).encode(encoding)
        else:
            return source
    elif not encoding:
        raise TypeError("%s must be bytes, not %s" % (errname, type(source)))
    elif isinstance(source, unicode):
        return source.encode(encoding)
    elif source_encoding:
        raise TypeError("%s must be unicode or %s-encoded bytes, not %s" %
                        (errname, source_encoding, type(source)))
    else:
        raise TypeError("%s must be unicode or bytes, not %s" % (errname, type(source)))

def to_unicode(source, source_encoding="utf-8", errname="value"):
    """take in unicode or bytes, return unicode

    if bytes provided, decodes using specified encoding.
    leaves unicode alone.

    :raises TypeError: if source is not unicode or bytes.

    :arg source: source bytes/unicode to process
    :arg source_encoding: encoding to use when decoding bytes instances
    :param errname: optional name of variable/noun to reference when raising errors

    :returns: unicode object
    """
    if isinstance(source, unicode):
        return source
    elif not source_encoding:
        raise TypeError("%s must be unicode, not %s" % (errname, type(source)))
    elif isinstance(source, bytes):
        return source.decode(source_encoding)
    else:
        raise TypeError("%s must be unicode or %s-encoded bytes, not %s" %
                        (errname, source_encoding, type(source)))

if PY3:
    def to_native_str(source, encoding="utf-8", errname="value"):
        assert encoding
        if isinstance(source, bytes):
            return source.decode(encoding)
        elif isinstance(source, unicode):
            return source
        else:
            raise TypeError("%s must be unicode or bytes, not %s" %
                            (errname, type(source)))
else:
    def to_native_str(source, encoding="utf-8", errname="value"):
        assert encoding
        if isinstance(source, bytes):
            return source
        elif isinstance(source, unicode):
            return source.encode(encoding)
        else:
            raise TypeError("%s must be unicode or bytes, not %s" %
                            (errname, type(source)))

_add_doc(to_native_str, """take in unicode or bytes, return native string

    python 2: encodes unicode using specified encoding, leaves bytes alone.
    python 3: decodes bytes using specified encoding, leaves unicode alone.

    :raises TypeError: if source is not unicode or bytes.

    :arg source: source bytes/unicode to process
    :arg encoding: encoding to use when encoding unicode / decoding bytes
    :param errname: optional name of variable/noun to reference when raising errors

    :returns: :class:`str` instance
    """)

def to_hash_str(hash, encoding="ascii", errname="hash"):
    "given hash string as bytes or unicode; normalize according to hash policy"
    #NOTE: for now, policy is ascii-bytes under py2, unicode under py3.
    #      but plan to make flag allowing apps to enable unicode behavior under py2.
    return to_native_str(hash, encoding, errname)

#--------------------------------------------------
#support utils
#--------------------------------------------------
def is_same_codec(left, right):
    "check if two codecs names are aliases for same codec"
    if left == right:
        return True
    if not (left and right):
        return False
    return _lookup_codec(left).name == _lookup_codec(right).name

_B80 = 128 if PY3 else b('\x80')
_U80 = u('\x80')
def is_ascii_safe(source):
    "check if source (bytes or unicode) contains only 7-bit ascii"
    r = _B80 if isinstance(source, bytes) else _U80
    return all(c < r for c in source)

#=================================================================================
#string helpers
#=================================================================================
UEMPTY = u("")
USPACE = u(" ")
ujoin = UEMPTY.join

def consteq(left, right):
    """check two strings/bytes for equality, taking constant time relative
    to the size of the righthand input.

    The purpose of this function is to aid in preventing timing attacks
    during digest comparisons (see the 1.6 changelog
    :ref:`entry <consteq-issue>` for more details).
    """
    # NOTE:
    # This function attempts to take an amount of time proportional
    # to ``THETA(len(right))``. The main loop is designed so that timing attacks
    # against this function should reveal nothing about how much (or which
    # parts) of the two inputs match.
    #
    # Why ``THETA(len(right))``?
    # Assuming the attacker controls one of the two inputs, padding to
    # the largest input or trimming to the smallest input both allow
    # a timing attack to reveal the length of the other input.
    # However, by fixing the runtime to be proportional to the right input:
    # * If the right value is attacker controlled, the runtime is proportional
    #   to their input, giving nothing away about the left value's size.
    # * If the left value is attacker controlled, the runtime is constant
    #   relative to their input, giving nothing away about the right value's size.

    # validate types
    if isinstance(left, unicode):
        if not isinstance(right, unicode):
            raise TypeError("inputs must be both unicode or bytes")
        is_py3_bytes = False
    elif isinstance(left, bytes):
        if not isinstance(right, bytes):
            raise TypeError("inputs must be both unicode or bytes")
        is_py3_bytes = PY3
    else:
        raise TypeError("inputs must be both unicode or bytes")

    # do size comparison.
    # NOTE: the double-if construction below is done deliberately, to ensure
    # the same number of operations (including branches) is performed regardless
    # of whether left & right are the same size.
    same = (len(left) == len(right))
    if same:
        # if sizes are the same, setup loop to perform actual check of contents.
        tmp = left
        result = 0
    if not same:
        # if sizes aren't the same, set 'result' so equality will fail regardless
        # of contents. then, to ensure we do exactly 'len(right)' iterations
        # of the loop, just compare 'right' against itself.
        tmp = right
        result = 1

    # run constant-time string comparision
    if is_py3_bytes:
        for l,r in zip(tmp, right):
            result |= l ^ r
    else:
        for l,r in zip(tmp, right):
            result |= ord(l) ^ ord(r)
    return result == 0

def splitcomma(source, sep=","):
    """split comma-separated string into list of elements,
    stripping whitespace and discarding empty elements.

    .. deprecated:: 1.6, will be removed in 1.7
    """
    warn("splitcomma() is deprecated, will be removed in passlib 1.7",
         DeprecationWarning, stacklevel=2)
    return [
        elem.strip()
        for elem in source.split(sep)
        if elem.strip()
    ]

def saslprep(source, errname="value"):
    """normalizes unicode string using SASLPrep stringprep profile.

    The SASLPrep profile is defined in :rfc:`4013`.
    It provides a uniform scheme for normalizing unicode usernames
    and passwords before performing byte-value sensitive operations
    such as hashing. Among other things, it normalizes diacritic
    representations, removes non-printing characters, and forbids
    invalid characters such as ``\n``.

    :arg source:
        unicode string to normalize & validate

    :param errname:
        optionally override noun used to refer to source in error messages,
        defaults to ``value``; mainly useful to make caller's error
        messages make more sense.

    :raises ValueError:
        if any characters forbidden by the SASLPrep profile are encountered.

    :returns:
        normalized unicode string
    """
    # saslprep - http://tools.ietf.org/html/rfc4013
    # stringprep - http://tools.ietf.org/html/rfc3454
    #              http://docs.python.org/library/stringprep.html

    # validate type
    if not isinstance(source, unicode):
        raise TypeError("input must be unicode string, not %s" %
                        (type(source),))

    # mapping stage
    #   - map non-ascii spaces to U+0020 (stringprep C.1.2)
    #   - strip 'commonly mapped to nothing' chars (stringprep B.1)
    in_table_c12 = stringprep.in_table_c12
    in_table_b1 = stringprep.in_table_b1
    data = ujoin(
        USPACE if in_table_c12(c) else c
        for c in source
        if not in_table_b1(c)
        )

    # normalize to KC form
    data = unicodedata.normalize('NFKC', data)
    if not data:
        return UEMPTY

    # check for invalid bi-directional strings.
    # stringprep requires the following:
    #   - chars in C.8 must be prohibited.
    #   - if any R/AL chars in string:
    #       - no L chars allowed in string
    #       - first and last must be R/AL chars
    # this checks if start/end are R/AL chars. if so, prohibited loop
    # will forbid all L chars. if not, prohibited loop will forbid all
    # R/AL chars instead. in both cases, prohibited loop takes care of C.8.
    is_ral_char = stringprep.in_table_d1
    if is_ral_char(data[0]):
        if not is_ral_char(data[-1]):
            raise ValueError("malformed bidi sequence in " + errname)
        # forbid L chars within R/AL sequence.
        is_forbidden_bidi_char = stringprep.in_table_d2
    else:
        # forbid R/AL chars if start not setup correctly; L chars allowed.
        is_forbidden_bidi_char = is_ral_char

    # check for prohibited output - stringprep tables A.1, B.1, C.1.2, C.2 - C.9
    in_table_a1 = stringprep.in_table_a1
    in_table_c21_c22 = stringprep.in_table_c21_c22
    in_table_c3 = stringprep.in_table_c3
    in_table_c4 = stringprep.in_table_c4
    in_table_c5 = stringprep.in_table_c5
    in_table_c6 = stringprep.in_table_c6
    in_table_c7 = stringprep.in_table_c7
    in_table_c8 = stringprep.in_table_c8
    in_table_c9 = stringprep.in_table_c9
    for c in data:
        # check for this mapping stage should have removed
        assert not in_table_b1(c), "failed to strip B.1 in mapping stage"
        assert not in_table_c12(c), "failed to replace C.1.2 in mapping stage"

        # check for forbidden chars
        if in_table_a1(c):
            raise ValueError("unassigned code points forbidden in " + errname)
        if in_table_c21_c22(c):
            raise ValueError("control characters forbidden in " + errname)
        if in_table_c3(c):
            raise ValueError("private use characters forbidden in " + errname)
        if in_table_c4(c):
            raise ValueError("non-char code points forbidden in " + errname)
        if in_table_c5(c):
            raise ValueError("surrogate codes forbidden in " + errname)
        if in_table_c6(c):
            raise ValueError("non-plaintext chars forbidden in " + errname)
        if in_table_c7(c):
            # XXX: should these have been caught by normalize?
            # if so, should change this to an assert
            raise ValueError("non-canonical chars forbidden in " + errname)
        if in_table_c8(c):
            raise ValueError("display-modifying / deprecated chars "
                             "forbidden in" + errname)
        if in_table_c9(c):
            raise ValueError("tagged characters forbidden in " + errname)

        # do bidi constraint check chosen by bidi init, above
        if is_forbidden_bidi_char(c):
            raise ValueError("forbidden bidi character in " + errname)

    return data

#==========================================================
#bytes helpers
#==========================================================

#some common constants / aliases
BEMPTY = b('')

#helpers for joining / extracting elements
bjoin = BEMPTY.join

#def bjoin_elems(elems):
#    """takes series of bytes elements, returns bytes.
#
#    elem should be result of bytes[x].
#    this is another bytes instance under py2,
#    but it int under py3.
#
#    returns bytes.
#
#    this is bytes() constructor under py3,
#    but b"".join() under py2.
#    """
#    if PY3:
#        return bytes(elems)
#    else:
#        return bjoin(elems)
#
#for efficiency, don't bother with above wrapper...
if PY3:
    bjoin_elems = bytes
else:
    bjoin_elems = bjoin

#def bord(elem):
#    """takes bytes element, returns integer.
#
#    elem should be result of bytes[x].
#    this is another bytes instance under py2,
#    but it int under py3.
#
#    returns int in range(0,256).
#
#    this is ord() under py2, and noop under py3.
#    """
#    if PY3:
#        assert isinstance(elem, int)
#        return elem
#    else:
#        assert isinstance(elem, bytes)
#        return ord(elem)
#
#for efficiency, don't bother with above wrapper...
if PY3:
    def bord(elem):
        return elem
else:
    bord = ord

if PY3:
    bjoin_ints = bytes
else:
    def bjoin_ints(values):
        return bjoin(chr(v) for v in values)

def render_bytes(source, *args):
    """helper for using formatting operator with bytes.

    this function is motivated by the fact that
    :class:`bytes` instances do not support % or {} formatting under python 3.
    this function is an attempt to provide a replacement
    that will work uniformly under python 2 & 3.

    it converts everything to unicode (including bytes arguments),
    then encodes the result to latin-1.
    """
    if isinstance(source, bytes):
        source = source.decode("latin-1")
    def adapt(arg):
        if isinstance(arg, bytes):
            return arg.decode("latin-1")
        return arg
    result = source % tuple(adapt(arg) for arg in args)
    return result.encode("latin-1")

#=================================================================================
#numeric helpers
#=================================================================================

##def int_to_bytes(value, count=None, order="big"):
##    """encode a integer into a string of bytes
##
##    :arg value: the integer
##    :arg count: optional number of bytes to expose, uses minimum needed if count not specified
##    :param order: the byte ordering; "big" (the default), "little", or "native"
##
##    :raises ValueError:
##        * if count specified and integer too large to fit.
##        * if integer is negative
##
##    :returns:
##        bytes encoding integer
##    """
##
##
##def bytes_to_int(value, order="big"):
##    """decode a byte string into an integer representation of it's binary value.
##
##    :arg value: the string to decode.
##    :param order: the byte ordering; "big" (the default), "little", or "native"
##
##    :returns: the decoded positive integer.
##    """
##    if not value:
##        return 0
##    if order == "native":
##        order = sys.byteorder
##    if order == "little":
##        value = reversed(value)
##    out = 0
##    for v in value:
##        out = (out<<8) | ord(v)
##    return out

def bytes_to_int(value):
    "decode string of bytes as single big-endian integer"
    out = 0
    for v in value:
        out = (out<<8) | bord(v)
    return out

def int_to_bytes(value, count):
    "encodes integer into single big-endian byte string"
    assert value < (1<<(8*count)), "value too large for %d bytes: %d" % (count, value)
    return bjoin_ints(
        ((value>>s) & 0xff)
        for s in irange(8*count-8,-8,-8)
    )

if PY3:
    def xor_bytes(left, right):
        "perform bitwise-xor of two byte-strings"
        return bytes(l ^ r for l, r in zip(left, right))
else:
    def xor_bytes(left, right):
        "perform bitwise-xor of two byte-strings"
        return bjoin(chr(ord(l) ^ ord(r)) for l, r in zip(left, right))

#=================================================================================
#alt base64 encoding
#=================================================================================
_A64_ALTCHARS = b("./")
_A64_STRIP = b("=\n")
_A64_PAD1 = b("=")
_A64_PAD2 = b("==")

def adapted_b64_encode(data):
    """encode using variant of base64

    the output of this function is identical to b64_encode,
    except that it uses ``.`` instead of ``+``,
    and omits trailing padding ``=`` and whitepsace.

    it is primarily used for by passlib's custom pbkdf2 hashes.
    """
    return b64encode(data, _A64_ALTCHARS).strip(_A64_STRIP)

def adapted_b64_decode(data, sixthree="."):
    """decode using variant of base64

    the input of this function is identical to b64_decode,
    except that it uses ``.`` instead of ``+``,
    and should not include trailing padding ``=`` or whitespace.

    it is primarily used for by passlib's custom pbkdf2 hashes.
    """
    off = len(data) % 4
    if off == 0:
        return b64decode(data, _A64_ALTCHARS)
    elif off == 1:
        raise ValueError("invalid bas64 input")
    elif off == 2:
        return b64decode(data + _A64_PAD2, _A64_ALTCHARS)
    else:
        return b64decode(data + _A64_PAD1, _A64_ALTCHARS)

#=================================================================================
#randomness
#=================================================================================

#-----------------------------------------------------------------------
# setup rng for generating salts
#-----------------------------------------------------------------------

#NOTE:
# generating salts (eg h64_gensalt, below) doesn't require cryptographically
# strong randomness. it just requires enough range of possible outputs
# that making a rainbow table is too costly.
# so python's builtin merseen twister prng is used, but seeded each time
# this module is imported, using a couple of minor entropy sources.

try:
    os.urandom(1)
    has_urandom = True
except NotImplementedError: #pragma: no cover
    has_urandom = False

def genseed(value=None):
    "generate prng seed value from system resources"
    #if value is rng, extract a bunch of bits from it's state
    if hasattr(value, "getrandbits"):
        value = value.getrandbits(256)
    text = u("%s %s %s %.15f %s") % (
        value,
            #if user specified a seed value (eg current rng state), mix it in

        os.getpid() if hasattr(os, "getpid") else None,
            #add current process id
            #NOTE: not available in some environments, eg GAE

        id(object()),
            #id of a freshly created object.
            #(at least 2 bytes of which should be hard to predict)

        time.time(),
            #the current time, to whatever precision os uses

        os.urandom(16).decode("latin-1") if has_urandom else 0,
            #if urandom available, might as well mix some bytes in.
        )
    #hash it all up and return it as int/long
    return int(sha256(text.encode("utf-8")).hexdigest(), 16)

if has_urandom:
    rng = random.SystemRandom()
else: #pragma: no cover
    #NOTE: to reseed - rng.seed(genseed(rng))
    rng = random.Random(genseed())

#-----------------------------------------------------------------------
# some rng helpers
#-----------------------------------------------------------------------
def getrandbytes(rng, count):
    """return byte-string containing *count* number of randomly generated bytes, using specified rng"""
    #NOTE: would be nice if this was present in stdlib Random class

    ###just in case rng provides this...
    ##meth = getattr(rng, "getrandbytes", None)
    ##if meth:
    ##    return meth(count)

    if not count:
        return BEMPTY
    def helper():
        #XXX: break into chunks for large number of bits?
        value = rng.getrandbits(count<<3)
        i = 0
        while i < count:
            yield value & 0xff
            value >>= 3
            i += 1
    return bjoin_ints(helper())

def getrandstr(rng, charset, count):
    """return string containing *count* number of chars/bytes, whose elements are drawn from specified charset, using specified rng"""
    #check alphabet & count
    if count < 0:
        raise ValueError("count must be >= 0")
    letters = len(charset)
    if letters == 0:
        raise ValueError("alphabet must not be empty")
    if letters == 1:
        return charset * count

    #get random value, and write out to buffer
    def helper():
        #XXX: break into chunks for large number of letters?
        value = rng.randrange(0, letters**count)
        i = 0
        while i < count:
            yield charset[value % letters]
            value //= letters
            i += 1

    if isinstance(charset, unicode):
        return ujoin(helper())
    else:
        return bjoin_elems(helper())

def generate_password(size=10, charset='2346789ABCDEFGHJKMNPQRTUVWXYZabcdefghjkmnpqrstuvwxyz'):
    """generate random password using given length & chars

    :param size:
        size of password.

    :param charset:
        optional string specified set of characters to draw from.

        the default charset contains all normal alphanumeric characters,
        except for the characters ``1IiLl0OoS5``, which were omitted
        due to their visual similarity.

    :returns: randomly generated password.
    """
    return getrandstr(rng, charset, size)

#=================================================================================
#eof
#=================================================================================