Second commit

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 214 insertions, 0 deletions

diff --git a/rawshake128sum.1 b/rawshake128sum.1
new file mode 100644
index 0000000..d3fa614
--- /dev/null
+++ b/rawshake128sum.1
@@ -0,0 +1,214 @@
+.TH RAWSHAKE128SUM 1 anysum
+.SH NAME
+rawshake128sum - compute or verify against multiple RawSHAKE-128 hashes
+
+.SH SYNOPSIS
+.B rawshake128sum
+.RB [ -c
+.RB [ -w ]]
+.RB [ -N
+.IR length ]
+.RB [ -W
+.IR options ]\ ...
+.RB [ -z ]
+.RI [ file ]\ ...
+
+.SH DESCRIPTION
+The
+.B rawshake128sum
+utility calculates and prints or checks RawSHAKE-128
+checksums.
+.PP
+The
+.B rawshake128sum
+utility can also check a file against multiple RawSHAKE-128
+checksums, and check that the file matches at least one
+of the listed checksums.
+
+.SH OPTIONS
+The rawshake128sum utility conforms to the Base Definitions
+volume of POSIX.1-2017,
+.IR "Section 12.2" ,
+.IR "Utility Syntax Guidelines" .
+.PP
+The following options are supported:
+.TP
+.B -b
+Equivalent to
+.BR "-W output=binary" .
+.TP
+.B -c
+Verify the the files listed in file against the
+checksums listed on the same lines. The file
+shall be formatted as the output of the utility
+when this option is not used. See the
+.B STDOUT
+section for more information. If a file is listed
+multiple times, it need only match one of the
+checksums listed for the file.
+
+The length of the listed checksums need not match
+the length output by this utility; before the
+checksums are compared, they are truncated to the
+shorter of the two checksums.
+.TP
+.B -l
+Equivalent to
+.BR "-W output=lowercase" .
+.TP
+.BR -N \ \fIlength\fP
+The hash output size in bits. (Default is 128.)
+.TP
+.B -u
+Equivalent to
+.BR "-W output=uppercase" .
+.TP
+.B -v
+Print Keccak parameters to standard error.
+.TP
+.BR -W \ \fIoptions\fP
+Comma-sepearated list of implementation-specific
+options. The following options are supported:
+.RS
+.TP
+.BI output= format
+.I format
+shall be
+.RB \(dq lowercase \(dq
+if the checksums shall be printed in lowercase
+hexadecimal format (default),
+.RB \(dq uppercase \(dq
+for uppercase hexadecimal format, or
+.RB \(dq binary \(dq
+for binary format without anything but the
+checksum printed to standard output. This
+option is ignored if the
+.B -c
+option is used.
+.TP
+.BI input= format
+.I format
+shall be
+.RB \(dq binary \(dq
+if the files are be read in binary mode,
+.RB \(dq text \(dq
+if the files shall be read in text mode, or
+.RB \(dq hexadecimal \(dq
+they shall be decoded from hexadecimal to
+binary. If the
+.B -c
+option is used, the mode specification
+associated with a file is overrides this
+behaviour for that file if the line
+specifies hexadecimal mode.
+.TP
+.B recursive
+If a
+.I file
+operand is a directory, the checksum is computed for
+all files recursively. This option is ignored if the
+.B -c
+option is used.
+.TP
+.B no-recursive
+The utility shall traverse directories.
+(This is the default behaviour).
+.RE
+.TP
+.B -w
+Warn about, but skip, lines that are not properly
+formatted.
+.TP
+.B -x
+Equivalent to
+.BR "-W input=hexadeximal" .
+.TP
+.B -z
+Use NUL byte as line ending instead of LF.
+.PP
+There is no difference between binary mode and text mode.
+
+.SH OPERANDS
+The following operand is supported:
+.TP
+.I file
+The file to read and compute the checksum for, or if the
+.B -c
+option is used, use as the listing of files and checksums
+to verify the files against. If dash
+.RB (' - ')
+is used or if no file operand is specified, standard input
+will be used.
+
+.SH STDOUT
+If the
+.B -c
+option is not used, the utility shall print the following
+line for each calculated checksum, however there are options
+that modify the format; see the
+.B OPTIONS
+section for more information:
+.PP
+.RS
+.B \(dq%s %c%s\en\(dq,
+.RI < hash >\fB,\fP
+.RI < mode >\fB,\fP
+.RI < file >
+.RE
+.PP
+where
+.I mode
+is SP (' ') for text mode, an asterisk
+.RB (' * ')
+for binary mode, or a pound sign
+.RB (' # ')
+for hexadecimal mode; however if there is no difference
+between binary mode and text mode and either is selected,
+SP (' ') (text mode) is used.
+.PP
+If the
+.B -c
+option the output shall be on the format:
+.PP
+.RS
+.B \(dq%s: %s\en\(dq,
+.RI < file >\fB,\fP
+.RI < validity >
+.RE
+.PP
+where
+.I validity
+is an implementation specified string
+that describes whether the checksum was valid (possibly
+with remarks), the file did not exist, the file could
+not be read (possibly with error information), or if
+the checksum was invalid or could not be compared
+(possibly with remarks). The
+.B -z
+option does not modify the line ending.
+
+.SH EXIT STATUS
+The following exit values are returned:
+.TP
+0
+Successful completion.
+.TP
+1
+Checksums did not match or a file did not exist.
+.TP
+2
+An error occurred.
+
+.SH NOTES
+Other implementations do not necessarily recognise the
+hexadecimal mode specifier
+.RB (' # ')
+in checksum list files.
+.PP
+The
+.B -c
+option accepting truncated checksums is an
+implementation-specific behaviour.
+
+.SH SEE ALSO
+.BR anysum (1)