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 20, 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 , 92which will also erase the 93.Vt SHA256_CTX . 94.Pp 95.Fn SHA256_End 96is a wrapper for 97.Fn SHA256_Final 98which converts the return value to a 65-character 99(including the terminating '\e0') 100ASCII string which represents the 256 bits in hexadecimal. 101.Pp 102.Fn SHA256_File 103calculates the digest of a file, and uses 104.Fn SHA256_End 105to return the result. 106If the file cannot be opened, a null pointer is returned. 107.Fn SHA256_FileChunk 108is similar to 109.Fn SHA256_File , 110but it only calculates the digest over a byte-range of the file specified, 111starting at 112.Fa offset 113and spanning 114.Fa length 115bytes. 116If the 117.Fa length 118parameter is specified as 0, or more than the length of the remaining part 119of the file, 120.Fn SHA256_FileChunk 121calculates the digest from 122.Fa offset 123to the end of file. 124.Fn SHA256_Data 125calculates the digest of a chunk of data in memory, and uses 126.Fn SHA256_End 127to return the result. 128.Pp 129When using 130.Fn SHA256_End , 131.Fn SHA256_File , 132or 133.Fn SHA256_Data , 134the 135.Fa buf 136argument can be a null pointer, in which case the returned string 137is allocated with 138.Xr malloc 3 139and subsequently must be explicitly deallocated using 140.Xr free 3 141after use. 142If the 143.Fa buf 144argument is non-null it must point to at least 65 characters of buffer space. 145.Pp 146SHA224 is identical SHA256, except it has slightly different initialization 147vectors, and is truncated to a shorter digest. 148.Sh ERRORS 149The 150.Fn SHA256_End 151function called with a null buf argument may fail and return NULL if: 152.Bl -tag -width Er 153.It Bq Er ENOMEM 154Insufficient storage space is available. 155.El 156.Pp 157The 158.Fn SHA256_File 159and 160.Fn SHA256_FileChunk 161may return NULL when underlying 162.Xr open 2 , 163.Xr fstat 2 , 164.Xr lseek 2 , 165or 166.Xr SHA256_End 3 167fail. 168.Sh SEE ALSO 169.Xr md4 3 , 170.Xr md5 3 , 171.Xr ripemd 3 , 172.Xr sha 3 , 173.Xr sha512 3 , 174.Xr skein 3 175.Sh HISTORY 176These functions appeared in 177.Fx 6.0 . 178.Sh AUTHORS 179The core hash routines were implemented by Colin Percival based on 180the published FIPS 180-2 standard. 181.Sh BUGS 182No method is known to exist which finds two files having the same hash value, 183nor to find a file with a specific hash value. 184There is on the other hand no guarantee that such a method does not exist. 185