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