1c177a86bSGarrett Wollman.\" 2c177a86bSGarrett Wollman.\" ---------------------------------------------------------------------------- 3c177a86bSGarrett Wollman.\" "THE BEER-WARE LICENSE" (Revision 42): 442c159feSPoul-Henning Kamp.\" <phk@FreeBSD.org> wrote this file. As long as you retain this notice you 5c177a86bSGarrett Wollman.\" can do whatever you want with this stuff. If we meet some day, and you think 6c177a86bSGarrett Wollman.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp 7c177a86bSGarrett Wollman.\" ---------------------------------------------------------------------------- 8c177a86bSGarrett Wollman.\" 9c177a86bSGarrett Wollman.\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp 107f3dea24SPeter Wemm.\" $FreeBSD$ 11c177a86bSGarrett Wollman.\" 12*b468a9ffSAllan Jude.Dd April 26, 2016 13d00ed299SGarrett Wollman.Dt SHA 3 14a307d598SRuslan Ermilov.Os 15c177a86bSGarrett Wollman.Sh NAME 16c177a86bSGarrett Wollman.Nm SHA_Init , 17c177a86bSGarrett Wollman.Nm SHA_Update , 18c177a86bSGarrett Wollman.Nm SHA_Final , 19c177a86bSGarrett Wollman.Nm SHA_End , 20c177a86bSGarrett Wollman.Nm SHA_File , 218a24546cSPoul-Henning Kamp.Nm SHA_FileChunk , 22c177a86bSGarrett Wollman.Nm SHA_Data , 23c177a86bSGarrett Wollman.Nm SHA1_Init , 24c177a86bSGarrett Wollman.Nm SHA1_Update , 25c177a86bSGarrett Wollman.Nm SHA1_Final , 26c177a86bSGarrett Wollman.Nm SHA1_End , 27c177a86bSGarrett Wollman.Nm SHA1_File , 288a24546cSPoul-Henning Kamp.Nm SHA1_FileChunk , 29c177a86bSGarrett Wollman.Nm SHA1_Data 30c177a86bSGarrett Wollman.Nd calculate the FIPS 160 and 160-1 ``SHA'' message digests 319452ceebSAlexey Zelkin.Sh LIBRARY 329452ceebSAlexey Zelkin.Lb libmd 33c177a86bSGarrett Wollman.Sh SYNOPSIS 3432eef9aeSRuslan Ermilov.In sys/types.h 3532eef9aeSRuslan Ermilov.In sha.h 36c177a86bSGarrett Wollman.Ft void 37c177a86bSGarrett Wollman.Fn SHA_Init "SHA_CTX *context" 38c177a86bSGarrett Wollman.Ft void 39c7981eaeSColin Percival.Fn SHA_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" 40c177a86bSGarrett Wollman.Ft void 41c177a86bSGarrett Wollman.Fn SHA_Final "unsigned char digest[20]" "SHA_CTX *context" 42c177a86bSGarrett Wollman.Ft "char *" 43c177a86bSGarrett Wollman.Fn SHA_End "SHA_CTX *context" "char *buf" 44c177a86bSGarrett Wollman.Ft "char *" 45c177a86bSGarrett Wollman.Fn SHA_File "const char *filename" "char *buf" 46c177a86bSGarrett Wollman.Ft "char *" 478a24546cSPoul-Henning Kamp.Fn SHA_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 488a24546cSPoul-Henning Kamp.Ft "char *" 49c177a86bSGarrett Wollman.Fn SHA_Data "const unsigned char *data" "unsigned int len" "char *buf" 50c177a86bSGarrett Wollman.Ft void 51c177a86bSGarrett Wollman.Fn SHA1_Init "SHA_CTX *context" 52c177a86bSGarrett Wollman.Ft void 53c7981eaeSColin Percival.Fn SHA1_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" 54c177a86bSGarrett Wollman.Ft void 55c177a86bSGarrett Wollman.Fn SHA1_Final "unsigned char digest[20]" "SHA_CTX *context" 56c177a86bSGarrett Wollman.Ft "char *" 57c177a86bSGarrett Wollman.Fn SHA1_End "SHA_CTX *context" "char *buf" 58c177a86bSGarrett Wollman.Ft "char *" 59c177a86bSGarrett Wollman.Fn SHA1_File "const char *filename" "char *buf" 60c177a86bSGarrett Wollman.Ft "char *" 618a24546cSPoul-Henning Kamp.Fn SHA1_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 628a24546cSPoul-Henning Kamp.Ft "char *" 63c177a86bSGarrett Wollman.Fn SHA1_Data "const unsigned char *data" "unsigned int len" "char *buf" 64c177a86bSGarrett Wollman.Sh DESCRIPTION 65c177a86bSGarrett WollmanThe 66c177a86bSGarrett Wollman.Li SHA_ 67c177a86bSGarrett Wollmanand 68c177a86bSGarrett Wollman.Li SHA1_ 69c177a86bSGarrett Wollmanfunctions calculate a 160-bit cryptographic checksum (digest) 70dc2af37dSHiten Pandyafor any number of input bytes. 71dc2af37dSHiten PandyaA cryptographic checksum is a one-way 72c177a86bSGarrett Wollmanhash function; that is, it is computationally impractical to find 73dc2af37dSHiten Pandyathe input corresponding to a particular output. 74dc2af37dSHiten PandyaThis net result is 75dc2af37dSHiten Pandyaa 76dc2af37dSHiten Pandya.Dq fingerprint 770227791bSRuslan Ermilovof the input-data, which does not disclose the actual input. 78c177a86bSGarrett Wollman.Pp 79c177a86bSGarrett Wollman.Tn SHA 80c4d9468eSRuslan Ermilov(or 81c4d9468eSRuslan Ermilov.Tn SHA-0 ) 82c177a86bSGarrett Wollmanis the original Secure Hash Algorithm specified in 83c177a86bSGarrett Wollman.Tn FIPS 84dc2af37dSHiten Pandya160. 85dc2af37dSHiten PandyaIt was quickly proven insecure, and has been superseded by 86c177a86bSGarrett Wollman.Tn SHA-1 . 87c177a86bSGarrett Wollman.Tn SHA-0 88c177a86bSGarrett Wollmanis included for compatibility purposes only. 89c177a86bSGarrett Wollman.Pp 90c177a86bSGarrett WollmanThe 91c177a86bSGarrett Wollman.Fn SHA1_Init , 92c177a86bSGarrett Wollman.Fn SHA1_Update , 93c177a86bSGarrett Wollmanand 94c177a86bSGarrett Wollman.Fn SHA1_Final 95dc2af37dSHiten Pandyafunctions are the core functions. 96dc2af37dSHiten PandyaAllocate an 97dc2af37dSHiten Pandya.Vt SHA_CTX , 98dc2af37dSHiten Pandyainitialize it with 99c177a86bSGarrett Wollman.Fn SHA1_Init , 100c177a86bSGarrett Wollmanrun over the data with 101c177a86bSGarrett Wollman.Fn SHA1_Update , 102c177a86bSGarrett Wollmanand finally extract the result using 103c177a86bSGarrett Wollman.Fn SHA1_Final . 104c177a86bSGarrett Wollman.Pp 105c177a86bSGarrett Wollman.Fn SHA1_End 106c177a86bSGarrett Wollmanis a wrapper for 107c177a86bSGarrett Wollman.Fn SHA1_Final 108c177a86bSGarrett Wollmanwhich converts the return value to a 41-character 109c177a86bSGarrett Wollman(including the terminating '\e0') 110c177a86bSGarrett Wollman.Tn ASCII 111c177a86bSGarrett Wollmanstring which represents the 160 bits in hexadecimal. 112c177a86bSGarrett Wollman.Pp 113c177a86bSGarrett Wollman.Fn SHA1_File 114c177a86bSGarrett Wollmancalculates the digest of a file, and uses 115c177a86bSGarrett Wollman.Fn SHA1_End 116c177a86bSGarrett Wollmanto return the result. 117c177a86bSGarrett WollmanIf the file cannot be opened, a null pointer is returned. 1188a24546cSPoul-Henning Kamp.Fn SHA1_FileChunk 1198a24546cSPoul-Henning Kampis similar to 1208a24546cSPoul-Henning Kamp.Fn SHA1_File , 1218a24546cSPoul-Henning Kampbut it only calculates the digest over a byte-range of the file specified, 1228a24546cSPoul-Henning Kampstarting at 1237e5d6de0SRuslan Ermilov.Fa offset 1248a24546cSPoul-Henning Kampand spanning 1257e5d6de0SRuslan Ermilov.Fa length 1268a24546cSPoul-Henning Kampbytes. 1278a24546cSPoul-Henning KampIf the 1287e5d6de0SRuslan Ermilov.Fa length 1298a24546cSPoul-Henning Kampparameter is specified as 0, or more than the length of the remaining part 1308a24546cSPoul-Henning Kampof the file, 1318a24546cSPoul-Henning Kamp.Fn SHA1_FileChunk 1328a24546cSPoul-Henning Kampcalculates the digest from 1337e5d6de0SRuslan Ermilov.Fa offset 1348a24546cSPoul-Henning Kampto the end of file. 135c177a86bSGarrett Wollman.Fn SHA1_Data 136c177a86bSGarrett Wollmancalculates the digest of a chunk of data in memory, and uses 137c177a86bSGarrett Wollman.Fn SHA1_End 138c177a86bSGarrett Wollmanto return the result. 139c177a86bSGarrett Wollman.Pp 140c177a86bSGarrett WollmanWhen using 141c177a86bSGarrett Wollman.Fn SHA1_End , 142c177a86bSGarrett Wollman.Fn SHA1_File , 143c177a86bSGarrett Wollmanor 144c177a86bSGarrett Wollman.Fn SHA1_Data , 145c177a86bSGarrett Wollmanthe 1467e5d6de0SRuslan Ermilov.Fa buf 147c177a86bSGarrett Wollmanargument can be a null pointer, in which case the returned string 148c177a86bSGarrett Wollmanis allocated with 149c177a86bSGarrett Wollman.Xr malloc 3 150c177a86bSGarrett Wollmanand subsequently must be explicitly deallocated using 151c177a86bSGarrett Wollman.Xr free 3 152c177a86bSGarrett Wollmanafter use. 153c177a86bSGarrett WollmanIf the 1547e5d6de0SRuslan Ermilov.Fa buf 155c177a86bSGarrett Wollmanargument is non-null it must point to at least 41 characters of buffer space. 156c177a86bSGarrett Wollman.Sh SEE ALSO 157c177a86bSGarrett Wollman.Xr md4 3 , 158d00ed299SGarrett Wollman.Xr md5 3 , 15948856b00SRuslan Ermilov.Xr ripemd 3 , 160*b468a9ffSAllan Jude.Xr sha256 3 , 161*b468a9ffSAllan Jude.Xr sha512 3 , 162*b468a9ffSAllan Jude.Xr skein 3 16324a0682cSRuslan Ermilov.Sh HISTORY 16424a0682cSRuslan ErmilovThese functions appeared in 16524a0682cSRuslan Ermilov.Fx 4.0 . 166c177a86bSGarrett Wollman.Sh AUTHORS 167c177a86bSGarrett WollmanThe core hash routines were implemented by Eric Young based on the 168c177a86bSGarrett Wollmanpublished 169c177a86bSGarrett Wollman.Tn FIPS 170c177a86bSGarrett Wollmanstandards. 171c177a86bSGarrett Wollman.Sh BUGS 172c177a86bSGarrett WollmanNo method is known to exist which finds two files having the same hash value, 173c177a86bSGarrett Wollmannor to find a file with a specific hash value. 1740227791bSRuslan ErmilovThere is on the other hand no guarantee that such a method does not exist. 175303dec3bSGarrett Wollman.Pp 176303dec3bSGarrett WollmanThe 177303dec3bSGarrett Wollman.Tn IA32 178303dec3bSGarrett Wollman(Intel) implementation of 179303dec3bSGarrett Wollman.Tn SHA-1 180303dec3bSGarrett Wollmanmakes heavy use of the 181303dec3bSGarrett Wollman.Ql bswapl 182dc2af37dSHiten Pandyainstruction, which is not present on the original 80386. 183dc2af37dSHiten PandyaAttempts to use 184303dec3bSGarrett Wollman.Tn SHA-1 185303dec3bSGarrett Wollmanon those processors will cause an illegal instruction trap. 186303dec3bSGarrett Wollman(Arguably, the kernel should simply emulate this instruction.) 187