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 108The 109.Li SHA512_ 110functions calculate a 512-bit cryptographic checksum (digest) 111for any number of input bytes. 112A cryptographic checksum is a one-way 113hash function; that is, it is computationally impractical to find 114the input corresponding to a particular output. 115This net result is 116a 117.Dq fingerprint 118of the input-data, which does not disclose the actual input. 119.Pp 120The 121.Fn SHA512_Init , 122.Fn SHA512_Update , 123and 124.Fn SHA512_Final 125functions are the core functions. 126Allocate an 127.Vt SHA512_CTX , 128initialize it with 129.Fn SHA512_Init , 130run over the data with 131.Fn SHA512_Update , 132and finally extract the result using 133.Fn SHA512_Final , 134which will also erase the 135.Vt SHA512_CTX . 136.Pp 137.Fn SHA512_End 138is a wrapper for 139.Fn SHA512_Final 140which converts the return value to a 129-character 141(including the terminating '\e0') 142ASCII string which represents the 512 bits in hexadecimal. 143.Pp 144.Fn SHA512_File 145calculates the digest of a file, and uses 146.Fn SHA512_End 147to return the result. 148If the file cannot be opened, a null pointer is returned. 149.Fn SHA512_FileChunk 150is similar to 151.Fn SHA512_File , 152but it only calculates the digest over a byte-range of the file specified, 153starting at 154.Fa offset 155and spanning 156.Fa length 157bytes. 158If the 159.Fa length 160parameter is specified as 0, or more than the length of the remaining part 161of the file, 162.Fn SHA512_FileChunk 163calculates the digest from 164.Fa offset 165to the end of file. 166.Fn SHA512_Data 167calculates the digest of a chunk of data in memory, and uses 168.Fn SHA512_End 169to return the result. 170.Pp 171When using 172.Fn SHA512_End , 173.Fn SHA512_File , 174or 175.Fn SHA512_Data , 176the 177.Fa buf 178argument can be a null pointer, in which case the returned string 179is allocated with 180.Xr malloc 3 181and subsequently must be explicitly deallocated using 182.Xr free 3 183after use. 184If the 185.Fa buf 186argument is non-null it must point to at least 129 characters of buffer space. 187.Pp 188The 189.Li SHA384_ , 190.Li SHA512_224 , 191and 192.Li SHA512_256_ 193functions are identical to the 194.Li SHA512_ 195functions except they use a different initial hash value and the output is 196truncated to 384, 224, and 256 bits respectively. 197.Pp 198.Fn SHA384_End 199is a wrapper for 200.Fn SHA384_Final 201which converts the return value to a 97-character 202(including the terminating '\e0') 203ASCII string which represents the 384 bits in hexadecimal. 204.Pp 205.Fn SHA512_224_End 206is a wrapper for 207.Fn SHA512_Final 208which converts the return value to a 57-character 209(including the terminating '\e0') 210ASCII string which represents the 224 bits in hexadecimal. 211.Pp 212.Fn SHA512_224_End 213is a wrapper for 214.Fn SHA512_Final 215which converts the return value to a 57-character 216(including the terminating '\e0') 217.Tn ASCII 218string which represents the 224 bits in hexadecimal. 219.Pp 220.Fn SHA512_256_End 221is a wrapper for 222.Fn SHA512_Final 223which converts the return value to a 65-character 224(including the terminating '\e0') 225ASCII string which represents the 256 bits in hexadecimal. 226.Sh ERRORS 227The 228.Fn SHA512_End 229function called with a null buf argument may fail and return NULL if: 230.Bl -tag -width Er 231.It Bq Er ENOMEM 232Insufficient storage space is available. 233.El 234.Pp 235The 236.Fn SHA512_File 237and 238.Fn SHA512_FileChunk 239may return NULL when underlying 240.Xr open 2 , 241.Xr fstat 2 , 242.Xr lseek 2 , 243or 244.Xr SHA512_End 3 245fail. 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 255These functions appeared in 256.Fx 9.0 . 257.Sh AUTHORS 258The core hash routines were implemented by Colin Percival based on 259the published FIPS 180-2 standard. 260.Sh BUGS 261No method is known to exist which finds two files having the same hash value, 262nor to find a file with a specific hash value. 263There is on the other hand no guarantee that such a method does not exist. 264