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 July 20, 2018 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_File , 20.Nm SHA224_FileChunk , 21.Nm SHA224_Data , 22.Nm SHA256_Init , 23.Nm SHA256_Update , 24.Nm SHA256_Final , 25.Nm SHA256_End , 26.Nm SHA256_File , 27.Nm SHA256_FileChunk , 28.Nm SHA256_Data 29.Nd calculate the FIPS 180-2 ``SHA-256'' (or SHA-224) message digest 30.Sh LIBRARY 31.Lb libmd 32.Sh SYNOPSIS 33.In sys/types.h 34.In sha224.h 35.Ft void 36.Fn SHA224_Init "SHA224_CTX *context" 37.Ft void 38.Fn SHA224_Update "SHA224_CTX *context" "const unsigned char *data" "size_t len" 39.Ft void 40.Fn SHA224_Final "unsigned char digest[32]" "SHA224_CTX *context" 41.Ft "char *" 42.Fn SHA224_End "SHA224_CTX *context" "char *buf" 43.Ft "char *" 44.Fn SHA224_File "const char *filename" "char *buf" 45.Ft "char *" 46.Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 47.Ft "char *" 48.Fn SHA224_Data "const unsigned char *data" "unsigned int len" "char *buf" 49.In sha256.h 50.Ft void 51.Fn SHA256_Init "SHA256_CTX *context" 52.Ft void 53.Fn SHA256_Update "SHA256_CTX *context" "const unsigned char *data" "size_t len" 54.Ft void 55.Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context" 56.Ft "char *" 57.Fn SHA256_End "SHA256_CTX *context" "char *buf" 58.Ft "char *" 59.Fn SHA256_File "const char *filename" "char *buf" 60.Ft "char *" 61.Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 62.Ft "char *" 63.Fn SHA256_Data "const unsigned char *data" "unsigned int len" "char *buf" 64.Sh DESCRIPTION 65The 66.Li SHA256_ 67functions calculate a 256-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 SHA256_Init , 79.Fn SHA256_Update , 80and 81.Fn SHA256_Final 82functions are the core functions. 83Allocate an 84.Vt SHA256_CTX , 85initialize it with 86.Fn SHA256_Init , 87run over the data with 88.Fn SHA256_Update , 89and finally extract the result using 90.Fn SHA256_Final , 91which will also erase the 92.Vt SHA256_CTX . 93.Pp 94.Fn SHA256_End 95is a wrapper for 96.Fn SHA256_Final 97which converts the return value to a 65-character 98(including the terminating '\e0') 99ASCII string 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 ERRORS 148The 149.Fn SHA256_End 150function called with a null buf argument may fail and return NULL if: 151.Bl -tag -width Er 152.It Bq Er ENOMEM 153Insufficient storage space is available. 154.El 155.Pp 156The 157.Fn SHA256_File 158and 159.Fn SHA256_FileChunk 160may return NULL when underlying 161.Xr open 2 , 162.Xr fstat 2 , 163.Xr lseek 2 , 164or 165.Xr SHA256_End 3 166fail. 167.Sh SEE ALSO 168.Xr md4 3 , 169.Xr md5 3 , 170.Xr ripemd 3 , 171.Xr sha 3 , 172.Xr sha512 3 , 173.Xr skein 3 174.Sh HISTORY 175These functions appeared in 176.Fx 6.0 . 177.Sh AUTHORS 178The core hash routines were implemented by Colin Percival based on 179the published FIPS 180-2 standard. 180.Sh BUGS 181No method is known to exist which finds two files having the same hash value, 182nor to find a file with a specific hash value. 183There is on the other hand no guarantee that such a method does not exist. 184