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 May 21, 2019
  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 ERRORS
 159 The
 160 .Fn SHA1_End
 161 function called with a null buf argument may fail and return NULL if:
 162 .Bl -tag -width Er
 163 .It Bq Er ENOMEM
 164 Insufficient storage space is available.
 165 .El
 166 .Pp
 167 The
 168 .Fn SHA1_File
 169 and
 170 .Fn SHA1_FileChunk
 171 may return NULL when underlying
 172 .Xr open 2 ,
 173 .Xr fstat 2 ,
 174 .Xr lseek 2 ,
 175 or
 176 .Xr SHA1_End 2
 177 fail.
 178 .Sh SEE ALSO
 179 .Xr md4 3 ,
 180 .Xr md5 3 ,
 181 .Xr ripemd 3 ,
 182 .Xr sha256 3 ,
 183 .Xr sha512 3 ,
 184 .Xr skein 3
 185 .Sh HISTORY
 186 These functions appeared in
 187 .Fx 4.0 .
 188 .Sh AUTHORS
 189 The core hash routines were implemented by Eric Young based on the
 190 published
 191 .Tn FIPS
 192 standards.
 193 .Sh BUGS
 194 The
 195 .Tn SHA1
 196 algorithm has been proven to be vulnerable to practical collision
 197 attacks and should not be relied upon to produce unique outputs,
 198 .Em nor should it be used as part of a new cryptographic signature scheme.
 199 .Pp
 200 The
 201 .Tn IA32
 202 (Intel) implementation of
 203 .Tn SHA-1
 204 makes heavy use of the
 205 .Ql bswapl
 206 instruction, which is not present on the original 80386.
 207 Attempts to use
 208 .Tn SHA-1
 209 on those processors will cause an illegal instruction trap.
 210 (Arguably, the kernel should simply emulate this instruction.)