diff -r efe527e0f802 Doc/library/hashlib.rst
--- a/Doc/library/hashlib.rst	Wed Mar 12 13:14:19 2014 -0500
+++ b/Doc/library/hashlib.rst	Thu Mar 13 16:40:38 2014 -0400
@@ -29,8 +29,8 @@
 
 .. warning::
 
-   Some algorithms have known hash collision weaknesses, refer to the "See
-   also" section at the end.
+   Some algorithms have known hash collision weaknesses, please refer to 
+   the :ref:`security-considerations` section for important information
 
 
 .. _hash-algorithms:
@@ -213,6 +213,13 @@
    .. 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::