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 February 12, 2023 12.Dt SHA 3 13.Os 14.Sh NAME 15.Nm SHA_Init , 16.Nm SHA_Update , 17.Nm SHA_Final , 18.Nm SHA_End , 19.Nm SHA_Fd , 20.Nm SHA_FdChunk , 21.Nm SHA_File , 22.Nm SHA_FileChunk , 23.Nm SHA_Data , 24.Nm SHA1_Init , 25.Nm SHA1_Update , 26.Nm SHA1_Final , 27.Nm SHA1_End , 28.Nm SHA1_Fd , 29.Nm SHA1_FdChunk , 30.Nm SHA1_File , 31.Nm SHA1_FileChunk , 32.Nm SHA1_Data 33.Nd calculate the FIPS 160 and 160-1 ``SHA'' message digests 34.Sh LIBRARY 35.Lb libmd 36.Sh SYNOPSIS 37.In sys/types.h 38.In sha.h 39.Ft void 40.Fn SHA_Init "SHA_CTX *context" 41.Ft void 42.Fn SHA_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" 43.Ft void 44.Fn SHA_Final "unsigned char digest[20]" "SHA_CTX *context" 45.Ft "char *" 46.Fn SHA_End "SHA_CTX *context" "char *buf" 47.Ft "char *" 48.Fn SHA_Fd "int fd" "char *buf" 49.Ft "char *" 50.Fn SHA_FdChunk "int fd" "char *buf" "off_t offset" "off_t length" 51.Ft "char *" 52.Fn SHA_File "const char *filename" "char *buf" 53.Ft "char *" 54.Fn SHA_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 55.Ft "char *" 56.Fn SHA_Data "const unsigned char *data" "unsigned int len" "char *buf" 57.Ft void 58.Fn SHA1_Init "SHA_CTX *context" 59.Ft void 60.Fn SHA1_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" 61.Ft void 62.Fn SHA1_Final "unsigned char digest[20]" "SHA_CTX *context" 63.Ft "char *" 64.Fn SHA1_End "SHA_CTX *context" "char *buf" 65.Ft "char *" 66.Fn SHA1_Fd "int fd" "char *buf" 67.Ft "char *" 68.Fn SHA1_FdChunk "int fd" "char *buf" "off_t offset" "off_t length" 69.Ft "char *" 70.Fn SHA1_File "const char *filename" "char *buf" 71.Ft "char *" 72.Fn SHA1_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 73.Ft "char *" 74.Fn SHA1_Data "const unsigned char *data" "unsigned int len" "char *buf" 75.Sh DESCRIPTION 76The 77.Li SHA_ 78and 79.Li SHA1_ 80functions calculate a 160-bit cryptographic checksum (digest) 81for any number of input bytes. 82A cryptographic checksum is a one-way 83hash function; that is, it is computationally impractical to find 84the input corresponding to a particular output. 85This net result is 86a 87.Dq fingerprint 88of the input-data, which does not disclose the actual input. 89.Pp 90SHA (or SHA-0) is the original Secure Hash Algorithm specified in FIPS 160. 91It was quickly proven insecure, and has been superseded by SHA-1. 92SHA-0 is included for compatibility purposes only. 93.Pp 94The 95.Fn SHA1_Init , 96.Fn SHA1_Update , 97and 98.Fn SHA1_Final 99functions are the core functions. 100Allocate an 101.Vt SHA_CTX , 102initialize it with 103.Fn SHA1_Init , 104run over the data with 105.Fn SHA1_Update , 106and finally extract the result using 107.Fn SHA1_Final , 108which will also erase the 109.Vt SHA_CTX . 110.Pp 111.Fn SHA1_End 112is a wrapper for 113.Fn SHA1_Final 114which converts the return value to a 41-character 115(including the terminating '\e0') 116ASCII string which represents the 160 bits in hexadecimal. 117.Pp 118.Fn SHA1_File 119calculates the digest of a file, and uses 120.Fn SHA1_End 121to return the result. 122If the file cannot be opened, a null pointer is returned. 123.Fn SHA1_FileChunk 124is similar to 125.Fn SHA1_File , 126but it only calculates the digest over a byte-range of the file specified, 127starting at 128.Fa offset 129and spanning 130.Fa length 131bytes. 132If the 133.Fa length 134parameter is specified as 0, or more than the length of the remaining part 135of the file, 136.Fn SHA1_FileChunk 137calculates the digest from 138.Fa offset 139to the end of file. 140.Fn SHA1_Data 141calculates the digest of a chunk of data in memory, and uses 142.Fn SHA1_End 143to return the result. 144.Pp 145The 146.Fn SHA1_Fd 147and 148.Fn SHA1_FdChunk 149functions are identical to their 150.Fn SHA1_File 151and 152.Fn SHA1_FileChunk 153counterparts, with the exception that the first argument is an 154.Fa fd 155instead of a 156.Fa filename . 157.Pp 158When using 159.Fn SHA1_End , 160.Fn SHA1_File , 161or 162.Fn SHA1_Data , 163the 164.Fa buf 165argument can be a null pointer, in which case the returned string 166is allocated with 167.Xr malloc 3 168and subsequently must be explicitly deallocated using 169.Xr free 3 170after use. 171If the 172.Fa buf 173argument is non-null it must point to at least 41 characters of buffer space. 174.Sh ERRORS 175The 176.Fn SHA1_End 177function called with a null buf argument may fail and return NULL if: 178.Bl -tag -width Er 179.It Bq Er ENOMEM 180Insufficient storage space is available. 181.El 182.Pp 183The 184.Fn SHA1_File 185and 186.Fn SHA1_FileChunk 187may return NULL when underlying 188.Xr open 2 , 189.Xr fstat 2 , 190.Xr lseek 2 , 191or 192.Xr SHA1_End 3 193fail. 194.Sh SEE ALSO 195.Xr md4 3 , 196.Xr md5 3 , 197.Xr ripemd 3 , 198.Xr sha256 3 , 199.Xr sha512 3 , 200.Xr skein 3 201.Sh HISTORY 202These functions appeared in 203.Fx 4.0 . 204.Sh AUTHORS 205The core hash routines were implemented by Eric Young based on the 206published 207FIPS standards. 208.Sh BUGS 209The SHA1 algorithm has been proven to be vulnerable to practical collision 210attacks and should not be relied upon to produce unique outputs, 211.Em nor should it be used as part of a new cryptographic signature scheme. 212