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