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