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