c_cpp/etc/md5_sha/README

   1 Landon Curt Noll (chongo was here) /\../\
   2 http://www.isthe.com/chongo/index.html
   3
   4 @(#) $Revision: 13.1 $
   5 @(#) $Id: README,v 13.1 2006/08/14 03:16:33 chongo Exp $
   6 @(#) $Source: /usr/local/src/cmd/hash/RCS/README,v $
   7
   8 Lanndon Curt Noll (chongo was here) /\oo/\
   9 http://www.isthe.com/chongo/index.html
  10
  11 Share and enjoy! :-)
  12
  13 This is an implementation of the Secure Hash Standard-1 (SHS1)
  14 as well as implementation of the RSA Data Security, Inc.
  15                 MD5 Message-Digest Algorithm
  16
  17 The digests produced from strings (-s string), files or stdin are
  18 identical to the original programs.  The command line and output
  19 interface are upward compatible as well.  Users of the original shs
  20 program may replace it with this version has their existing use
  21 and digests will be preserved.
  22
  23 To build:
  24
  25     <<Edit the Makefile as needed>>
  26     make all
  27     make test
  28
  29 To install:
  30
  31     make install
  32
  33 This implementation has been improved over the original posting in
  34 a number of ways:
  35
  36   * performance
  37
  38     On some platforms, the characters per second processed have been
  39     increased by a factor of almost 3.5 times the original postings.
  40
  41   * inode digests
  42
  43     This flag allows one to include the filename and various inode
  44     information in the digest.  This option is useful in detecting
  45     file tampering where the contents of the file was later restored.
  46
  47   * version string
  48
  49     The -v flag prints the version.
  50
  51   * test suites
  52
  53     The standard test suite (-x) been changed.  The initial string
  54     for shs now says 'shs test suite results' instead of 'SHA test
  55     suite results'.  While it is true that it we testing the
  56     algorithm the program is called shs.  The initial string for
  57     md5 now says 'md5 test suite results' instead of 'MD5 test
  58     suite results'.  These changes also helps distinguish this
  59     version from much older versions which did not have the -v
  60     (print version) flag.
  61
  62     The original test file "foo" which contained the string "abc" (with
  63     no newline) was renamed file1.
  64
  65     To avoid filename conflicts, the shs and md5 verify.data files
  66     were renamed shs.data and md5.data respectively.
  67
  68     A new file, "file2" was added to the standard test suite.  This
  69     file is larger than an internal read and thus helps test file
  70     processing.  The contents of this file are two highly munged
  71     copies of the original README.  The munging to prevent people
  72     from using this file as documentation.
  73
  74     The test suite will first look in the current directory for
  75     "file1".  If it is not found, it will look in ${DESTDIR}
  76     (usually /usr/local/lib/{shs,md5}) as defined in the makefile.
  77     It is assumes that "file2" is in the same location as "file1".
  78
  79     With the exception of the initial title line and the addition
  80     of file2, the md5.data and shs.data file is identical to the
  81     respective originals.
  82
  83   * prepend data
  84
  85     By using '-p string' one may prepend any set of data with a
  86     string.  The digest produced is equivalent to digest that is
  87     produced with the string pretended to the data.  By use of the
  88     '-P file' interface, one may prepend using up to the 32k of a
  89     file.  This interface allows one to prepend using binary data.
  90
  91   * performance test suite
  92
  93     The -t performance test has been changed to compute user cpu
  94     time.  Older tests looked at wall clock time.  Variations in
  95     system load produced variations in the reported performance.
  96
  97     The test length was increased to 16 megabytes.  One may change
  98     the number of megabytes processed by changing the value of
  99     TEST_MEG in the file shsdrvr.c or md5drvr.c.
 100
 101     On some systems with certain virtual memory characteristics,
 102     you may need to run the performance test 3 times, ignoring the
 103     first result.
 104
 105   * quiet mode
 106
 107     When -q is given, only digests are printed.
 108
 109   * C-type hex values.
 110
 111     When -c is given, digests are prepended by 0x so that they
 112     may be directly used by programs such as calc:
 113
 114                 ftp://ftp.uu.net/pub/calc
 115
 116     that want C-style hex values.
 117
 118   * multiple digests
 119
 120     When -m num is given, num multiple digests are computed in parallel.
 121     The prepend data (if any) and the input data are divided so that
 122     each num-th byte is digested by a separate hash.  The result is
 123     a hash value that is num times as long as a single digest.
 124
 125     The -d is a historic (pre version 3) shorthand for -m 2.
 126
 127     When -C is given, the digests are cancatinated together to form
 128     one large hex value.
 129
 130   * use by other programs
 131
 132     External programs may use the hash and I/O modules without all of
 133     the other structure.
 134
 135         To use SHS grab:    shs.c,  shs.h and if I/O is needed shsio.c.
 136         To use SHS1 grab:  shs1.c, shs1.h and if I/O is needed shs1io.c.
 137         To use MD5 grab:    md5.c,  md5.h and if I/I is needed md5io.c.
 138
 139     One will need to declare:
 140
 141         char *program;          /* program = argv[0] */
 142         int debug = 0;          /* 1 => enable debugging */
 143
 144 See shs1drvr.c (and shsdrvr.c) and md5drvr.c for version information.  See
 145 the man pages shs.1 and md5.1 for other details.  Also see README.shs and
 146 README.md5.  Happy hashing!