[Python-checkins] peps: PEP 506: Improve markup
berker.peksag
python-checkins at python.org
Sun Sep 20 02:22:00 CEST 2015
https://hg.python.org/peps/rev/68a2455c09aa
changeset: 6074:68a2455c09aa
user: Berker Peksag <berker.peksag at gmail.com>
date: Sun Sep 20 03:21:55 2015 +0300
summary:
PEP 506: Improve markup
files:
pep-0506.txt | 143 ++++++++++++++++++++------------------
1 files changed, 76 insertions(+), 67 deletions(-)
diff --git a/pep-0506.txt b/pep-0506.txt
--- a/pep-0506.txt
+++ b/pep-0506.txt
@@ -47,11 +47,11 @@
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 [1]_ 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 [2]_, it is strongly
believed that this warning may be missed, ignored or misunderstood by
many Python developers. In particular:
@@ -65,21 +65,21 @@
(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 [3]_ 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 [4]_. 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 [5]_. 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." [6]_
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 [7]_.
Proposal
@@ -98,7 +98,7 @@
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 [8]_.
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 @@
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 [9]_. 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 ``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 [10]_.
This idea has also been discussed on the issue tracker for the
-"cryptography" module[11].
+"cryptography" module [11]_.
The ``secrets`` module itself will be pure Python, and other Python
implementations can easily make use of it unchanged, or adapt it as
@@ -153,7 +153,7 @@
============
One alternative is to change the default PRNG provided by the ``random``
-module[12]. This received considerable scepticism and outright opposition:
+module [12]_. 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).
@@ -172,13 +172,13 @@
* 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[13]. Consequently,
+ than Python's version, due to a poor seeding technique [13]_. 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[14], but has since hinted that he
-may withdraw it in favour of this proposal[15].
+which uses the system CSPRNG by default [14]_, but has since hinted that he
+may withdraw it in favour of this proposal [15]_.
Comparison To Other Languages
@@ -186,7 +186,7 @@
* PHP
- PHP includes a function ``uniqid`` [16] which by default returns a
+ PHP includes a function ``uniqid`` [16]_ which by default returns a
thirteen character string based on the current time in microseconds.
Translated into Python syntax, it has the following signature::
@@ -196,8 +196,9 @@
security purposes. Nevertheless, various mature, well-known PHP
applications use it for that purpose (citation needed).
- PHP 5.3 and better also includes a function ``openssl_random_pseudo_bytes`` [17].
- Translated into Python syntax, it has roughly the following signature::
+ PHP 5.3 and better also includes a function ``openssl_random_pseudo_bytes``
+ [17]_. Translated into Python syntax, it has roughly the following
+ signature::
def openssl_random_pseudo_bytes(length:int)->Tuple[str, bool]
@@ -208,16 +209,16 @@
* Javascript
- Based on a rather cursory search[18], there doesn't appear to be any
+ Based on a rather cursory search [18]_, there doesn't appear to be any
well-known standard functions for producing strong random values in
Javascript, although there may be good quality third-party libraries.
Standard Javascript doesn't seem to include an interface to the
system CSPRNG either, and people have extensively written about the
- weaknesses of Javascript's Math.random[19].
+ weaknesses of Javascript's ``Math.random`` [19]_.
* Ruby
- The Ruby standard library includes a module ``SecureRandom`` [20]
+ The Ruby standard library includes a module ``SecureRandom`` [20]_
which includes the following methods:
* base64 - returns a Base64 encoded random string.
@@ -239,7 +240,7 @@
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[21], and
+author of the Zen, Tim Peters, has come out against this idea [21]_, and
recommends a top-level module.
In discussion on the python-ideas mailing list so far, the name "secrets"
@@ -249,85 +250,93 @@
Frequently Asked Questions
==========================
- * Q: Is this a real problem? Surely MT is random enough that nobody can
- predict its output.
+* Q: Is this a real problem? Surely MT is random enough that nobody can
+ predict its output.
- 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[22][23] and so predict all past and future values. There
- are a number of known, practical attacks on systems using MT for
- randomness[24].
+ 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 [22]_ [23]_ and so predict all past and future values. There
+ are a number of known, practical attacks on systems using MT for
+ randomness [24]_.
- While there are currently no known direct attacks on applications
- written in Python due to the use of MT, there is widespread agreement
- that such usage is unsafe.
+ While there are currently no known direct attacks on applications
+ written in Python due to the use of MT, there is widespread agreement
+ that such usage is unsafe.
- * Q: Is this an alternative to specialise cryptographic software such as SSL?
+* Q: Is this an alternative to specialise cryptographic software such as SSL?
- 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::
+ 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 [25]_::
- "...folks really are better off learning to use things like
- cryptography.io for security sensitive software, so this change
- is just about harm mitigation given that it's inevitable that a
- non-trivial proportion of the millions of current and future
- Python developers won't do that."[25]
+ "...folks really are better off learning to use things like
+ cryptography.io for security sensitive software, so this change
+ is just about harm mitigation given that it's inevitable that a
+ non-trivial proportion of the millions of current and future
+ Python developers won't do that."
References
==========
-[1] https://mail.python.org/pipermail/python-ideas/2015-September/035820.html
+.. [1] https://mail.python.org/pipermail/python-ideas/2015-September/035820.html
-[2] https://docs.python.org/3/library/random.html
+.. [2] https://docs.python.org/3/library/random.html
-[3] 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.
+.. [3] 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
+.. [4] http://interactivepython.org/runestone/static/everyday/2013/01/3_password.html
-[5] http://stackoverflow.com/questions/3854692/generate-password-in-python
+.. [5] http://stackoverflow.com/questions/3854692/generate-password-in-python
-[6] http://stackoverflow.com/questions/3854692/generate-password-in-python/3854766#3854766
+.. [6] http://stackoverflow.com/questions/3854692/generate-password-in-python/3854766#3854766
-[7] https://mail.python.org/pipermail/python-ideas/2015-September/036238.html
+.. [7] 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.
+.. [8] 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 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.
+.. [9] 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
+.. [10] https://mail.python.org/pipermail/python-ideas/2015-September/036271.html
-[11] https://github.com/pyca/cryptography/issues/2347
+.. [11] https://github.com/pyca/cryptography/issues/2347
-[12] Link needed.
+.. [12] Link needed.
-[13] By default PHP seeds the MT PRNG with the time (citation needed), which is exploitable by attackers, while Python seeds the PRNG with output from the system CSPRNG, which is believed to be much harder to exploit.
+.. [13] By default PHP seeds the MT PRNG with the time (citation needed),
+ which is exploitable by attackers, while Python seeds the PRNG with
+ output from the system CSPRNG, which is believed to be much harder to
+ exploit.
-[14] http://legacy.python.org/dev/peps/pep-0504/
+.. [14] http://legacy.python.org/dev/peps/pep-0504/
-[15] https://mail.python.org/pipermail/python-ideas/2015-September/036243.html
+.. [15] https://mail.python.org/pipermail/python-ideas/2015-September/036243.html
-[16] http://php.net/manual/en/function.uniqid.php
+.. [16] http://php.net/manual/en/function.uniqid.php
-[17] http://php.net/manual/en/function.openssl-random-pseudo-bytes.php
+.. [17] http://php.net/manual/en/function.openssl-random-pseudo-bytes.php
-[18] Volunteers and patches are welcome.
+.. [18] Volunteers and patches are welcome.
-[19] http://ifsec.blogspot.fr/2012/05/cross-domain-mathrandom-prediction.html
+.. [19] http://ifsec.blogspot.fr/2012/05/cross-domain-mathrandom-prediction.html
-[20] http://ruby-doc.org/stdlib-2.1.2/libdoc/securerandom/rdoc/SecureRandom.html
+.. [20] http://ruby-doc.org/stdlib-2.1.2/libdoc/securerandom/rdoc/SecureRandom.html
-[21] https://mail.python.org/pipermail/python-ideas/2015-September/036254.html
+.. [21] https://mail.python.org/pipermail/python-ideas/2015-September/036254.html
-[22] https://jazzy.id.au/2010/09/22/cracking_random_number_generators_part_3.html
+.. [22] https://jazzy.id.au/2010/09/22/cracking_random_number_generators_part_3.html
-[23] https://mail.python.org/pipermail/python-ideas/2015-September/036077.html
+.. [23] https://mail.python.org/pipermail/python-ideas/2015-September/036077.html
-[24] https://media.blackhat.com/bh-us-12/Briefings/Argyros/BH_US_12_Argyros_PRNG_WP.pdf
+.. [24] https://media.blackhat.com/bh-us-12/Briefings/Argyros/BH_US_12_Argyros_PRNG_WP.pdf
-[25] https://mail.python.org/pipermail/python-ideas/2015-September/036157.html
+.. [25] https://mail.python.org/pipermail/python-ideas/2015-September/036157.html
Copyright
--
Repository URL: https://hg.python.org/peps
More information about the Python-checkins
mailing list