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