.\" This man page was written by:
.\"
.\"	 Landon Curt Noll  chongo (was here) /\../\
.\"	 http://www.isthe.com/chongo/index.html
.\"
.\" Share and enjoy! :-)
.\"
.\" @(#) $Revision: 13.1 $
.\" @(#) $Id: shs.1,v 13.1 2006/08/14 03:16:33 chongo Exp $
.\" @(#) $Source: /usr/local/src/cmd/hash/RCS/shs.1,v $
.\"
.\" This man page has been placed in the public domain.  Please do not
.\" copyright this man page.
.\"
.\" LANDON CURT NOLL DISCLAIMS ALL WARRANTIES WITH  REGARD  TO
.\" THIS  SOFTWARE,  INCLUDING  ALL IMPLIED WARRANTIES OF MER-
.\" CHANTABILITY AND FITNESS.  IN NO EVENT SHALL  LANDON  CURT
.\" NOLL  BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM  LOSS  OF
.\" USE,  DATA  OR  PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR  IN
.\" CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" See shsdrvr.c for version and modification history.
.\"
.TH SHS 1  LOCAL
.SH NAME
shs1, shs, sha1, sha \- Secure Hash Standard
.SH SYNOPSIS
.B shs1
[\fB\-cCdhiqtx\fP]
[\fB\-m num\fP]
.br
     [\fB\-p prefix\fP]
[\fB\-P prefile\fP]
[\fB\-s str\fP]
file\ ...
.sp
.B shs
[\fB\-cCdhiqtx\fP]
[\fB\-m num\fP]
.br
    [\fB\-p prefix\fP]
[\fB\-P prefile\fP]
[\fB\-s str\fP]
file\ ...
.sp
.B sha1
[\fB\-cCdhiqtx\fP]
[\fB\-m num\fP]
.br
     [\fB\-p prefix\fP]
[\fB\-P prefile\fP]
[\fB\-s str\fP]
file\ ...
.sp
.B sha
[\fB\-cCdhiqtx\fP]
[\fB\-m num\fP]
.br
    [\fB\-p prefix\fP]
[\fB\-P prefile\fP]
[\fB\-s str\fP]
file\ ...
.SH DESCRIPTION
The
.B sha1
utility implements the Secure Hash Algorithm-1 (\fISHA-1\fP).
It produces 160-bit Secure Hash Digests of files, strings or data
read on stdin.
If no
.B file
is given, and
no string is to be digested (\fB\-s\fP)
then stdin will be digested.
By default, a digests are printed as 40 hex characters without a leading
.IR 0x .
.PP
The
.B shs1
utility is the same as
.B sha1
and is linked for backward compatibility.
.PP
The Secure Hash Standard-1 (\fISHS-1\fP) is a United States
Department of Commerce National Institute of Standards and Technology
approved standard (FIPS Pub 180-1) for secure hashing.
The
.I SHS-1
is designed to work with the Digital Signature Standard (\fIDSS\fP).
The Secure Hash Algorithm (\fISHA-1\fP)
specified in this standard is
necessary to ensure the security of the Digital Signature Standard.
When a message of length < 2^64 bits is input, the
.I SHA-1
produces a 160-bit representation of the message called the message digest.
The message digest is used during generation of a signature for the message.
The
.I SHA-1
is designed to have the following properties: it is
computationally infeasible to recover a message corresponding to a
given message digest, or to find two different messages which
produce the same message digest.
.PP
On 1994 May 31, the United States Department of Commerce
National Institute of Standards and Technology published a
technical modification (FIPS Pub 180-1) to the Secure Hash Standard known
as Secure Hash Algorithm-1 (\fISHA-1\fP).
The
.B sha1
utility implements the new Secure Hash Algorithm-1 (\fISHA-1\fP)
as specified by (FIPS Pub 180-1).
The
.B sha
utility implements the old Secure Hash Algorithm (\fISHA\fP)
as specified by (FIPS Pub 180).
It uses the same arguments and interface as
.BR sha1 .
This utility is provided for backward compatibility with
version at or before 2.10.1.
.PP
The
.B shs
utility is the same as
.B sha
and is linked for backward compatibility.
.PP
If a
.B str
(string) argument is given, then the digest for
.BR str ,
followed by a space, followed by
.B str
enclosed double quotes is written to stdout.
Any
.B file
arguments are ignored.
.PP
If one or more
.B file
if given, a separate digest if produced for each file.
By default,
.B file
digests are followed by a space and the filename.
.PP
If no
.B str
or
.B file
arguments are given, then a digest of stdin is written to stdout.
.PP
.TP
.B \-c
Print C style hex digests with a leading \fI0x\fP.
.TP
.B \-C
When printing multi digests (see \fB\-d\fP or \fB\-m num\fP), do not
separate digests with spaces.  When combined with \fB\-c\fP and \fB\-q\fP,
the output is only a single long hex value.
.TP
.B \-d
Shorthand for \fB\-m 2\fP.
Used for backward compatibility.
.TP
.B \-h
Print a help and usage message.
.TP
.B \-i
Compute inode digests of files.
.sp
Prepend the filename and various inode information to the file data
being digested.
The inode information prepended includes information
such as the device (\fIst_dev\fP),
inode number (\fIst_ino\fP),
mode (\fIst_mode\fP),
link count (\fIst_nlink\fP),
uid (\fIst_uid\fP),
gid (\fIst_gid\fP),
size (\fIst_size\fP),
modification time (\fIst_mtime\fP) and
change time (\fIst_ctime\fP).
The prepended data is padded with zeros to make it a multiple of 64
bytes long.
Both a
.BR stat (2)
and a
.BR lstat (2)
information are both used.
.sp
The \fB\-i\fP flag allows one to include various inode information in
the digest.
This option is useful in detecting file tampering.
For example, the following will produce different digests:
.sp
.in +0.5i
.nf
sha1 \-i /tmp/chongo
cp /tmp/chongo /tmp/was_here
\^... misc funny business ...
cp /tmp/was_here /tmp/chongo
sha1 \-i /tmp/chongo
.fi
.in -0.5i
.sp
Note that a \fB\-i\fP digest is not portable to other systems.
This is because inode information will likely change as the
contents of a file are copied from machine to machine.
.sp
To mark a \fB\-i\fP digest as a special value, \fI.0\fP is
prepended onto the digest output.
.sp
One may only compute inode digests of files.
Use of
.B \-i
disables reading from stdin.
The
.B \-i
flag is not compatible with
.BR \-s .
.TP
.BI \-m num
Compute multiple digests in parallel.
.sp
Every \fBnum\fP-th octet of the prefix (if given) and data are processed
by a separate digest.
Each successive octet is assigned an index starting with 0.
The i-th digest is taken from all octets with an index of i mod \fBnum\fP.
.sp
The result of a multiple digest is a hash that is \fBnum\fP times
as long as a standard digest.
.TP
.BI \-p prefix
.TP
.BI \-P prefile
Insert a prefix into the data to be digested.
.sp
By using \fB\-p\fP\fIprefix\fP, one may prepend any set of data with a
string.
The digest produced is equivalent to digest that is
produced with the string pretended to the data.
Thus the following two commands produce the same digest:
.sp
.in +0.5i
.nf
sha1 \-p curds \-s whey
sha1 \-s curdswhey
.fi
.in -0.5i
.sp
By use of the \fB\-P\fP\fIprefile\fP interface, one may prepend using
up to the 32k of a file.
This interface allows one to prepend using binary data.
The following produces the same digest:
.sp
.in +0.5i
.nf
sha1 \-P /usr/bin/awk /bin/ls
dd if=/usr/bin/awk of=/tmp/foo bs=32k count=1
cat /tmp/foo /bin/ls > /tmp/ls
sha1 /tmp/ls
.fi
.in -0.5i
.sp
Knowledge of the original prepend data is only kept in
the digest.
Thus one may use the prepend string as a ``salt'' making it intractable
for someone else to reproduce the digest of a file without knowledge
of the prepend data.
.sp
This feature works in conjunction all modes of operation except
the \fB\-t\fP and \fB\-x\fP modes.
.TP
.B \-q
Output only digests.
The filename or string will not be written to stdout.
.TP
.BR \-s str
Digest \fIstr\fP as if it were a string.
.sp
The trailing NUL byte is not digested.
No files are digested.
The \fIstr\fP is written to stdout enclosed in double quotes.
.TP
.BR \-t
Time the user cpu seconds needed to digest several megabytes of data.
The number of megabytes,
followed by the digest produced,
followed by the number of user cpu seconds
followed by the number of characters per user second is written to stdout.
.sp
On some systems with certain virtual memory characteristics,
you may need to run the performance test several times, ignoring the
first result.
The default amount of data tested is 16 megabytes.
On some systems, this amount may differ.
One may change the number of megabytes processed by changing the value of
TEST_MEG in the file shs1drvr.c (or shsdrvr.c) and recompiling.
.TP
.BR \-v
Print the version.
.TP
.BR \-x
Perform an extended standard SHS-1 test suite.
.sp
The test suite will first look in the current directory for
.IR file1 .
If it is not found, it will look in ${DESTDIR} (usually
.IR /usr/local/lib/shs ).
It is assumes that
.I file2
is in the same location as
.IR file1 .
.sp
The standard test suite been extended.
The initial string now says:
.sp
.in +0.5i
.nf
sha1 test suite results
.fi
.in -0.5i
.sp
instead of:
.sp
.in +0.5i
.nf
SHA test suite results
.fi
.in -0.5i
.sp
to reflect the utility name instead of the algorithm implemented.
This also helps distinguish this version from much older
versions which did not have the
.B -v
flag.
Also the original test file
.I foo
which contained the string  "\fIabc\fP" (with no newline) was renamed
.IR file1 .
.SH "SEE ALSO"
.BR md5 (1),
.BR stat (2),
.BR lstat (2)
.SH FILES
.nf
\^./file1			default test file location
\^./file2			default test file location
${DESTDIR}/file1	alternate test file location
${DESTDIR}/file2	alternate test file location
.fi
.sp
The typical value of ${DESTDIR} is \fI/usr/local/lib/shs\fP,
or \fI/usr/local/lib\fP.
.SH AUTHOR
.nf
Much of this code was written, re-written or modified by:

    Landon Curt Noll	(chongo was here)  /\\../\\
    http://www.isthe.com/chongo/index.html

This code is based on code by Peter C. Gutmann.  Much thanks goes
to Peter C. Gutman (pgut1@cs.aukuni.ac.nz) , Shawn A. Clifford
(sac@eng.ufl.edu), Pat Myrto (pat@rwing.uucp), Colin Plumb
(colin@nyx10.cs.du.edu), Rich Schroeppel (rcs@cs.arizona.edu)
and others who wrote and/or worked on the original code.
.fi
.SH NOTICE
LANDON CURT NOLL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
IN NO EVENT SHALL LANDON CURT NOLL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
.SH BUGS
The command:
.sp
.in +0.5i
.nf
sha1 -s '/\\"O/\\'
.fi
.in -0.5i
.sp
writes to stdout, the following line:
.sp
.in +0.5i
.nf
945a6306a6d7caee4a28fabb36838750a673fc9f "/\"O/\"
.fi
.in -0.5i
.sp
The string written in double quotes by
.B \-s
may not be a valid string according to C or shell syntax.