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$
  11 .\"
  12 .Dd July 20, 2018
  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 unsigned char *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 unsigned char *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 unsigned char *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 unsigned char *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 which will also erase the
 105 .Vt SHA_CTX .
 106 .Pp
 107 .Fn SHA1_End
 108 is a wrapper for
 109 .Fn SHA1_Final
 110 which converts the return value to a 41-character
 111 (including the terminating '\e0')
 112 .Tn ASCII
 113 string which represents the 160 bits in hexadecimal.
 114 .Pp
 115 .Fn SHA1_File
 116 calculates the digest of a file, and uses
 117 .Fn SHA1_End
 118 to return the result.
 119 If the file cannot be opened, a null pointer is returned.
 120 .Fn SHA1_FileChunk
 121 is similar to
 122 .Fn SHA1_File ,
 123 but it only calculates the digest over a byte-range of the file specified,
 124 starting at
 125 .Fa offset
 126 and spanning
 127 .Fa length
 128 bytes.
 129 If the
 130 .Fa length
 131 parameter is specified as 0, or more than the length of the remaining part
 132 of the file,
 133 .Fn SHA1_FileChunk
 134 calculates the digest from
 135 .Fa offset
 136 to the end of file.
 137 .Fn SHA1_Data
 138 calculates the digest of a chunk of data in memory, and uses
 139 .Fn SHA1_End
 140 to return the result.
 141 .Pp
 142 When using
 143 .Fn SHA1_End ,
 144 .Fn SHA1_File ,
 145 or
 146 .Fn SHA1_Data ,
 147 the
 148 .Fa buf
 149 argument can be a null pointer, in which case the returned string
 150 is allocated with
 151 .Xr malloc 3
 152 and subsequently must be explicitly deallocated using
 153 .Xr free 3
 154 after use.
 155 If the
 156 .Fa buf
 157 argument is non-null it must point to at least 41 characters of buffer space.
 158 .Sh SEE ALSO
 159 .Xr md4 3 ,
 160 .Xr md5 3 ,
 161 .Xr ripemd 3 ,
 162 .Xr sha256 3 ,
 163 .Xr sha512 3 ,
 164 .Xr skein 3
 165 .Sh HISTORY
 166 These functions appeared in
 167 .Fx 4.0 .
 168 .Sh AUTHORS
 169 The core hash routines were implemented by Eric Young based on the
 170 published
 171 .Tn FIPS
 172 standards.
 173 .Sh BUGS
 174 No method is known to exist which finds two files having the same hash value,
 175 nor to find a file with a specific hash value.
 176 There is on the other hand no guarantee that such a method does not exist.
 177 .Pp
 178 The
 179 .Tn IA32
 180 (Intel) implementation of
 181 .Tn SHA-1
 182 makes heavy use of the
 183 .Ql bswapl
 184 instruction, which is not present on the original 80386.
 185 Attempts to use
 186 .Tn SHA-1
 187 on those processors will cause an illegal instruction trap.
 188 (Arguably, the kernel should simply emulate this instruction.)