On Sat, 10 May 2014 14:35:38 -0700 Raymond Hettinger <raymond.hettinger@gmail.com> wrote:

In the past couple of years, we've grown an unfortunate tendency to fill the docs with big warning boxes (the subprocess docs are an example of implicitly communicating that the module is dangerous and unusable).

The preferred form of documentation is to be affirmatively worded, telling how to use a tool correctly and what its known limitations are. We save the warnings for cases of actual danger where otherwise well informed users get tripped-up.

Tim Peters used to be around to articulate the principle that we don't write the docs with the assumption that the users are less bright than we are or that they can't read.

I agree with Alex. It's not about being bright or not, it's about being *willing* to eat walls of text. However pleasant it may be for some people to *write* documentation, for most readers (and especially non-native English readers, who read more slowly and more painfully than native ones), documentation is a piece of reference that they skim from, rather than read from start to end like a novel. So it makes sense to single out useful information. Knowing that the functions from the random module are not appropriate for cryptography is (IMO) more important than knowing that """Python uses the Mersenne Twister as the core generator. It produces 53-bit precision floats and has a period of 2**19937-1. The underlying implementation in C is both fast and threadsafe""" Regards Antoine.

Give it up, Raymond. On Saturday, May 10, 2014, Raymond Hettinger <raymond.hettinger@gmail.com> wrote:

On May 10, 2014, at 2:54 PM, Antoine Pitrou <solipsis@pitrou.net<javascript:_e(%7B%7D,'cvml','solipsis@pitrou.net');>> wrote:

It's not about being bright or not, it's about being *willing* to eat walls of text. However pleasant it may be for some people to *write* documentation, for most readers (and especially non-native English readers, who read more slowly and more painfully than native ones), documentation is a piece of reference that they skim from, rather than read from start to end like a novel.

Most users of the random module documentation are just normal people trying to create random numbers. People writing secure apps with cryptographically secure random numbers are not the primary audience. But we have this big red security warning that essentially says, if you read only one thing, read this.

Before proceeding further with stamping distracting security warnings all over the module documentation, we should look to other languages to see what others have found necessary. This warning does not appear anywhere else I've looked (MS Excel docs, Java docs, Go lang docs, etc.)

http://docs.oracle.com/javase/6/docs/api/java/util/Random.html http://golang.org/pkg/math/rand/

Those docs are clear, concise, not preachy, and not littered with distractions.

Raymond

-- --Guido van Rossum (on iPad)

Nick Coghlan, 11.05.2014 01:01:

As you point out, most language development teams do very little to try to educate their users about security issues. The consequences of that are clearly visible in the world around us: when security is treated as an optional afterthought, you get widespread deployment of insecure software.

At this point, we have two options:

* continue with the same model as everyone else, and treat security as an optional extra users should feel free to ignore (or treat as an advanced topic only specialists need to worry about)

* change our documentation practices to try to encourage the growth of a security aware development community around Python, trusting that our users will recognise that the security issues we're discussing are inherent in the way computers work, rather than being specific to Python.

I'm obviously a strong advocate for the second path. Users aren't stupid, they'll figure out that almost all the security concerns we're warning about are inherent in the problem being solved, rather than being a Python-specific issue.

Even if I know the problematic parts of a certain corner of software development or just of a specific tool, I prefer reading in the documentation that the authors of that tool are also aware of the (potential) problems. Makes me feel more comfortable with trusting the software. Total +1 on keeping these little bits around. Stefan

[Raymond Hettinger]

... I'm not all at comfortable with the wording of the second sentence. I was the author of the SystemRandom() class and I only want to guarantee that it provides access to the operating system's source of random numbers. It is a bold claim to guarantee that it is cryptographically secure (many such claims in the past have turned-out to be false). We don't really know what it is going to do on a VM for example.

Also, I don't want to call SystemRandom() a pseudo-random number generator. It purports to be an actual random number generator (or at least it purports to have used some real source of entropy at some stage). To me (the module maintainer), that is an important distinction.

It should be sufficient to say that SystemRandom() inherits all the properties of the operating system's os.urandom() implementation, yes? Since Python has nothing to do with that, it's most accurate and helpful to tell the user to refer to their OS urandom docs. On all platforms I'm aware of (two ;-)), urandom() is in fact a CSPRNG, not an "actual random number generator". That's why urandom() can get away with never blocking, potentially producing bits far faster than the system random() can accumulate fresh entropy. But all the hideous details don't belong in the Python docs - they belong in the OS's urandom docs. A phrasing I've found helpful is to tell users that "urandom() is as secure as the people who wrote your operating system knew how to make it". Linux users smile then, and Windows users groan ;-)

On 11 May 2014 07:37, "Raymond Hettinger" <raymond.hettinger@gmail.com> wrote:

On May 10, 2014, at 2:18 PM, Alex Gaynor <alex.gaynor@gmail.com> wrote:

...

I think this change is a considerable usability regression for the

documentation. Right now the warnings about CSPRNGs are hidden in the introductory paragraph, which users are likely to skip

In the past couple of years, we've grown an unfortunate tendency to fill the docs with big warning boxes (the subprocess docs are an example of implicitly communicating that the module is dangerous and unusable).

The preferred form of documentation is to be affirmatively worded, telling how to use a tool correctly and what its known limitations are. We save the warnings for cases of actual danger where otherwise well informed users get tripped-up.

Tim Peters used to be around to articulate the principle that we don't

write

the docs with the assumption that the users are less bright than we are or that they can't read.

That assumption has changed somewhat, as many users are now getting their education in programming (and how computers work in general) from introductory community workshops and the Python documentation. This means that writing our docs based on the assumption that the reader is already going to be a professional programmer is no longer adequate. This is especially essential in security related areas, as even professional programmers usually aren't sufficiently paranoid about all the ways their software can be attacked. As Alex notes, the short term way to eliminate the duplication here is to keep the security warnings and drop the material from the introductory paragraph, not go back to expecting readers to have already been alerted to randomness related cryptographic security issues in some other context. Readers that are already familiar with the security concerns will hopefully recognise that they're not a Python specific problem (and may even be appreciative of our attempts to convey the relevant knowledge to a broader audience), while readers that aren't yet aware of them may be more likely to account for them appropriately when writing their software. It's as much about cultivating a more paranoid more mindset in developers in general as it is about the contents of the specific security warning. A "Security Considerations" section in the module documentation can be a better way to tackle this than trying to jam everything into one warning box, but there should still be a "Here be dragons" warning early on noting that random *is* a potentially security sensitive module in a cryptographic context. Regards, Nick.

Hi, On Sun, May 11, 2014 at 12:35 AM, Raymond Hettinger <raymond.hettinger@gmail.com> wrote:

On May 10, 2014, at 2:18 PM, Alex Gaynor <alex.gaynor@gmail.com> wrote:

I think this change is a considerable usability regression for the documentation. Right now the warnings about CSPRNGs are hidden in the introductory paragraph, which users are likely to skip

In the past couple of years, we've grown an unfortunate tendency to fill the docs with big warning boxes

If the problem is the scary red boxes, http://bugs.python.org/issue13515 still has a patch to make them less intimidating (and some interesting discussion about it). Best Regards, Ezio Melotti

(the subprocess docs are an example of implicitly communicating that the module is dangerous and unusable).

The preferred form of documentation is to be affirmatively worded, telling how to use a tool correctly and what its known limitations are. We save the warnings for cases of actual danger where otherwise well informed users get tripped-up.

Tim Peters used to be around to articulate the principle that we don't write the docs with the assumption that the users are less bright than we are or that they can't read.

People writing applications that need to be sure should probably have a howto guide. I don't think they are well served by filling the module docs with every possible way a person could make a security mistake).

If you're writing a secure on-line poker game, you really need to know a great deal more about security than the warning message can supply. My understanding is that actual gaming systems use seeded CSPRNGs rather than urandom() because those systems need to be auditable.

Raymond

P.S. The docs for the random module had a successful 20 year history without the redundant big red warning box, so it is not really correct to say there has been a "considerable usability regression".