lib/libc/hash/sha1/sha1.3

   1 .\"     $NetBSD: sha1.3,v 1.4 2009/10/22 01:38:18 snj Exp $
   2 .\"     $OpenBSD: sha1.3,v 1.9 1998/03/07 22:18:12 millert Exp $
   3 .\"
   4 .\" Copyright (c) 1997, 2004 Todd C. Miller <Todd.Miller@courtesan.com>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\" See http://csrc.nist.gov/fips/fip180-1.txt for the detailed standard
  19 .\"
  20 .Dd July 10, 1997
  21 .Dt SHA1 3
  22 .Os
  23 .Sh NAME
  24 .Nm SHA1Init ,
  25 .Nm SHA1Update ,
  26 .Nm SHA1Final ,
  27 .Nm SHA1Transform ,
  28 .Nm SHA1End ,
  29 .Nm SHA1File ,
  30 .Nm SHA1Data
  31 .Nd calculate the NIST Secure Hash Algorithm
  32 .Sh SYNOPSIS
  33 .In sys/types.h
  34 .In sha1.h
  35 .Ft void
  36 .Fn SHA1Init "SHA1_CTX *context"
  37 .Ft void
  38 .Fn SHA1Update "SHA1_CTX *context" "const uint8_t *data" "u_int len"
  39 .Ft void
  40 .Fn SHA1Final "uint8_t digest[20]" "SHA1_CTX *context"
  41 .Ft void
  42 .Fn SHA1Transform "uint32_t state[5]" "uint8_t buffer[64]"
  43 .Ft "char *"
  44 .Fn SHA1End "SHA1_CTX *context" "char *buf"
  45 .Ft "char *"
  46 .Fn SHA1File "char *filename" "char *buf"
  47 .Ft "char *"
  48 .Fn SHA1Data "uint8_t *data" "size_t len" "char *buf"
  49 .Sh DESCRIPTION
  50 The SHA1 functions implement the NIST Secure Hash Algorithm (SHA-1),
  51 FIPS PUB 180-1.
  52 SHA-1 is used to generate a condensed representation
  53 of a message called a message digest.
  54 The algorithm takes a
  55 message less than 2^64 bits as input and produces a 160-bit digest
  56 suitable for use as a digital signature.
  57 .Pp
  58 The SHA1 functions are considered to be more secure than the
  59 .Xr md4 3
  60 and
  61 .Xr md5 3
  62 functions with which they share a similar interface.
  63 .Pp
  64 The
  65 .Fn SHA1Init
  66 function initializes a SHA1_CTX
  67 .Ar context
  68 for use with
  69 .Fn SHA1Update ,
  70 and
  71 .Fn SHA1Final .
  72 The
  73 .Fn SHA1Update
  74 function adds
  75 .Ar data
  76 of length
  77 .Ar len
  78 to the SHA1_CTX specified by
  79 .Ar context .
  80 .Fn SHA1Final
  81 is called when all data has been added via
  82 .Fn SHA1Update
  83 and stores a message digest in the
  84 .Ar digest
  85 parameter.
  86 When a null pointer is passed to
  87 .Fn SHA1Final
  88 as first argument only the final padding will be applied and the
  89 current context can still be used with
  90 .Fn SHA1Update .
  91 .Pp
  92 The
  93 .Fn SHA1Transform
  94 function is used by
  95 .Fn SHA1Update
  96 to hash 512-bit blocks and forms the core of the algorithm.
  97 Most programs should use the interface provided by
  98 .Fn SHA1Init ,
  99 .Fn SHA1Update
 100 and
 101 .Fn SHA1Final
 102 instead of calling
 103 .Fn SHA1Transform
 104 directly.
 105 .Pp
 106 The
 107 .Fn SHA1End
 108 function is a front end for
 109 .Fn SHA1Final
 110 which converts the digest into an
 111 .Tn ASCII
 112 representation of the 160 bit digest in hexadecimal.
 113 .Pp
 114 The
 115 .Fn SHA1File
 116 function calculates the digest for a file and returns the result via
 117 .Fn SHA1End .
 118 If
 119 .Fn SHA1File
 120 is unable to open the file a NULL pointer is returned.
 121 .Pp
 122 The
 123 .Fn SHA1Data
 124 function
 125 calculates the digest of an arbitrary string and returns the result via
 126 .Fn SHA1End .
 127 .Pp
 128 For each of the
 129 .Fn SHA1End ,
 130 .Fn SHA1File ,
 131 and
 132 .Fn SHA1Data
 133 functions the
 134 .Ar buf
 135 parameter should either be a string of at least 41 characters in
 136 size or a NULL pointer.
 137 In the latter case, space will be dynamically
 138 allocated via
 139 .Xr malloc 3
 140 and should be freed using
 141 .Xr free 3
 142 when it is no longer needed.
 143 .Sh EXAMPLES
 144 The follow code fragment will calculate the digest for
 145 the string "abc" which is ``0xa9993e36476816aba3e25717850c26c9cd0d89d''.
 146 .Bd -literal -offset indent
 147 SHA1_CTX sha;
 148 uint8_t results[20];
 149 char *buf;
 150 int n;
 151
 152 buf = "abc";
 153 n = strlen(buf);
 154 SHA1Init(\*[Am]sha);
 155 SHA1Update(\*[Am]sha, (uint8_t *)buf, n);
 156 SHA1Final(results, \*[Am]sha);
 157
 158 /* Print the digest as one long hex value */
 159 printf("0x");
 160 for (n = 0; n \*[Lt] 20; n++)
 161         printf("%02x", results[n]);
 162 putchar('\\n');
 163 .Ed
 164 .Pp
 165 Alternately, the helper functions could be used in the following way:
 166 .Bd -literal -offset indent
 167 SHA1_CTX sha;
 168 uint8_t output[41];
 169 char *buf = "abc";
 170
 171 printf("0x%s", SHA1Data(buf, strlen(buf), output));
 172 .Ed
 173 .Sh SEE ALSO
 174 .\"     .Xr sha1 1 ,
 175 .Xr md5 1 ,
 176 .Xr md4 3 ,
 177 .Xr md5 3
 178 .Pp
 179 .Rs
 180 .%A J. Burrows
 181 .%T The Secure Hash Standard
 182 .%O FIPS PUB 180-1
 183 .Re
 184 .Sh HISTORY
 185 The SHA-1 functions appeared in
 186 .Nx 1.4 .
 187 .Sh AUTHORS
 188 This implementation of SHA-1 was written by Steve Reid.
 189 .Pp
 190 The
 191 .Fn SHA1End ,
 192 .Fn SHA1File ,
 193 and
 194 .Fn SHA1Data
 195 helper functions are derived from code written by Poul-Henning Kamp.
 196 .Sh BUGS
 197 This implementation of SHA-1 has not been validated by NIST
 198 and as such is not in official compliance with the standard.
 199 .Pp
 200 If a message digest is to be copied to a multi-byte type (ie:
 201 an array of five 32-bit integers) it will be necessary to
 202 perform byte swapping on little endian machines such as the i386, alpha,
 203 and VAX.