lib/libmd/sha.3

   1 .\"
   2 .\" ----------------------------------------------------------------------------
   3 .\" "THE BEER-WARE LICENSE" (Revision 42):
   4 .\" <phk@FreeBSD.org> wrote this file.  As long as you retain this notice you
   5 .\" can do whatever you want with this stuff. If we meet some day, and you think
   6 .\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
   7 .\" ----------------------------------------------------------------------------
   8 .\"
   9 .\"     From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp
  10 .\" $FreeBSD: src/lib/libmd/sha.3,v 1.19 2005/06/16 19:01:06 ru Exp $
  11 .\"
  12 .Dd February 25, 1999
  13 .Dt SHA 3
  14 .Os
  15 .Sh NAME
  16 .Nm SHA_Init ,
  17 .Nm SHA_Update ,
  18 .Nm SHA_Final ,
  19 .Nm SHA_End ,
  20 .Nm SHA_File ,
  21 .Nm SHA_FileChunk ,
  22 .Nm SHA_Data ,
  23 .Nm SHA1_Init ,
  24 .Nm SHA1_Update ,
  25 .Nm SHA1_Final ,
  26 .Nm SHA1_End ,
  27 .Nm SHA1_File ,
  28 .Nm SHA1_FileChunk ,
  29 .Nm SHA1_Data
  30 .Nd calculate the FIPS 160 and 160-1 ``SHA'' message digests
  31 .Sh LIBRARY
  32 .Lb libmd
  33 .Sh SYNOPSIS
  34 .In sys/types.h
  35 .In sha.h
  36 .Ft void
  37 .Fn SHA_Init "SHA_CTX *context"
  38 .Ft void
  39 .Fn SHA_Update "SHA_CTX *context" "const void *data" "size_t len"
  40 .Ft void
  41 .Fn SHA_Final "unsigned char digest[20]" "SHA_CTX *context"
  42 .Ft "char *"
  43 .Fn SHA_End "SHA_CTX *context" "char *buf"
  44 .Ft "char *"
  45 .Fn SHA_File "const char *filename" "char *buf"
  46 .Ft "char *"
  47 .Fn SHA_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  48 .Ft "char *"
  49 .Fn SHA_Data "const void *data" "unsigned int len" "char *buf"
  50 .Ft void
  51 .Fn SHA1_Init "SHA_CTX *context"
  52 .Ft void
  53 .Fn SHA1_Update "SHA_CTX *context" "const void *data" "size_t len"
  54 .Ft void
  55 .Fn SHA1_Final "unsigned char digest[20]" "SHA_CTX *context"
  56 .Ft "char *"
  57 .Fn SHA1_End "SHA_CTX *context" "char *buf"
  58 .Ft "char *"
  59 .Fn SHA1_File "const char *filename" "char *buf"
  60 .Ft "char *"
  61 .Fn SHA1_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  62 .Ft "char *"
  63 .Fn SHA1_Data "const void *data" "unsigned int len" "char *buf"
  64 .Sh DESCRIPTION
  65 The
  66 .Li SHA_
  67 and
  68 .Li SHA1_
  69 functions calculate a 160-bit cryptographic checksum (digest)
  70 for any number of input bytes.
  71 A cryptographic checksum is a one-way
  72 hash function; that is, it is computationally impractical to find
  73 the input corresponding to a particular output.
  74 This net result is
  75 a
  76 .Dq fingerprint
  77 of the input-data, which does not disclose the actual input.
  78 .Pp
  79 .Tn SHA
  80 (or
  81 .Tn SHA-0 )
  82 is the original Secure Hash Algorithm specified in
  83 .Tn FIPS
  84 160.
  85 It was quickly proven insecure, and has been superseded by
  86 .Tn SHA-1 .
  87 .Tn SHA-0
  88 is included for compatibility purposes only.
  89 .Pp
  90 The
  91 .Fn SHA1_Init ,
  92 .Fn SHA1_Update ,
  93 and
  94 .Fn SHA1_Final
  95 functions are the core functions.
  96 Allocate an
  97 .Vt SHA_CTX ,
  98 initialize it with
  99 .Fn SHA1_Init ,
 100 run over the data with
 101 .Fn SHA1_Update ,
 102 and finally extract the result using
 103 .Fn SHA1_Final .
 104 .Pp
 105 .Fn SHA1_End
 106 is a wrapper for
 107 .Fn SHA1_Final
 108 which converts the return value to a 41-character
 109 (including the terminating '\e0')
 110 .Tn ASCII
 111 string which represents the 160 bits in hexadecimal.
 112 .Pp
 113 .Fn SHA1_File
 114 calculates the digest of a file, and uses
 115 .Fn SHA1_End
 116 to return the result.
 117 If the file cannot be opened, a null pointer is returned.
 118 .Fn SHA1_FileChunk
 119 is similar to
 120 .Fn SHA1_File ,
 121 but it only calculates the digest over a byte-range of the file specified,
 122 starting at
 123 .Fa offset
 124 and spanning
 125 .Fa length
 126 bytes.
 127 If the
 128 .Fa length
 129 parameter is specified as 0, or more than the length of the remaining part
 130 of the file,
 131 .Fn SHA1_FileChunk
 132 calculates the digest from
 133 .Fa offset
 134 to the end of file.
 135 .Fn SHA1_Data
 136 calculates the digest of a chunk of data in memory, and uses
 137 .Fn SHA1_End
 138 to return the result.
 139 .Pp
 140 When using
 141 .Fn SHA1_End ,
 142 .Fn SHA1_File ,
 143 or
 144 .Fn SHA1_Data ,
 145 the
 146 .Fa buf
 147 argument can be a null pointer, in which case the returned string
 148 is allocated with
 149 .Xr malloc 3
 150 and subsequently must be explicitly deallocated using
 151 .Xr free 3
 152 after use.
 153 If the
 154 .Fa buf
 155 argument is non-null it must point to at least 41 characters of buffer space.
 156 .Sh SEE ALSO
 157 .Xr md2 3 ,
 158 .Xr md4 3 ,
 159 .Xr md5 3 ,
 160 .Xr ripemd 3 ,
 161 .Xr sha256 3
 162 .Sh HISTORY
 163 These functions appeared in
 164 .Fx 4.0 .
 165 .Sh AUTHORS
 166 The core hash routines were implemented by Eric Young based on the
 167 published
 168 .Tn FIPS
 169 standards.
 170 .Sh BUGS
 171 No method is known to exist which finds two files having the same hash value,
 172 nor to find a file with a specific hash value.
 173 There is on the other hand no guarantee that such a method does not exist.
 174 .Pp
 175 The
 176 .Tn IA32
 177 (Intel) implementation of
 178 .Tn SHA-1
 179 makes heavy use of the
 180 .Ql bswapl
 181 instruction, which is not present on the original 80386.
 182 Attempts to use
 183 .Tn SHA-1
 184 on those processors will cause an illegal instruction trap.
 185 (Arguably, the kernel should simply emulate this instruction.)