Hynek Schlawack added the comment: I think since we ship cryptographic functions, we should take responsibility and warn against the most common mistakes people do. ---------- nosy: +hynek _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Changes by Giampaolo Rodola' : ---------- nosy: +giampaolo.rodola _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Changes by Andrew Svetlov : ---------- nosy: +asvetlov _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Christian Heimes added the comment: ping :) ---------- _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

STINNER Victor added the comment:

For passwords a key stretching and key derivation function like PBKDF2, bcrypt or scrypt is much more secure.

It looks like Python 3.4 now provides something for pbkdf2, so it may be interested to mention it on the top of the hashlib in your warning. http://docs.python.org/dev/library/hashlib.html#hashlib.pbkdf2_hmac ---------- nosy: +haypo _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

R. David Murray added the comment: Priya: I see that there is already a 'warning' box at the top of the hashib page. If Christian concurs, I suggest we add your note to that warning, with the link to the security considerations section as you have it, and removing the reference to the 'see also' section. Then we move the security related 'see also' link into the new security section, with a sentence that says that it explains the weaknesses. A note about the patch: you should wrap all lines to less than 80 characters. ---------- nosy: +r.david.murray _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

R. David Murray added the comment: Please note what I said about wrapping lines to less than 80 characters. Also, my thought was to move the 'see also' entry that is referenced in the existing warning text (the wikipedia link) into the 'security considerations' section, probably as a separate paragraph that consists of the current text that follows that reference, with 'wikipedia article' turned into a link to the actual article. (See http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-target... for information on how to make links to external urls in .rst files). ---------- _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Changes by Raymond Hettinger : ---------- title: Warn users about hashing secrets? -> Add advice on best practices for hashing secrets _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Raymond Hettinger added the comment:

So probably it should stay a warning in this particular case.

Please don't. Python's docs have become cluttered with warning and danger signs. This stands in marked contrast with the docs for other languages which are much cleaner. Our docs have also started to become "preachy", telling people how we think they should write programs rather than documenting what the language does. ---------- _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Christian Heimes added the comment: Raymond makes a good point. We mustn't clutter the docs with warnings. People are going to skip warning boxes if they occur too often. The documentation of the hashlib module contains three "note" boxes and one "warning box". That's far too many. The first "note" box could be moved to "see also". The other two "note" could be removed and their content added to the documentation of update(). The warning box should follow the example of the ssl module and all further security considerations should be moved into a new section. The Python stdlib documentation is the wrong place to teach users about crypto and security stuff. But in my opinion good documentation should point out that something is dangerous or may lure a user into false sense of security. Perhaps I should start a howto with common security-related issues in Python software for 3.5. ---------- _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Antoine Pitrou added the comment: Note boxes have nothing to do with warnings, we should discuss them separately if needed. (I see nothing wrong with multiple notes, given that a note is generally something ancillary and optional) ---------- nosy: +pitrou _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Changes by A.M. Kuchling : ---------- nosy: -akuchling _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________

Ezio Melotti added the comment:

People are going to skip warning boxes if they occur too often.

I'm not sure I agree. This would be true if they were abused for trivial things ("Warnings: using .pop() on a empty list will return an IndexError!"), but I don't think they are. I think warnings are ignored only by people that are already familiar with the module and its limitation/issues, and that know what they are doing. If the warning is not evident, people are going to miss it [0]. If warnings are used correctly, people will spot them easily and read them (or ignore them if they already know what they are warning against). [0]: I know I missed it in e.g. https://api.jquery.com/die/ -- the function is deprecated, but (currently) this is only written in the top right corner and in small in the category at the top -- two places that are easily overlooked. https://api.jquery.com/toggle-event/ on the other hand has a clearly visible yellow box at the top that immediately says that the method is deprecated. ---------- _______________________________________ Python tracker http://bugs.python.org/issue17006 _______________________________________