Automated merge with ssh://hg.python.org/cpython
This commit is contained in:
commit
5562563dd4
|
@ -88,7 +88,7 @@ hard-to-guess URLs, and similar.
|
|||
.. function:: token_urlsafe([nbytes=None])
|
||||
|
||||
Return a random URL-safe text string, containing *nbytes* random
|
||||
bytes. The text is Base64 encoded, so on average, each byte results
|
||||
bytes. The text is Base64 encoded, so on average each byte results
|
||||
in approximately 1.3 characters. If *nbytes* is ``None`` or not
|
||||
supplied, a reasonable default is used.
|
||||
|
||||
|
@ -106,7 +106,7 @@ To be secure against
|
|||
tokens need to have sufficient randomness. Unfortunately, what is
|
||||
considered sufficient will necessarily increase as computers get more
|
||||
powerful and able to make more guesses in a shorter period. As of 2015,
|
||||
it is believed that 64 bytes (512 bits) of randomness is sufficient for
|
||||
it is believed that 32 bytes (256 bits) of randomness is sufficient for
|
||||
the typical use-case expected for the :mod:`secrets` module.
|
||||
|
||||
For those who want to manage their own token length, you can explicitly
|
||||
|
@ -129,8 +129,8 @@ Other functions
|
|||
.. function:: compare_digest(a, b)
|
||||
|
||||
Return ``True`` if strings *a* and *b* are equal, otherwise ``False``,
|
||||
in such a way as to redice the risk of
|
||||
`timing attacks <http://codahale.com/a-lesson-in-timing-attacks/>`_ .
|
||||
in such a way as to reduce the risk of
|
||||
`timing attacks <http://codahale.com/a-lesson-in-timing-attacks/>`_.
|
||||
See :func:`hmac.compare_digest` for additional details.
|
||||
|
||||
|
||||
|
@ -151,11 +151,10 @@ Generate an eight-character alphanumeric password:
|
|||
|
||||
.. note::
|
||||
|
||||
Applications should
|
||||
`not store passwords in a recoverable format <http://cwe.mitre.org/data/definitions/257.html>`_ ,
|
||||
whether plain text or encrypted. They should always be salted and
|
||||
hashed using a cryptographically-strong one-way (irreversible) hash
|
||||
function.
|
||||
Applications should not
|
||||
`store passwords in a recoverable format <http://cwe.mitre.org/data/definitions/257.html>`_,
|
||||
whether plain text or encrypted. They should be salted and hashed
|
||||
using a cryptographically-strong one-way (irreversible) hash function.
|
||||
|
||||
|
||||
Generate a ten-character alphanumeric password with at least one
|
||||
|
@ -174,7 +173,7 @@ three digits:
|
|||
break
|
||||
|
||||
|
||||
Generate an `XKCD-style passphrase <http://xkcd.com/936/>`_ :
|
||||
Generate an `XKCD-style passphrase <http://xkcd.com/936/>`_:
|
||||
|
||||
.. testcode::
|
||||
|
||||
|
|
106
Lib/secrets.py
106
Lib/secrets.py
|
@ -1,84 +1,9 @@
|
|||
"""Generate cryptographically strong pseudo-random numbers suitable for
|
||||
managing secrets such as account authentication, tokens, and similar.
|
||||
|
||||
See PEP 506 for more information.
|
||||
|
||||
https://www.python.org/dev/peps/pep-0506/
|
||||
|
||||
|
||||
Random numbers
|
||||
==============
|
||||
|
||||
The ``secrets`` module provides the following pseudo-random functions, based
|
||||
on SystemRandom, which in turn uses the most secure source of randomness your
|
||||
operating system provides.
|
||||
|
||||
|
||||
choice(sequence)
|
||||
Choose a random element from a non-empty sequence.
|
||||
|
||||
randbelow(n)
|
||||
Return a random int in the range [0, n).
|
||||
|
||||
randbits(k)
|
||||
Generates an int with k random bits.
|
||||
|
||||
SystemRandom
|
||||
Class for generating random numbers using sources provided by
|
||||
the operating system. See the ``random`` module for documentation.
|
||||
|
||||
|
||||
Token functions
|
||||
===============
|
||||
|
||||
The ``secrets`` module provides a number of functions for generating secure
|
||||
tokens, suitable for applications such as password resets, hard-to-guess
|
||||
URLs, and similar. All the ``token_*`` functions take an optional single
|
||||
argument specifying the number of bytes of randomness to use. If that is
|
||||
not given, or is ``None``, a reasonable default is used. That default is
|
||||
subject to change at any time, including during maintenance releases.
|
||||
|
||||
|
||||
token_bytes(nbytes=None)
|
||||
Return a random byte-string containing ``nbytes`` number of bytes.
|
||||
|
||||
>>> secrets.token_bytes(16) #doctest:+SKIP
|
||||
b'\\xebr\\x17D*t\\xae\\xd4\\xe3S\\xb6\\xe2\\xebP1\\x8b'
|
||||
|
||||
|
||||
token_hex(nbytes=None)
|
||||
Return a random text-string, in hexadecimal. The string has ``nbytes``
|
||||
random bytes, each byte converted to two hex digits.
|
||||
|
||||
>>> secrets.token_hex(16) #doctest:+SKIP
|
||||
'f9bf78b9a18ce6d46a0cd2b0b86df9da'
|
||||
|
||||
token_urlsafe(nbytes=None)
|
||||
Return a random URL-safe text-string, containing ``nbytes`` random
|
||||
bytes. On average, each byte results in approximately 1.3 characters
|
||||
in the final result.
|
||||
|
||||
>>> secrets.token_urlsafe(16) #doctest:+SKIP
|
||||
'Drmhze6EPcv0fN_81Bj-nA'
|
||||
|
||||
|
||||
(The examples above assume Python 3. In Python 2, byte-strings will display
|
||||
using regular quotes ``''`` with no prefix, and text-strings will have a
|
||||
``u`` prefix.)
|
||||
|
||||
|
||||
Other functions
|
||||
===============
|
||||
|
||||
compare_digest(a, b)
|
||||
Return True if strings a and b are equal, otherwise False.
|
||||
Performs the equality comparison in such a way as to reduce the
|
||||
risk of timing attacks.
|
||||
|
||||
See http://codahale.com/a-lesson-in-timing-attacks/ for a
|
||||
discussion on how timing attacks against ``==`` can reveal
|
||||
secrets from your application.
|
||||
|
||||
|
||||
"""
|
||||
|
||||
__all__ = ['choice', 'randbelow', 'randbits', 'SystemRandom',
|
||||
|
@ -100,18 +25,47 @@ randbits = _sysrand.getrandbits
|
|||
choice = _sysrand.choice
|
||||
|
||||
def randbelow(exclusive_upper_bound):
|
||||
"""Return a random int in the range [0, n)."""
|
||||
return _sysrand._randbelow(exclusive_upper_bound)
|
||||
|
||||
DEFAULT_ENTROPY = 32 # number of bytes to return by default
|
||||
|
||||
def token_bytes(nbytes=None):
|
||||
"""Return a random byte string containing *nbytes* bytes.
|
||||
|
||||
If *nbytes* is ``None`` or not supplied, a reasonable
|
||||
default is used.
|
||||
|
||||
>>> token_bytes(16) #doctest:+SKIP
|
||||
b'\\xebr\\x17D*t\\xae\\xd4\\xe3S\\xb6\\xe2\\xebP1\\x8b'
|
||||
|
||||
"""
|
||||
if nbytes is None:
|
||||
nbytes = DEFAULT_ENTROPY
|
||||
return os.urandom(nbytes)
|
||||
|
||||
def token_hex(nbytes=None):
|
||||
"""Return a random text string, in hexadecimal.
|
||||
|
||||
The string has *nbytes* random bytes, each byte converted to two
|
||||
hex digits. If *nbytes* is ``None`` or not supplied, a reasonable
|
||||
default is used.
|
||||
|
||||
>>> token_hex(16) #doctest:+SKIP
|
||||
'f9bf78b9a18ce6d46a0cd2b0b86df9da'
|
||||
|
||||
"""
|
||||
return binascii.hexlify(token_bytes(nbytes)).decode('ascii')
|
||||
|
||||
def token_urlsafe(nbytes=None):
|
||||
"""Return a random URL-safe text string, in Base64 encoding.
|
||||
|
||||
The string has *nbytes* random bytes. If *nbytes* is ``None``
|
||||
or not supplied, a reasonable default is used.
|
||||
|
||||
>>> token_urlsafe(16) #doctest:+SKIP
|
||||
'Drmhze6EPcv0fN_81Bj-nA'
|
||||
|
||||
"""
|
||||
tok = token_bytes(nbytes)
|
||||
return base64.urlsafe_b64encode(tok).rstrip(b'=').decode('ascii')
|
||||
|
|
Loading…
Reference in New Issue