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 September 14, 2005 13.Dt SHA256 3 14.Os 15.Sh NAME 16.Nm SHA256_Init , 17.Nm SHA256_Update , 18.Nm SHA256_Final , 19.Nm SHA256_End , 20.Nm SHA256_File , 21.Nm SHA256_FileChunk , 22.Nm SHA256_Data 23.Nd calculate the FIPS 180-2 ``SHA-256'' message digest 24.Sh LIBRARY 25.Lb libmd 26.Sh SYNOPSIS 27.In sys/types.h 28.In sha256.h 29.Ft void 30.Fn SHA256_Init "SHA256_CTX *context" 31.Ft void 32.Fn SHA256_Update "SHA256_CTX *context" "const unsigned char *data" "size_t len" 33.Ft void 34.Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context" 35.Ft "char *" 36.Fn SHA256_End "SHA256_CTX *context" "char *buf" 37.Ft "char *" 38.Fn SHA256_File "const char *filename" "char *buf" 39.Ft "char *" 40.Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 41.Ft "char *" 42.Fn SHA256_Data "const unsigned char *data" "unsigned int len" "char *buf" 43.Sh DESCRIPTION 44The 45.Li SHA256_ 46functions calculate a 256-bit cryptographic checksum (digest) 47for any number of input bytes. 48A cryptographic checksum is a one-way 49hash function; that is, it is computationally impractical to find 50the input corresponding to a particular output. 51This net result is 52a 53.Dq fingerprint 54of the input-data, which does not disclose the actual input. 55.Pp 56The 57.Fn SHA256_Init , 58.Fn SHA256_Update , 59and 60.Fn SHA256_Final 61functions are the core functions. 62Allocate an 63.Vt SHA256_CTX , 64initialize it with 65.Fn SHA256_Init , 66run over the data with 67.Fn SHA256_Update , 68and finally extract the result using 69.Fn SHA256_Final . 70.Pp 71.Fn SHA256_End 72is a wrapper for 73.Fn SHA256_Final 74which converts the return value to a 65-character 75(including the terminating '\e0') 76.Tn ASCII 77string which represents the 256 bits in hexadecimal. 78.Pp 79.Fn SHA256_File 80calculates the digest of a file, and uses 81.Fn SHA256_End 82to return the result. 83If the file cannot be opened, a null pointer is returned. 84.Fn SHA256_FileChunk 85is similar to 86.Fn SHA256_File , 87but it only calculates the digest over a byte-range of the file specified, 88starting at 89.Fa offset 90and spanning 91.Fa length 92bytes. 93If the 94.Fa length 95parameter is specified as 0, or more than the length of the remaining part 96of the file, 97.Fn SHA256_FileChunk 98calculates the digest from 99.Fa offset 100to the end of file. 101.Fn SHA256_Data 102calculates the digest of a chunk of data in memory, and uses 103.Fn SHA256_End 104to return the result. 105.Pp 106When using 107.Fn SHA256_End , 108.Fn SHA256_File , 109or 110.Fn SHA256_Data , 111the 112.Fa buf 113argument can be a null pointer, in which case the returned string 114is allocated with 115.Xr malloc 3 116and subsequently must be explicitly deallocated using 117.Xr free 3 118after use. 119If the 120.Fa buf 121argument is non-null it must point to at least 65 characters of buffer space. 122.Sh SEE ALSO 123.Xr md2 3 , 124.Xr md4 3 , 125.Xr md5 3 , 126.Xr ripemd 3 , 127.Xr sha 3 128.Sh HISTORY 129These functions appeared in 130.Fx 4.0 . 131.Sh AUTHORS 132The core hash routines were implemented by Colin Percival based on 133the published 134.Tn FIPS 180-2 135standard. 136.Sh BUGS 137No method is known to exist which finds two files having the same hash value, 138nor to find a file with a specific hash value. 139There is on the other hand no guarantee that such a method does not exist. 140