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