From 9a49ffb8ec5ede05bc6d7100066d9eda7efdde46 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Mon, 16 Sep 2019 10:45:14 +0200
Subject: [PATCH] Recommend against SHA-1 and MD5 for security

* doc/lispref/text.texi (Checksum/Hash):
* src/fns.c (Fmd5, Fsecure_hash):
* lisp/subr.el (sha1): Doc fix to recommend against SHA-1 and MD5 for
security-related applications, since they are not collision
resistant.  (Bug#37420)
---
 doc/lispref/text.texi | 12 ++++++------
 lisp/subr.el          |  8 ++++++--
 src/fns.c             | 11 +++++++++--
 3 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 7ce54f59c6..54b89cff5a 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4710,12 +4710,12 @@ Checksum/Hash
 SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512.  MD5 is the
 oldest of these algorithms, and is commonly used in @dfn{message
 digests} to check the integrity of messages transmitted over a
-network.  MD5 is not collision resistant (i.e., it is possible to
-deliberately design different pieces of data which have the same MD5
-hash), so you should not used it for anything security-related.  A
-similar theoretical weakness also exists in SHA-1.  Therefore, for
-security-related applications you should use the other hash types,
-such as SHA-2.
+network.  MD5 and SHA-1 are not collision resistant (i.e., it is
+possible to deliberately design different pieces of data which have
+the same MD5 or SHA-1 hash), so you should not use them for anything
+security-related.  For security-related applications you should use
+the other hash types, such as SHA-2 (e.g. @code{sha384} or
+@code{sha512}).
 
 @defun secure-hash-algorithms
 This function returns a list of symbols representing algorithms that
diff --git a/lisp/subr.el b/lisp/subr.el
index 0b47da884b..45b99a82d2 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3120,11 +3120,15 @@ field-at-pos
       raw-field)))
 
 (defun sha1 (object &optional start end binary)
-  "Return the SHA1 (Secure Hash Algorithm) of an OBJECT.
+  "Return the SHA-1 (Secure Hash Algorithm) of an OBJECT.
 OBJECT is either a string or a buffer.  Optional arguments START and
 END are character positions specifying which portion of OBJECT for
 computing the hash.  If BINARY is non-nil, return a string in binary
-form."
+form.
+
+Note that SHA-1 is not collision resistant and should not be used
+for anything security-related.  See `secure-hash' for
+alternatives."
   (secure-hash 'sha1 object start end binary))
 
 (defun function-get (f prop &optional autoload)
diff --git a/src/fns.c b/src/fns.c
index df921e28f3..20047be63d 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -5379,7 +5379,10 @@ DEFUN ("md5", Fmd5, Smd5, 1, 5, 0,
 command `prefer-coding-system') is used.
 
 If NOERROR is non-nil, silently assume the `raw-text' coding if the
-guesswork fails.  Normally, an error is signaled in such case.  */)
+guesswork fails.  Normally, an error is signaled in such case.
+
+Note that MD5 is not collision resistant and should not be used for
+anything security-related.  See `secure-hash' for alternatives.  */)
   (Lisp_Object object, Lisp_Object start, Lisp_Object end, Lisp_Object coding_system, Lisp_Object noerror)
 {
   return secure_hash (Qmd5, object, start, end, coding_system, noerror, Qnil);
@@ -5396,7 +5399,11 @@ DEFUN ("secure-hash", Fsecure_hash, Ssecure_hash, 2, 5, 0,
 
 The full list of algorithms can be obtained with `secure-hash-algorithms'.
 
-If BINARY is non-nil, returns a string in binary form.  */)
+If BINARY is non-nil, returns a string in binary form.
+
+Note that MD5 and SHA-1 are not collision resistant and should not be
+used for anything security-related.  Use one of the other hash types
+for security-related applications.  */)
   (Lisp_Object algorithm, Lisp_Object object, Lisp_Object start, Lisp_Object end, Lisp_Object binary)
 {
   return secure_hash (algorithm, object, start, end, Qnil, Qnil, binary);
-- 
2.20.1