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