[Python-checkins] cpython (merge default -> default): Automated merge with ssh://hg.python.org/cpython

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
