From 2d1e43436da93defe13ad125de46e3bce41172c3 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 11 Feb 2023 12:28:43 +0200 Subject: [PATCH] ; Improve documentation of hash functions. * src/fns.c (Fsecure_hash, Fmd5): Document the length of the return values. * lisp/subr.el (sha1): Describe the return value in more detail. * doc/lispref/text.texi (Checksum/Hash): Document 'sha1'. Document the length of the strings returned by each hashing algorithm. --- doc/lispref/text.texi | 47 +++++++++++++++++++++++++++++++++++++------ lisp/subr.el | 4 ++-- src/fns.c | 17 ++++++++-------- 3 files changed, 52 insertions(+), 16 deletions(-) diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 326c111cac5..0a48beab8b8 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -4947,16 +4947,38 @@ computed for the whole of @var{object}. If the argument @var{binary} is omitted or @code{nil}, the function returns the @dfn{text form} of the hash, as an ordinary Lisp string. If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary -form}, as a sequence of bytes stored in a unibyte string. +form}, as a sequence of bytes stored in a unibyte string. The length +of the returned string depends on @var{algorithm}: + +@itemize +@item +For @code{md5}: 32 characters (32 bytes if @var{binary} is +non-@code{nil}). +@item +For @code{sha1}: 40 characters (40 bytes if @var{binary} is +non-@code{nil}). +@item +For @code{sha224}: 56 characters (56 bytes if @var{binary} is +non-@code{nil}). +@item +For @code{sha256}: 64 characters (64 bytes if @var{binary} is +non-@code{nil}). +@item +For @code{sha384}: 96 characters (96 bytes if @var{binary} is +non-@code{nil}). +@item +For @code{sha512}: 128 characters (128 bytes if @var{binary} is +non-@code{nil}). +@end itemize This function does not compute the hash directly from the internal representation of @var{object}'s text (@pxref{Text Representations}). Instead, it encodes the text using a coding system (@pxref{Coding Systems}), and computes the hash from that encoded text. If @var{object} is a buffer, the coding system used is the one which -would be chosen by default for writing the text into a file. If -@var{object} is a string, the user's preferred coding system is used -(@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}). +would be chosen by default for writing the text of that buffer into a +file. If @var{object} is a string, the user's preferred coding system +is used (@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}). @end defun @defun md5 object &optional start end coding-system noerror @@ -4964,7 +4986,7 @@ This function returns an MD5 hash. It is semi-obsolete, since for most purposes it is equivalent to calling @code{secure-hash} with @code{md5} as the @var{algorithm} argument. The @var{object}, @var{start} and @var{end} arguments have the same meanings as in -@code{secure-hash}. +@code{secure-hash}. The function returns a 32-character string. If @var{coding-system} is non-@code{nil}, it specifies a coding system to use to encode the text; if omitted or @code{nil}, the default @@ -4987,7 +5009,20 @@ It should be somewhat more efficient on larger buffers than @code{secure-hash} is, and should not allocate more memory. @c Note that we do not document what hashing function we're using, or @c even whether it's a cryptographic hash, since that may change -@c according to what we find useful. +@c according to what we find useful. We also don't document the +@c length of the hash string it returns, since that can be used to +@c guess the hashing function being used. +@end defun + +@defun sha1 object &optional start end binary +This function is equivalent to calling @code{secure-hash} like this: + +@lisp +(secure-hash 'sha1 object start end binary) +@end lisp + +It returns a 40-character string if @var{binary} is @code{nil}, or a +40-byte unibyte string otherwise. @end defun @node Suspicious Text diff --git a/lisp/subr.el b/lisp/subr.el index 32c997425cf..9e6388987df 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -4160,8 +4160,8 @@ or byte-code." "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. +computing the hash. If BINARY is non-nil, return a 40-byte unibyte +string; otherwise returna 40-character string. Note that SHA-1 is not collision resistant and should not be used for anything security-related. See `secure-hash' for diff --git a/src/fns.c b/src/fns.c index 3984e318feb..ff364c65e26 100644 --- a/src/fns.c +++ b/src/fns.c @@ -5804,8 +5804,9 @@ secure_hash (Lisp_Object algorithm, Lisp_Object object, Lisp_Object start, DEFUN ("md5", Fmd5, Smd5, 1, 5, 0, doc: /* Return MD5 message digest of OBJECT, a buffer or string. -A message digest is a cryptographic checksum of a document, and the -algorithm to calculate it is defined in RFC 1321. +A message digest is the string representation of the cryptographic checksum +of a document, and the algorithm to calculate it is defined in RFC 1321. +The MD5 digest is 32-character long. The two optional arguments START and END are character positions specifying for which part of OBJECT the message digest should be @@ -5839,12 +5840,12 @@ anything security-related. See `secure-hash' for alternatives. */) DEFUN ("secure-hash", Fsecure_hash, Ssecure_hash, 2, 5, 0, doc: /* Return the secure hash of OBJECT, a buffer or string. ALGORITHM is a symbol specifying the hash to use: -- md5 corresponds to MD5 -- sha1 corresponds to SHA-1 -- sha224 corresponds to SHA-2 (SHA-224) -- sha256 corresponds to SHA-2 (SHA-256) -- sha384 corresponds to SHA-2 (SHA-384) -- sha512 corresponds to SHA-2 (SHA-512) +- md5 corresponds to MD5, produces a 32-character signature +- sha1 corresponds to SHA-1, produces a 40-character signature +- sha224 corresponds to SHA-2 (SHA-224), produces a 56-character signature +- sha256 corresponds to SHA-2 (SHA-256), produces a 64-character signature +- sha384 corresponds to SHA-2 (SHA-384), produces a 96-character signature +- sha512 corresponds to SHA-2 (SHA-512), produces a 128-character signature The two optional arguments START and END are positions specifying for which part of OBJECT to compute the hash. If nil or omitted, uses the -- 2.39.2