On 16/06/2023 13:16, Pádraig Brady wrote:
On 15/06/2023 22:37, David Loyall wrote:
Hello.
Today the correct canonical link to the HTML form of the documentation
for sha512sum is this:
https://www.gnu.org/software/coreutils/manual/html_node/md5sum-invocation.html
Note "md5sum" in the URL and in the document.
Here is the explanation:
https://www.gnu.org/software/coreutils/manual/html_node/sha2-utilities.html
I think the situation should change somehow. Off the top of my head:
what if you just flip it around so that the md5sum documentation
points at the sha2 utilities, instead of the other way around?
Here is why I considered this important enough to mention: at least
one major organization is currently giving bad advice about the sha2
family of utilities.. See
https://www.apache.org/info/verification.html#CheckingHashes and note
the absence of advice about using the `--check` argument. The
`--check` argument is important.
Background: I started writing to a smaller organization suggesting
they add `--check` to their documentation and during the process I
discovered a) the larger organization also got it wrong and b) I can't
provide a direct link to clear documentation from the canonical
source.
A generation or two of folks have been taught to avoid anything that
says md5 on it...
Thank you for your time and of course for this collection of utilities
of immeasurable importance.
Well there are redirects setup for all utils to redirect to the appropriate
part of the manual. These are the URLs presented in the man pages BTW.
So in this case the best url to use is:
https://www.gnu.org/software/coreutils/sha512sum
But I do agree that the docs for these checksum utils have become
a bit awkward as these utilities have evolved.
Currently the option descriptions are dispersed over the following nodes:
* b2sum
* cksum
* md5sum
It would be better I think to now organize the options over two nodes as
follows,
and then adjust to redirects for the standalone checksum utils to
cksum-common-options:
* cksum invocation
* general options
Options supported only by cksum
--algorithm
--base64
--debug
--length
--raw
--untagged
* common options
Options supported by cksum and standalone checksum utilities
--binary
--check
--ignore-missing
--quiet
--status
--tag
--text
--warn
--strict
--zero
cheers,
Pádraig
Done in the attached.
cheers,
Pádraig
From 1e8624a61dcdf66d7ac77841543f1be6a400d4ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com>
Date: Mon, 21 Aug 2023 15:15:36 +0100
Subject: [PATCH] doc: reorg texinfo description of the checksumming utilities
* doc/coreutils.texi: Reorg so that 'cksum invocation' is the
main node listing all options and output formats, which is then
referenced by the descriptions of the standalone utilities.
---
doc/coreutils.texi | 207 ++++++++++++++++++++++++++-------------------
1 file changed, 119 insertions(+), 88 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 8fdb6b5d9..ec5bcfc2d 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -4009,12 +4009,56 @@ by comparing the @command{cksum} output for the received files with the
@command{cksum} output for the original files (typically given in the
distribution).
+@menu
+* cksum output modes:: Legacy and non Legacy output formats
+* cksum general options:: Options suppported only by cksum
+* cksum common options:: Options suppported also by standalone utilities
+@end menu
+
+@node cksum output modes
+
+@table @asis
+
+@item Legacy output format
@command{cksum} by default prints the POSIX standard CRC checksum
for each file along with the number of bytes in the file,
and the file name unless no arguments were given.
The 32-bit CRC used is based on the polynomial used
for CRC error checking in the ISO/IEC 8802-3:1996 standard (Ethernet).
+The same output format is used for the other legacy checksums
+selectable with @option{--algorithm=sysv} or @option{--algorithm=bsd}.
+
+@item Tagged output format
+With the @option{--algorithm} option selecting non legacy checksums,
+the @command{cksum} command defaults to output of the form:
+@example
+@var{digest_name} (@var{file name}) = @var{digest}
+@end example
+Note the standalone checksum utilities can select this output
+mode by using the @option{--tag} option.
+
+@item Untagged output format
+With the @option{--untagged} option and the @option{--algorithm} option
+selecting non legacy checksums, the following output format is used.
+Note this is the default output format of the standalone checksum utilities.
+For each @var{file}, we print the checksum, a space, a flag indicating
+binary or text input mode, and the file name.
+Binary mode is indicated with @samp{*}, text mode with @samp{ } (space).
+Binary mode is the default on systems where it's significant,
+otherwise text mode is the default. The @command{cksum} command always
+uses binary mode and a @samp{ } (space) flag.
+
+@end table
+
+Note without @option{--zero}, and with non legacy output formats,
+if @var{file} contains a backslash, newline, or carriage return,
+the line is started with a backslash, and each problematic character
+in the file name is escaped with a backslash, making the output unambiguous
+even in the presence of arbitrary file names.
+Since the backslash character itself is escaped, any other backslash
+escape sequences are reserved for future use.
+@node cksum general options
@table @samp
@item -a
@@ -4096,80 +4140,7 @@ Note this does not identify the digest algorithm used for the checksum.
@xref{md5sum invocation} for details of this format.
@end table
-
-@node b2sum invocation
-@section @command{b2sum}: Print or check BLAKE2 digests
-
-@pindex b2sum
-@cindex BLAKE2
-@cindex 512-bit checksum
-@cindex checksum, 512-bit
-@cindex fingerprint, 512-bit
-@cindex message-digest, 512-bit
-
-@command{b2sum} computes a 512-bit checksum for each specified
-@var{file}. The same usage and options as the @command{md5sum}
-command are supported. @xref{md5sum invocation}.
-In addition @command{b2sum} supports the following options.
-
-@table @samp
-@cksumLengthOption
-@end table
-
-@node md5sum invocation
-@section @command{md5sum}: Print or check MD5 digests
-
-@pindex md5sum
-@cindex MD5
-@cindex 128-bit checksum
-@cindex checksum, 128-bit
-@cindex fingerprint, 128-bit
-@cindex message-digest, 128-bit
-
-@command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or
-@dfn{message-digest}) for each specified @var{file}.
-
-@macro weakHash{hash}
-Note: The \hash\ digest is more reliable than a simple CRC (provided by
-the @command{cksum} command) for detecting accidental file corruption,
-as the chances of accidentally having two files with identical \hash\
-are vanishingly small. However, it should not be considered secure
-against malicious tampering: although finding a file with a given \hash\
-fingerprint is considered infeasible at the moment, it is known how
-to modify certain files, including digital certificates, so that they
-appear valid when signed with an \hash\ digest. For more secure hashes,
-consider using SHA-2, or the newer @command{b2sum} command.
-@xref{sha2 utilities}. @xref{b2sum invocation}.
-@end macro
-@weakHash{MD5}
-
-If a @var{file} is specified as @samp{-} or if no files are given
-@command{md5sum} computes the checksum for the standard input.
-@command{md5sum} can also determine whether a file and checksum are
-consistent. Synopsis:
-
-@example
-md5sum [@var{option}]@dots{} [@var{file}]@dots{}
-@end example
-
-For each @var{file}, @samp{md5sum} outputs by default, the MD5 checksum,
-a space, a flag indicating binary or text input mode, and the file name.
-Binary mode is indicated with @samp{*}, text mode with @samp{ } (space).
-Binary mode is the default on systems where it's significant,
-otherwise text mode is the default. The @command{cksum} command always
-uses binary mode and a @samp{ } (space) flag.
-
-Without @option{--zero}, if @var{file} contains a backslash, newline,
-or carriage return, the line is started with a backslash, and each
-problematic character in the file name is escaped with a backslash,
-making the output unambiguous even in the presence of arbitrary file names.
-Since the backslash character itself is escaped, any other backslash
-escape sequences are reserved for future use.
-
-If @var{file} is omitted or specified as @samp{-}, standard input is read.
-
-The program accepts the following options. Also see @ref{Common options}.
-
+@node cksum common options
@table @samp
@item -b
@@ -4183,7 +4154,7 @@ Treat each input file as binary, by reading it in binary mode and
outputting a @samp{*} flag. This is the inverse of @option{--text}.
On systems like GNU that do not distinguish between binary
and text files, this option merely flags each input mode as binary:
-the MD5 checksum is unaffected. This option is the default on systems
+the checksum is unaffected. This option is the default on systems
like MS-DOS that distinguish between binary and text files, except
for reading standard input when standard input is a terminal.
@@ -4192,8 +4163,8 @@ for reading standard input when standard input is a terminal.
Read file names and checksum information (not data) from each
@var{file} (or from standard input if no @var{file} was specified) and report
whether the checksums match the contents of the named files.
-The input to this mode of @command{md5sum} is usually the output of
-a prior, checksum-generating run of @samp{md5sum}.
+The input to this mode is usually the output of
+a prior, checksum-generating run of the command.
Three input formats are supported. Either the default output
format described above, the @option{--tag} output format,
@@ -4211,8 +4182,8 @@ checksums and those generated via @command{cksum} with its
Output with @option{--zero} enabled is not supported by @option{--check}.
@sp 1
-For each such line, @command{md5sum} reads the named file and computes its
-MD5 checksum. Then, if the computed message digest does not match the
+For each such line, @command{cksum} reads the named file and computes its
+checksum. Then, if the computed message digest does not match the
one on the line with the file name, the file is noted as having
failed the test. Otherwise, the file passes the test.
By default, for each valid line, one line is written to standard
@@ -4221,15 +4192,15 @@ After all checks have been performed, if there were any failures,
a warning is issued to standard error.
Use the @option{--status} option to inhibit that output.
If any listed file cannot be opened or read, if any valid line has
-an MD5 checksum inconsistent with the associated file, or if no valid
-line is found, @command{md5sum} exits with nonzero status. Otherwise,
+a checksum inconsistent with the associated file, or if no valid
+line is found, @command{cksum} exits with nonzero status. Otherwise,
it exits successfully.
Note the @command{cksum} command doesn't support @option{--check}
with the older @samp{sysv}, @samp{bsd}, or @samp{crc} algorithms.
@item --ignore-missing
@opindex --ignore-missing
-@cindex verifying MD5 checksums
+@cindex verifying checksums
This option is useful only when verifying checksums.
When verifying checksums, don't fail or report any status
for missing files. This is useful when verifying a subset
@@ -4237,7 +4208,7 @@ of downloaded files given a larger list of checksums.
@item --quiet
@opindex --quiet
-@cindex verifying MD5 checksums
+@cindex verifying checksums
This option is useful only when verifying checksums.
When verifying checksums, don't generate an 'OK' message per successfully
checked file. Files that fail the verification are reported in the
@@ -4246,14 +4217,14 @@ print a warning summarizing the failures to standard error.
@item --status
@opindex --status
-@cindex verifying MD5 checksums
+@cindex verifying checksums
This option is useful only when verifying checksums.
When verifying checksums, don't generate the default one-line-per-file
diagnostic and don't output the warning summarizing any failures.
Failures to open or read a file still evoke individual diagnostics to
standard error.
If all listed files are readable and are consistent with the associated
-MD5 checksums, exit successfully. Otherwise exit with a status code
+checksums, exit successfully. Otherwise exit with a status code
indicating there was a failure.
@item --tag
@@ -4285,14 +4256,14 @@ terminal. This mode is never defaulted to if @option{--tag} is used.
@itemx --warn
@opindex -w
@opindex --warn
-@cindex verifying MD5 checksums
-When verifying checksums, warn about improperly formatted MD5 checksum lines.
+@cindex verifying checksums
+When verifying checksums, warn about improperly formatted checksum lines.
This option is useful only if all but a few lines in the checked input
are valid.
@item --strict
@opindex --strict
-@cindex verifying MD5 checksums
+@cindex verifying checksums
When verifying checksums,
if one or more input line is invalid,
exit nonzero after all warnings have been issued.
@@ -4301,6 +4272,66 @@ exit nonzero after all warnings have been issued.
Also file name escaping is not used.
@end table
+@node b2sum invocation
+@section @command{b2sum}: Print or check BLAKE2 digests
+
+@pindex b2sum
+@cindex BLAKE2
+@cindex 512-bit checksum
+@cindex checksum, 512-bit
+@cindex fingerprint, 512-bit
+@cindex message-digest, 512-bit
+
+@command{b2sum} computes a 512-bit checksum for each specified
+@var{file}. The same usage and options as the @command{md5sum}
+command are supported. @xref{md5sum invocation}.
+In addition @command{b2sum} supports the following options.
+
+@table @samp
+@cksumLengthOption
+@end table
+
+@node md5sum invocation
+@section @command{md5sum}: Print or check MD5 digests
+
+@pindex md5sum
+@cindex MD5
+@cindex 128-bit checksum
+@cindex checksum, 128-bit
+@cindex fingerprint, 128-bit
+@cindex message-digest, 128-bit
+
+@command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or
+@dfn{message-digest}) for each specified @var{file}.
+
+@macro weakHash{hash}
+Note: The \hash\ digest is more reliable than a simple CRC (provided by
+the @command{cksum} command) for detecting accidental file corruption,
+as the chances of accidentally having two files with identical \hash\
+are vanishingly small. However, it should not be considered secure
+against malicious tampering: although finding a file with a given \hash\
+fingerprint is considered infeasible at the moment, it is known how
+to modify certain files, including digital certificates, so that they
+appear valid when signed with an \hash\ digest. For more secure hashes,
+consider using SHA-2, or the newer @command{b2sum} command.
+@xref{sha2 utilities}. @xref{b2sum invocation}.
+@end macro
+@weakHash{MD5}
+
+If a @var{file} is specified as @samp{-} or if no files are given
+@command{md5sum} computes the checksum for the standard input.
+@command{md5sum} can also determine whether a file and checksum are
+consistent. Synopsis:
+
+@example
+md5sum [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@command{md5sum} uses the @samp{Untagged output format}
+for each specified file, as described at @ref{cksum output modes}.
+
+The program accepts @ref{cksum common options}. Also see @ref{Common options}.
+
@exitstatus
--
2.41.0
