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