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 April 22, 2016 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 . 114.Pp 115.Fn SHA512_End 116is a wrapper for 117.Fn SHA512_Final 118which converts the return value to a 129-character 119(including the terminating '\e0') 120.Tn ASCII 121string which represents the 512 bits in hexadecimal. 122.Pp 123.Fn SHA512_File 124calculates the digest of a file, and uses 125.Fn SHA512_End 126to return the result. 127If the file cannot be opened, a null pointer is returned. 128.Fn SHA512_FileChunk 129is similar to 130.Fn SHA512_File , 131but it only calculates the digest over a byte-range of the file specified, 132starting at 133.Fa offset 134and spanning 135.Fa length 136bytes. 137If the 138.Fa length 139parameter is specified as 0, or more than the length of the remaining part 140of the file, 141.Fn SHA512_FileChunk 142calculates the digest from 143.Fa offset 144to the end of file. 145.Fn SHA512_Data 146calculates the digest of a chunk of data in memory, and uses 147.Fn SHA512_End 148to return the result. 149.Pp 150When using 151.Fn SHA512_End , 152.Fn SHA512_File , 153or 154.Fn SHA512_Data , 155the 156.Fa buf 157argument can be a null pointer, in which case the returned string 158is allocated with 159.Xr malloc 3 160and subsequently must be explicitly deallocated using 161.Xr free 3 162after use. 163If the 164.Fa buf 165argument is non-null it must point to at least 129 characters of buffer space. 166.Pp 167The 168.Li SHA384_ 169and 170.Li SHA512_256_ 171functions are identical to the 172.Li SHA512_ 173functions except they use a different initial hash value and the output is 174truncated to 384 bits and 256 bits respectively. 175.Pp 176.Fn SHA384_End 177is a wrapper for 178.Fn SHA384_Final 179which converts the return value to a 97-character 180(including the terminating '\e0') 181.Tn ASCII 182string which represents the 384 bits in hexadecimal. 183.Pp 184.Fn SHA512_256_End 185is a wrapper for 186.Fn SHA512_Final 187which converts the return value to a 65-character 188(including the terminating '\e0') 189.Tn ASCII 190string which represents the 256 bits in hexadecimal. 191.Sh SEE ALSO 192.Xr md4 3 , 193.Xr md5 3 , 194.Xr ripemd 3 , 195.Xr sha 3 , 196.Xr sha256 3 , 197.Xr sha512 3 , 198.Xr skein 3 199.Sh HISTORY 200These functions appeared in 201.Fx 9.0 . 202.Sh AUTHORS 203The core hash routines were implemented by Colin Percival based on 204the published 205.Tn FIPS 180-2 206standard. 207.Sh BUGS 208No method is known to exist which finds two files having the same hash value, 209nor to find a file with a specific hash value. 210There is on the other hand no guarantee that such a method does not exist. 211