[Python-checkins] cpython (merge default -> default): Automated merge with ssh://hg.python.org/cpython
steven.daprano
python-checkins at python.org
Sat Apr 16 23:15:57 EDT 2016
https://hg.python.org/cpython/rev/19356c6d23b9
changeset: 101035:19356c6d23b9
parent: 101032:815a4ac67e68
parent: 101034:504ba147cbdf
user: Steven D'Aprano <steve at pearwood.info>
date: Sun Apr 17 13:14:48 2016 +1000
summary:
Automated merge with ssh://hg.python.org/cpython
files:
Doc/library/secrets.rst | 19 ++--
Lib/secrets.py | 106 +++++++--------------------
2 files changed, 39 insertions(+), 86 deletions(-)
diff --git a/Doc/library/secrets.rst b/Doc/library/secrets.rst
--- a/Doc/library/secrets.rst
+++ b/Doc/library/secrets.rst
@@ -88,7 +88,7 @@
.. 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 @@
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 @@
.. 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 @@
.. 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 @@
break
-Generate an `XKCD-style passphrase <http://xkcd.com/936/>`_ :
+Generate an `XKCD-style passphrase <http://xkcd.com/936/>`_:
.. testcode::
diff --git a/Lib/secrets.py b/Lib/secrets.py
--- a/Lib/secrets.py
+++ b/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 @@
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')
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list