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