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 February 6, 2023
  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 SHA (or SHA-0) is the original Secure Hash Algorithm specified in FIPS 160.
  80 It was quickly proven insecure, and has been superseded by SHA-1.
  81 SHA-0 is included for compatibility purposes only.
  82 .Pp
  83 The
  84 .Fn SHA1_Init ,
  85 .Fn SHA1_Update ,
  86 and
  87 .Fn SHA1_Final
  88 functions are the core functions.
  89 Allocate an
  90 .Vt SHA_CTX ,
  91 initialize it with
  92 .Fn SHA1_Init ,
  93 run over the data with
  94 .Fn SHA1_Update ,
  95 and finally extract the result using
  96 .Fn SHA1_Final ,
  97 which will also erase the
  98 .Vt SHA_CTX .
  99 .Pp
 100 .Fn SHA1_End
 101 is a wrapper for
 102 .Fn SHA1_Final
 103 which converts the return value to a 41-character
 104 (including the terminating '\e0')
 105 ASCII string which represents the 160 bits in hexadecimal.
 106 .Pp
 107 .Fn SHA1_File
 108 calculates the digest of a file, and uses
 109 .Fn SHA1_End
 110 to return the result.
 111 If the file cannot be opened, a null pointer is returned.
 112 .Fn SHA1_FileChunk
 113 is similar to
 114 .Fn SHA1_File ,
 115 but it only calculates the digest over a byte-range of the file specified,
 116 starting at
 117 .Fa offset
 118 and spanning
 119 .Fa length
 120 bytes.
 121 If the
 122 .Fa length
 123 parameter is specified as 0, or more than the length of the remaining part
 124 of the file,
 125 .Fn SHA1_FileChunk
 126 calculates the digest from
 127 .Fa offset
 128 to the end of file.
 129 .Fn SHA1_Data
 130 calculates the digest of a chunk of data in memory, and uses
 131 .Fn SHA1_End
 132 to return the result.
 133 .Pp
 134 When using
 135 .Fn SHA1_End ,
 136 .Fn SHA1_File ,
 137 or
 138 .Fn SHA1_Data ,
 139 the
 140 .Fa buf
 141 argument can be a null pointer, in which case the returned string
 142 is allocated with
 143 .Xr malloc 3
 144 and subsequently must be explicitly deallocated using
 145 .Xr free 3
 146 after use.
 147 If the
 148 .Fa buf
 149 argument is non-null it must point to at least 41 characters of buffer space.
 150 .Sh ERRORS
 151 The
 152 .Fn SHA1_End
 153 function called with a null buf argument may fail and return NULL if:
 154 .Bl -tag -width Er
 155 .It Bq Er ENOMEM
 156 Insufficient storage space is available.
 157 .El
 158 .Pp
 159 The
 160 .Fn SHA1_File
 161 and
 162 .Fn SHA1_FileChunk
 163 may return NULL when underlying
 164 .Xr open 2 ,
 165 .Xr fstat 2 ,
 166 .Xr lseek 2 ,
 167 or
 168 .Xr SHA1_End 3
 169 fail.
 170 .Sh SEE ALSO
 171 .Xr md4 3 ,
 172 .Xr md5 3 ,
 173 .Xr ripemd 3 ,
 174 .Xr sha256 3 ,
 175 .Xr sha512 3 ,
 176 .Xr skein 3
 177 .Sh HISTORY
 178 These functions appeared in
 179 .Fx 4.0 .
 180 .Sh AUTHORS
 181 The core hash routines were implemented by Eric Young based on the
 182 published
 183 FIPS standards.
 184 .Sh BUGS
 185 The SHA1 algorithm has been proven to be vulnerable to practical collision
 186 attacks and should not be relied upon to produce unique outputs,
 187 .Em nor should it be used as part of a new cryptographic signature scheme.