diff -r 3ae2cd85a908 Doc/library/hashlib.rst
--- a/Doc/library/hashlib.rst	Sun Mar 09 11:18:16 2014 +0100
+++ b/Doc/library/hashlib.rst	Tue Mar 11 23:56:50 2014 +0530
@@ -184,6 +184,7 @@
 against brute-force attacks. A good password hashing function must be tunable,
 slow and include a salt.
 
+.. note:: For passwords a key stretching and key derivation function like  :func:`pbkdf2_hmac`, bcrypt or scrypt is much more secure. Please refer to the :ref:`security-considerations` section for more information.
 
 .. function:: pbkdf2_hmac(name, password, salt, rounds, dklen=None)
 
@@ -210,11 +211,21 @@
 
    .. versionadded:: 3.4
 
+
+
    .. note:: A fast implementation of *pbkdf2_hmac* is available with OpenSSL.
       The Python implementation uses an inline version of :mod:`hmac`. It is
       about three times slower and doesn't release the GIL.
 
 
+.. _security-considerations:
+
+Security Considerations
+------------------------
+
+Using hash functions for secrets or messages containing a secret is not safe. Most crypto hash functions like md5, sha1, sha2 family (sha256, sha384, sha512) use a Merkle–Damgård construction. The construction is vulnerable to several attack vectors like length extension attacks. A MAC algorithm like HMAC should be used for messages and a key stretching and key derivation function like :func:`pbkdf2_hmac`, bcrypt or scrypt is much more secure for passwords.
+
+
 .. seealso::
 
    Module :mod:`hmac`