# -*- test-case-name: twisted.test.test_randbytes -*-
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.

"""
Cryptographically secure random implementation, with fallback on normal random.
"""

from __future__ import division, absolute_import

import warnings, os, random, string

from twisted.python.compat import _PY3

getrandbits = getattr(random, 'getrandbits', None)

if _PY3:
_fromhex = bytes.fromhex
else:
def _fromhex(hexBytes):
return hexBytes.decode('hex')


class SecureRandomNotAvailable(RuntimeError):
"""
Exception raised when no secure random algorithm is found.
"""



class SourceNotAvailable(RuntimeError):
"""
Internal exception used when a specific random source is not available.
"""



class RandomFactory(object):
"""
Factory providing L{secureRandom} and L{insecureRandom} methods.

You shouldn't have to instantiate this class, use the module level
functions instead: it is an implementation detail and could be removed or
changed arbitrarily.
"""

# This variable is no longer used, and will eventually be removed.
randomSources = ()

getrandbits = getrandbits


def _osUrandom(self, nbytes):
"""
Wrapper around C{os.urandom} that cleanly manage its absence.
"""
try:
return os.urandom(nbytes)
except (AttributeError, NotImplementedError) as e:
raise SourceNotAvailable(e)


def secureRandom(self, nbytes, fallback=False):
"""
Return a number of secure random bytes.

@param nbytes: number of bytes to generate.
@type nbytes: C{int}
@param fallback: Whether the function should fallback on non-secure
random or not. Default to C{False}.
@type fallback: C{bool}

@return: a string of random bytes.
@rtype: C{str}
"""
try:
return self._osUrandom(nbytes)
except SourceNotAvailable:
pass

if fallback:
warnings.warn(
"urandom unavailable - "
"proceeding with non-cryptographically secure random source",
category=RuntimeWarning,
stacklevel=2)
return self.insecureRandom(nbytes)
else:
raise SecureRandomNotAvailable("No secure random source available")


def _randBits(self, nbytes):
"""
Wrapper around C{os.getrandbits}.
"""
if self.getrandbits is not None:
n = self.getrandbits(nbytes * 8)
hexBytes = ("%%0%dx" % (nbytes * 2)) % n
return _fromhex(hexBytes)
raise SourceNotAvailable("random.getrandbits is not available")


if _PY3:
_maketrans = bytes.maketrans
def _randModule(self, nbytes):
"""
Wrapper around the C{random} module.
"""
return b"".join([
bytes([random.choice(self._BYTES)]) for i in range(nbytes)])
else:
_maketrans = string.maketrans
def _randModule(self, nbytes):
"""
Wrapper around the C{random} module.
"""
return b"".join([
random.choice(self._BYTES) for i in range(nbytes)])

_BYTES = _maketrans(b'', b'')


def insecureRandom(self, nbytes):
"""
Return a number of non secure random bytes.

@param nbytes: number of bytes to generate.
@type nbytes: C{int}

@return: a string of random bytes.
@rtype: C{str}
"""
for src in ("_randBits", "_randModule"):
try:
return getattr(self, src)(nbytes)
except SourceNotAvailable:
pass



factory = RandomFactory()

secureRandom = factory.secureRandom

insecureRandom = factory.insecureRandom

del factory


__all__ = ["secureRandom", "insecureRandom", "SecureRandomNotAvailable"]