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
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
@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
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
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