Automated merge with ssh://hg.python.org/peps

pep-0506.txt

@@ -47,11 +47,11 @@ Rationale
 This proposal is motivated by concerns that Python's standard library
 makes it too easy for developers to inadvertently make serious security
 errors.  Theo de Raadt, the founder of OpenBSD, contacted Guido van Rossum
-and expressed some concern [1]_ about the use of MT for generating sensitive
+and expressed some concern [#]_ about the use of MT for generating sensitive
 information such as passwords, secure tokens, session keys and similar.
 
 Although the documentation for the ``random`` module explicitly states that
-the default is not suitable for security purposes [2]_, it is strongly
+the default is not suitable for security purposes [#]_, it is strongly
 believed that this warning may be missed, ignored or misunderstood by
 many Python developers.  In particular:
 
@@ -65,21 +65,21 @@ many Python developers.  In particular:
   (or learned techniques) from websites which don't offer best
   practises.
 
-The first [3]_ hit when searching for "python how to generate passwords" on
+The first [#]_ hit when searching for "python how to generate passwords" on
 Google is a tutorial that uses the default functions from the ``random``
-module [4]_.  Although it is not intended for use in web applications, it is
+module [#]_.  Although it is not intended for use in web applications, it is
 likely that similar techniques find themselves used in that situation.
 The second hit is to a StackOverflow question about generating
-passwords [5]_.  Most of the answers given, including the accepted one, use
+passwords [#]_.  Most of the answers given, including the accepted one, use
 the default functions.  When one user warned that the default could be
-easily compromised, they were told "I think you worry too much." [6]_
+easily compromised, they were told "I think you worry too much." [#]_
 
 This strongly suggests that the existing ``random`` module is an attractive
 nuisance when it comes to generating (for example) passwords or secure
 tokens.
 
 Additional motivation (of a more philosophical bent) can be found in the
-post which first proposed this idea [7]_.
+post which first proposed this idea [#]_.
 
 
 Proposal
@@ -98,7 +98,7 @@ security.  (See Alternatives below.)  This proposes a different approach:
   the most common needs, such as generating secure tokens.  This code
   will both directly satisfy a need ("How do I generate a password reset
   token?"), and act as an example of acceptable practises which
-  developers can learn from [8]_.
+  developers can learn from [#]_.
 
 To do this, this PEP proposes that we add a new module to the standard
 library, with the suggested name ``secrets``.  This module will contain a
@@ -115,7 +115,7 @@ API and Implementation
 
 The contents of the ``secrets`` module is expected to evolve over time, and
 likely will evolve between the time of writing this PEP and actual release
-in the standard library [9]_.  At the time of writing, the following functions
+in the standard library [#]_.  At the time of writing, the following functions
 have been suggested:
 
 * A high-level function for generating secure tokens suitable for use
@@ -140,9 +140,9 @@ The consensus appears to be that there is no need to add a new CSPRNG to
 the ``random`` module to support these uses, ``SystemRandom`` will be
 sufficient.
 
-Some illustrative implementations have been given by Nick Coghlan [10]_
+Some illustrative implementations have been given by Nick Coghlan [#]_
-and a minimalist API by Tim Peters [11]_. This idea has also been discussed
+and a minimalist API by Tim Peters [#]_. This idea has also been discussed
-on the issue tracker for the "cryptography" module [12]_.  The following
+on the issue tracker for the "cryptography" module [#]_.  The following
 pseudo-code can be taken as a possible starting point for the real
 implementation::
 
@@ -186,12 +186,12 @@ help with this question by providing a default amount of entropy for the
 "token_*" functions. If the ``nbytes`` argument is None or not given, the
 default entropy will be used. This default value should be large enough
 to be expected to be secure for medium-security uses, but is expected to
-change in the future, possibly even in a maintenance release [13]_.
+change in the future, possibly even in a maintenance release [#]_.
 
 Naming conventions
 ~~~~~~~~~~~~~~~~~~
 
-One question is the naming conventions used in the module [14]_, whether to
+One question is the naming conventions used in the module [#]_, whether to
 use C-like naming conventions such as "randrange" or more Pythonic names
 such as "random_range".
 
@@ -204,7 +204,7 @@ Alternatives
 ============
 
 One alternative is to change the default PRNG provided by the ``random``
-module [15]_.  This received considerable scepticism and outright opposition:
+module [#]_.  This received considerable scepticism and outright opposition:
 
 * There is fear that a CSPRNG may be slower than the current PRNG (which
   in the case of MT is already quite slow).
@@ -223,12 +223,12 @@ module [15]_.  This received considerable scepticism and outright opposition:
 
 * Demonstrated attacks against MT are typically against PHP applications.
   It is believed that PHP's version of MT is a significantly softer target
-  than Python's version, due to a poor seeding technique [16]_.  Consequently,
+  than Python's version, due to a poor seeding technique [#]_.  Consequently,
   without a proven attack against Python applications, many people object
   to a backwards-incompatible change.
 
 Nick Coghlan made an earlier suggestion for a globally configurable PRNG
-which uses the system CSPRNG by default [17]_, but has since withdrawn it
+which uses the system CSPRNG by default [#]_, but has since withdrawn it
 in favour of this proposal.
 
 
@@ -237,7 +237,7 @@ Comparison To Other Languages
 
 * PHP
 
-  PHP includes a function ``uniqid`` [18]_ which by default returns a
+  PHP includes a function ``uniqid`` [#]_ which by default returns a
   thirteen character string based on the current time in microseconds.
   Translated into Python syntax, it has the following signature::
 
@@ -248,7 +248,7 @@ Comparison To Other Languages
   applications use it for that purpose (citation needed).
 
   PHP 5.3 and better also includes a function ``openssl_random_pseudo_bytes``
-  [19]_.  Translated into Python syntax, it has roughly the following
+  [#]_.  Translated into Python syntax, it has roughly the following
   signature::
 
     def openssl_random_pseudo_bytes(length:int)->Tuple[str, bool]
@@ -258,18 +258,21 @@ Comparison To Other Languages
   cryptographically strong.  The PHP manual suggests that returning
   anything but True should be rare except for old or broken platforms.
 
-* Javascript
+* JavaScript
 
-  Based on a rather cursory search [20]_, there do not appear to be any
+  Based on a rather cursory search [#]_, there do not appear to be any
   well-known standard functions for producing strong random values in
-  Javascript, although there may be good quality third-party libraries.
+  JavaScript. ``Math.random`` is often used, despite serious weaknesses
-  Standard Javascript doesn't seem to include an interface to the
+  making it unsuitable for cryptographic purposes [#]_. In recent years
-  system CSPRNG either, and people have extensively written about the
+  the majority of browsers have gained support for ``window.crypto.getRandomValues`` [#]_.
-  weaknesses of Javascript's ``Math.random`` [21]_.
+
+  Node.js offers a rich cryptographic module, ``crypto`` [#]_, most of
+  which is beyond the scope of this PEP. It does include a single function
+  for generating random bytes, ``crypto.randomBytes``.
 
 * Ruby
 
-  The Ruby standard library includes a module ``SecureRandom`` [22]_
+  The Ruby standard library includes a module ``SecureRandom`` [#]_
   which includes the following methods:
 
   * base64 - returns a Base64 encoded random string.
@@ -291,13 +294,13 @@ What Should Be The Name Of The Module?
 
 There was a proposal to add a "random.safe" submodule, quoting the Zen
 of Python "Namespaces are one honking great idea" koan.  However, the
-author of the Zen, Tim Peters, has come out against this idea [23]_, and
+author of the Zen, Tim Peters, has come out against this idea [#]_, and
 recommends a top-level module.
 
 In discussion on the python-ideas mailing list so far, the name "secrets"
 has received some approval, and no strong opposition.
 
-There is already an existing third-party module with the same name [24]_,
+There is already an existing third-party module with the same name [#]_,
 but it appears to be unused and abandoned.
 
 
@@ -309,9 +312,9 @@ Frequently Asked Questions
 
   A: The consensus among security professionals is that MT is not safe
   in security contexts.  It is not difficult to reconstruct the internal
-  state of MT [25]_ [26]_ and so predict all past and future values.  There
+  state of MT [#]_ [#]_ and so predict all past and future values.  There
   are a number of known, practical attacks on systems using MT for
-  randomness [27]_.
+  randomness [#]_.
 
   While there are currently no known direct attacks on applications
   written in Python due to the use of MT, there is widespread agreement
@@ -322,7 +325,7 @@ Frequently Asked Questions
   A: No. This is a "batteries included" solution, not a full-featured
   "nuclear reactor".  It is intended to mitigate against some basic
   security errors, not be a solution to all security-related issues. To
-  quote Nick Coghlan referring to his earlier proposal [28]_::
+  quote Nick Coghlan referring to his earlier proposal [#]_::
 
       "...folks really are better off learning to use things like
       cryptography.io for security sensitive software, so this change
@@ -333,84 +336,100 @@ Frequently Asked Questions
 * Q: What about a password generator?
 
   A: The consensus is that the requirements for password generators are too
-     variable for it to be a good match for the standard library [29]_. No
+     variable for it to be a good match for the standard library [#]_. No
      password generator will be included in the initial release of the
      module, instead it will be given in the documentation as a recipe (à la
-     the recipes in the ``itertools`` module) [30]_.
+     the recipes in the ``itertools`` module) [#]_.
+
+* Q: Will ``secrets`` use /dev/random (which blocks) or /dev/urandom (which
+     doesn't block) on Linux? What about other platforms?
+
+  A: ``secrets`` will be based on ``os.urandom`` and ``random.SystemRandom``,
+     which are interfaces to your operating system's best source of
+     cryptographic randomness. On Linux, that may be ``/dev/urandom`` [#]_,
+     on Windows it may be ``CryptGenRandom()``, but see the documentation
+     and/or source code for the detailed implementation details.
 
 
 References
 ==========
 
-.. [1] https://mail.python.org/pipermail/python-ideas/2015-September/035820.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/035820.html
 
-.. [2] https://docs.python.org/3/library/random.html
+.. [#] https://docs.python.org/3/library/random.html
 
-.. [3] As of the date of writing. Also, as Google search terms may be
+.. [#] As of the date of writing. Also, as Google search terms may be
        automatically customised for the user without their knowledge, some
        readers may see different results.
 
-.. [4] http://interactivepython.org/runestone/static/everyday/2013/01/3_password.html
+.. [#] http://interactivepython.org/runestone/static/everyday/2013/01/3_password.html
 
-.. [5] http://stackoverflow.com/questions/3854692/generate-password-in-python
+.. [#] http://stackoverflow.com/questions/3854692/generate-password-in-python
 
-.. [6] http://stackoverflow.com/questions/3854692/generate-password-in-python/3854766#3854766
+.. [#] http://stackoverflow.com/questions/3854692/generate-password-in-python/3854766#3854766
 
-.. [7] https://mail.python.org/pipermail/python-ideas/2015-September/036238.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036238.html
 
-.. [8] At least those who are motivated to read the source code and documentation.
+.. [#] At least those who are motivated to read the source code and documentation.
 
-.. [9] Tim Peters suggests that bike-shedding the contents of the module will
+.. [#] Tim Peters suggests that bike-shedding the contents of the module will
        be 10000 times more time consuming than actually implementing the
        module.  Words do not begin to express how much I am looking forward to
        this.
 
-.. [10] https://mail.python.org/pipermail/python-ideas/2015-September/036271.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036271.html
 
-.. [11] https://mail.python.org/pipermail/python-ideas/2015-September/036350.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036350.html
 
-.. [12] https://github.com/pyca/cryptography/issues/2347
+.. [#] https://github.com/pyca/cryptography/issues/2347
 
-.. [13] https://mail.python.org/pipermail/python-ideas/2015-September/036517.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036517.html
-        https://mail.python.org/pipermail/python-ideas/2015-September/036515.html
+       https://mail.python.org/pipermail/python-ideas/2015-September/036515.html
 
-.. [14] https://mail.python.org/pipermail/python-ideas/2015-September/036474.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036474.html
 
-.. [15] Link needed.
+.. [#] Link needed.
 
-.. [16] By default PHP seeds the MT PRNG with the time (citation needed),
+.. [#] By default PHP seeds the MT PRNG with the time (citation needed),
-        which is exploitable by attackers, while Python seeds the PRNG with
+       which is exploitable by attackers, while Python seeds the PRNG with
-        output from the system CSPRNG, which is believed to be much harder to
+       output from the system CSPRNG, which is believed to be much harder to
-        exploit.
+       exploit.
 
-.. [17] http://legacy.python.org/dev/peps/pep-0504/
+.. [#] http://legacy.python.org/dev/peps/pep-0504/
 
-.. [18] http://php.net/manual/en/function.uniqid.php
+.. [#] http://php.net/manual/en/function.uniqid.php
 
-.. [19] http://php.net/manual/en/function.openssl-random-pseudo-bytes.php
+.. [#] http://php.net/manual/en/function.openssl-random-pseudo-bytes.php
 
-.. [20] Volunteers and patches are welcome.
+.. [#] Volunteers and patches are welcome.
 
-.. [21] http://ifsec.blogspot.fr/2012/05/cross-domain-mathrandom-prediction.html
+.. [#] http://ifsec.blogspot.fr/2012/05/cross-domain-mathrandom-prediction.html
 
-.. [22] http://ruby-doc.org/stdlib-2.1.2/libdoc/securerandom/rdoc/SecureRandom.html
+.. [#] https://developer.mozilla.org/en-US/docs/Web/API/RandomSource/getRandomValues
 
-.. [23] https://mail.python.org/pipermail/python-ideas/2015-September/036254.html
+.. [#] https://nodejs.org/api/crypto.html
 
-.. [24] https://pypi.python.org/pypi/secrets
+.. [#] http://ruby-doc.org/stdlib-2.1.2/libdoc/securerandom/rdoc/SecureRandom.html
 
-.. [25] https://jazzy.id.au/2010/09/22/cracking_random_number_generators_part_3.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036254.html
 
-.. [26] https://mail.python.org/pipermail/python-ideas/2015-September/036077.html
+.. [#] https://pypi.python.org/pypi/secrets
 
-.. [27] https://media.blackhat.com/bh-us-12/Briefings/Argyros/BH_US_12_Argyros_PRNG_WP.pdf
+.. [#] https://jazzy.id.au/2010/09/22/cracking_random_number_generators_part_3.html
 
-.. [28] https://mail.python.org/pipermail/python-ideas/2015-September/036157.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036077.html
 
-.. [29] https://mail.python.org/pipermail/python-ideas/2015-September/036476.html
+.. [#] https://media.blackhat.com/bh-us-12/Briefings/Argyros/BH_US_12_Argyros_PRNG_WP.pdf
-        https://mail.python.org/pipermail/python-ideas/2015-September/036478.html
 
-.. [30] https://mail.python.org/pipermail/python-ideas/2015-September/036488.html
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036157.html
+
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036476.html
+       https://mail.python.org/pipermail/python-ideas/2015-September/036478.html
+
+.. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036488.html
+
+.. [#] http://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/
+       http://www.2uo.de/myths-about-urandom/
 
 
 Copyright