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 October 17, 2015 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.Nd calculate the FIPS 180-4 ``SHA-512'' family of message digests 31.Sh LIBRARY 32.Lb libmd 33.Sh SYNOPSIS 34.In sys/types.h 35.In sha512.h 36.Ft void 37.Fn SHA512_Init "SHA512_CTX *context" 38.Ft void 39.Fn SHA512_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len" 40.Ft void 41.Fn SHA512_Final "unsigned char digest[64]" "SHA512_CTX *context" 42.Ft "char *" 43.Fn SHA512_End "SHA512_CTX *context" "char *buf" 44.Ft "char *" 45.Fn SHA512_File "const char *filename" "char *buf" 46.Ft "char *" 47.Fn SHA512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 48.Ft "char *" 49.Fn SHA512_Data "const unsigned char *data" "unsigned int len" "char *buf" 50.Ft void 51.Fn SHA384_Init "SHA384_CTX *context" 52.Ft void 53.Fn SHA384_Update "SHA384_CTX *context" "const unsigned char *data" "size_t len" 54.Ft void 55.Fn SHA384_Final "unsigned char digest[48]" "SHA384_CTX *context" 56.Ft "char *" 57.Fn SHA384_End "SHA384_CTX *context" "char *buf" 58.Ft "char *" 59.Fn SHA384_File "const char *filename" "char *buf" 60.Ft "char *" 61.Fn SHA384_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 62.Ft "char *" 63.Fn SHA384_Data "const unsigned char *data" "unsigned int len" "char *buf" 64.Sh DESCRIPTION 65The 66.Li SHA512_ 67functions calculate a 512-bit cryptographic checksum (digest) 68for any number of input bytes. 69A cryptographic checksum is a one-way 70hash function; that is, it is computationally impractical to find 71the input corresponding to a particular output. 72This net result is 73a 74.Dq fingerprint 75of the input-data, which does not disclose the actual input. 76.Pp 77The 78.Fn SHA512_Init , 79.Fn SHA512_Update , 80and 81.Fn SHA512_Final 82functions are the core functions. 83Allocate an 84.Vt SHA512_CTX , 85initialize it with 86.Fn SHA512_Init , 87run over the data with 88.Fn SHA512_Update , 89and finally extract the result using 90.Fn SHA512_Final . 91.Pp 92.Fn SHA512_End 93is a wrapper for 94.Fn SHA512_Final 95which converts the return value to a 65-character 96(including the terminating '\e0') 97.Tn ASCII 98string which represents the 512 bits in hexadecimal. 99.Pp 100.Fn SHA512_File 101calculates the digest of a file, and uses 102.Fn SHA512_End 103to return the result. 104If the file cannot be opened, a null pointer is returned. 105.Fn SHA512_FileChunk 106is similar to 107.Fn SHA512_File , 108but it only calculates the digest over a byte-range of the file specified, 109starting at 110.Fa offset 111and spanning 112.Fa length 113bytes. 114If the 115.Fa length 116parameter is specified as 0, or more than the length of the remaining part 117of the file, 118.Fn SHA512_FileChunk 119calculates the digest from 120.Fa offset 121to the end of file. 122.Fn SHA512_Data 123calculates the digest of a chunk of data in memory, and uses 124.Fn SHA512_End 125to return the result. 126.Pp 127When using 128.Fn SHA512_End , 129.Fn SHA512_File , 130or 131.Fn SHA512_Data , 132the 133.Fa buf 134argument can be a null pointer, in which case the returned string 135is allocated with 136.Xr malloc 3 137and subsequently must be explicitly deallocated using 138.Xr free 3 139after use. 140If the 141.Fa buf 142argument is non-null it must point to at least 65 characters of buffer space. 143.Pp 144The 145.Li SHA384_ 146functions are identical to the 147.Li SHA512_ 148functions except they use a different initial hash value and the output is 149truncated to 384 bits. 150.Pp 151.Fn SHA384_End 152is a wrapper for 153.Fn SHA384_Final 154which converts the return value to a 49-character 155(including the terminating '\e0') 156.Tn ASCII 157string which represents the 384 bits in hexadecimal. 158.Sh SEE ALSO 159.Xr md4 3 , 160.Xr md5 3 , 161.Xr ripemd 3 , 162.Xr sha 3 163.Sh HISTORY 164These functions appeared in 165.Fx 9.0 . 166.Sh AUTHORS 167The core hash routines were implemented by Colin Percival based on 168the published 169.Tn FIPS 180-2 170standard. 171.Sh BUGS 172No method is known to exist which finds two files having the same hash value, 173nor to find a file with a specific hash value. 174There is on the other hand no guarantee that such a method does not exist. 175