lib/libmd/sha512.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 .\"
  11 .Dd February 3, 2023
  12 .Dt SHA512 3
  13 .Os
  14 .Sh NAME
  15 .Nm SHA512_Init ,
  16 .Nm SHA512_Update ,
  17 .Nm SHA512_Final ,
  18 .Nm SHA512_End ,
  19 .Nm SHA512_File ,
  20 .Nm SHA512_FileChunk ,
  21 .Nm SHA512_Data ,
  22 .Nm SHA384_Init ,
  23 .Nm SHA384_Update ,
  24 .Nm SHA384_Final ,
  25 .Nm SHA384_End ,
  26 .Nm SHA384_File ,
  27 .Nm SHA384_FileChunk ,
  28 .Nm SHA384_Data ,
  29 .Nm SHA512_224_Init ,
  30 .Nm SHA512_224_Update ,
  31 .Nm SHA512_224_Final ,
  32 .Nm SHA512_224_End ,
  33 .Nm SHA512_224_File ,
  34 .Nm SHA512_224_FileChunk ,
  35 .Nm SHA512_224_Data
  36 .Nm SHA512_256_Init ,
  37 .Nm SHA512_256_Update ,
  38 .Nm SHA512_256_Final ,
  39 .Nm SHA512_256_End ,
  40 .Nm SHA512_256_File ,
  41 .Nm SHA512_256_FileChunk ,
  42 .Nm SHA512_256_Data
  43 .Nd calculate the FIPS 180-4 ``SHA-512'' family of message digests
  44 .Sh LIBRARY
  45 .Lb libmd
  46 .Sh SYNOPSIS
  47 .In sys/types.h
  48 .In sha512.h
  49 .Ft void
  50 .Fn SHA512_Init "SHA512_CTX *context"
  51 .Ft void
  52 .Fn SHA512_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
  53 .Ft void
  54 .Fn SHA512_Final "unsigned char digest[64]" "SHA512_CTX *context"
  55 .Ft "char *"
  56 .Fn SHA512_End "SHA512_CTX *context" "char *buf"
  57 .Ft "char *"
  58 .Fn SHA512_File "const char *filename" "char *buf"
  59 .Ft "char *"
  60 .Fn SHA512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  61 .Ft "char *"
  62 .Fn SHA512_Data "const unsigned char *data" "unsigned int len" "char *buf"
  63 .In sha384.h
  64 .Ft void
  65 .Fn SHA384_Init "SHA384_CTX *context"
  66 .Ft void
  67 .Fn SHA384_Update "SHA384_CTX *context" "const unsigned char *data" "size_t len"
  68 .Ft void
  69 .Fn SHA384_Final "unsigned char digest[48]" "SHA384_CTX *context"
  70 .Ft "char *"
  71 .Fn SHA384_End "SHA384_CTX *context" "char *buf"
  72 .Ft "char *"
  73 .Fn SHA384_File "const char *filename" "char *buf"
  74 .Ft "char *"
  75 .Fn SHA384_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  76 .Ft "char *"
  77 .Fn SHA384_Data "const unsigned char *data" "unsigned int len" "char *buf"
  78 .In sha512t.h
  79 .Ft void
  80 .Fn SHA512_224_Init "SHA512_CTX *context"
  81 .Ft void
  82 .Fn SHA512_224_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
  83 .Ft void
  84 .Fn SHA512_224_Final "unsigned char digest[32]" "SHA512_CTX *context"
  85 .Ft "char *"
  86 .Fn SHA512_224_End "SHA512_CTX *context" "char *buf"
  87 .Ft "char *"
  88 .Fn SHA512_224_File "const char *filename" "char *buf"
  89 .Ft "char *"
  90 .Fn SHA512_224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  91 .Ft "char *"
  92 .Fn SHA512_224_Data "const unsigned char *data" "unsigned int len" "char *buf"
  93 .Ft void
  94 .Fn SHA512_256_Init "SHA512_CTX *context"
  95 .Ft void
  96 .Fn SHA512_256_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
  97 .Ft void
  98 .Fn SHA512_256_Final "unsigned char digest[32]" "SHA512_CTX *context"
  99 .Ft "char *"
 100 .Fn SHA512_256_End "SHA512_CTX *context" "char *buf"
 101 .Ft "char *"
 102 .Fn SHA512_256_File "const char *filename" "char *buf"
 103 .Ft "char *"
 104 .Fn SHA512_256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
 105 .Ft "char *"
 106 .Fn SHA512_256_Data "const unsigned char *data" "unsigned int len" "char *buf"
 107 .Sh DESCRIPTION
 108 The
 109 .Li SHA512_
 110 functions calculate a 512-bit cryptographic checksum (digest)
 111 for any number of input bytes.
 112 A cryptographic checksum is a one-way
 113 hash function; that is, it is computationally impractical to find
 114 the input corresponding to a particular output.
 115 This net result is
 116 a
 117 .Dq fingerprint
 118 of the input-data, which does not disclose the actual input.
 119 .Pp
 120 The
 121 .Fn SHA512_Init ,
 122 .Fn SHA512_Update ,
 123 and
 124 .Fn SHA512_Final
 125 functions are the core functions.
 126 Allocate an
 127 .Vt SHA512_CTX ,
 128 initialize it with
 129 .Fn SHA512_Init ,
 130 run over the data with
 131 .Fn SHA512_Update ,
 132 and finally extract the result using
 133 .Fn SHA512_Final ,
 134 which will also erase the
 135 .Vt SHA512_CTX .
 136 .Pp
 137 .Fn SHA512_End
 138 is a wrapper for
 139 .Fn SHA512_Final
 140 which converts the return value to a 129-character
 141 (including the terminating '\e0')
 142 ASCII string which represents the 512 bits in hexadecimal.
 143 .Pp
 144 .Fn SHA512_File
 145 calculates the digest of a file, and uses
 146 .Fn SHA512_End
 147 to return the result.
 148 If the file cannot be opened, a null pointer is returned.
 149 .Fn SHA512_FileChunk
 150 is similar to
 151 .Fn SHA512_File ,
 152 but it only calculates the digest over a byte-range of the file specified,
 153 starting at
 154 .Fa offset
 155 and spanning
 156 .Fa length
 157 bytes.
 158 If the
 159 .Fa length
 160 parameter is specified as 0, or more than the length of the remaining part
 161 of the file,
 162 .Fn SHA512_FileChunk
 163 calculates the digest from
 164 .Fa offset
 165 to the end of file.
 166 .Fn SHA512_Data
 167 calculates the digest of a chunk of data in memory, and uses
 168 .Fn SHA512_End
 169 to return the result.
 170 .Pp
 171 When using
 172 .Fn SHA512_End ,
 173 .Fn SHA512_File ,
 174 or
 175 .Fn SHA512_Data ,
 176 the
 177 .Fa buf
 178 argument can be a null pointer, in which case the returned string
 179 is allocated with
 180 .Xr malloc 3
 181 and subsequently must be explicitly deallocated using
 182 .Xr free 3
 183 after use.
 184 If the
 185 .Fa buf
 186 argument is non-null it must point to at least 129 characters of buffer space.
 187 .Pp
 188 The
 189 .Li SHA384_ ,
 190 .Li SHA512_224 ,
 191 and
 192 .Li SHA512_256_
 193 functions are identical to the
 194 .Li SHA512_
 195 functions except they use a different initial hash value and the output is
 196 truncated to 384, 224, and 256 bits respectively.
 197 .Pp
 198 .Fn SHA384_End
 199 is a wrapper for
 200 .Fn SHA384_Final
 201 which converts the return value to a 97-character
 202 (including the terminating '\e0')
 203 ASCII string which represents the 384 bits in hexadecimal.
 204 .Pp
 205 .Fn SHA512_224_End
 206 is a wrapper for
 207 .Fn SHA512_Final
 208 which converts the return value to a 57-character
 209 (including the terminating '\e0')
 210 ASCII string which represents the 224 bits in hexadecimal.
 211 .Pp
 212 .Fn SHA512_224_End
 213 is a wrapper for
 214 .Fn SHA512_Final
 215 which converts the return value to a 57-character
 216 (including the terminating '\e0')
 217 .Tn ASCII
 218 string which represents the 224 bits in hexadecimal.
 219 .Pp
 220 .Fn SHA512_256_End
 221 is a wrapper for
 222 .Fn SHA512_Final
 223 which converts the return value to a 65-character
 224 (including the terminating '\e0')
 225 ASCII string which represents the 256 bits in hexadecimal.
 226 .Sh ERRORS
 227 The
 228 .Fn SHA512_End
 229 function called with a null buf argument may fail and return NULL if:
 230 .Bl -tag -width Er
 231 .It Bq Er ENOMEM
 232 Insufficient storage space is available.
 233 .El
 234 .Pp
 235 The
 236 .Fn SHA512_File
 237 and
 238 .Fn SHA512_FileChunk
 239 may return NULL when underlying
 240 .Xr open 2 ,
 241 .Xr fstat 2 ,
 242 .Xr lseek 2 ,
 243 or
 244 .Xr SHA512_End 3
 245 fail.
 246 .Sh SEE ALSO
 247 .Xr md4 3 ,
 248 .Xr md5 3 ,
 249 .Xr ripemd 3 ,
 250 .Xr sha 3 ,
 251 .Xr sha256 3 ,
 252 .Xr sha512 3 ,
 253 .Xr skein 3
 254 .Sh HISTORY
 255 These functions appeared in
 256 .Fx 9.0 .
 257 .Sh AUTHORS
 258 The core hash routines were implemented by Colin Percival based on
 259 the published FIPS 180-2 standard.
 260 .Sh BUGS
 261 No method is known to exist which finds two files having the same hash value,
 262 nor to find a file with a specific hash value.
 263 There is on the other hand no guarantee that such a method does not exist.