1.\" 2.\" ---------------------------------------------------------------------------- 3.\" "THE BEER-WARE LICENSE" (Revision 42): 4.\" <phk@login.dkuug.dk> 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.\" $Id: sha.3,v 1.2 1999/02/26 18:41:45 wollman Exp $ 11.\" 12.Dd February 25, 1999 13.Dt SHA 3 14.Os FreeBSD 4.0 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_Data , 22.Nm SHA1_Init , 23.Nm SHA1_Update , 24.Nm SHA1_Final , 25.Nm SHA1_End , 26.Nm SHA1_File , 27.Nm SHA1_Data 28.Nd calculate the FIPS 160 and 160-1 ``SHA'' message digests 29.Sh SYNOPSIS 30.Fd #include <sys/types.h> 31.Fd #include <sha.h> 32.Ft void 33.Fn SHA_Init "SHA_CTX *context" 34.Ft void 35.Fn SHA_Update "SHA_CTX *context" "const unsigned char *data" "unsigned int len" 36.Ft void 37.Fn SHA_Final "unsigned char digest[20]" "SHA_CTX *context" 38.Ft "char *" 39.Fn SHA_End "SHA_CTX *context" "char *buf" 40.Ft "char *" 41.Fn SHA_File "const char *filename" "char *buf" 42.Ft "char *" 43.Fn SHA_Data "const unsigned char *data" "unsigned int len" "char *buf" 44.Ft void 45.Fn SHA1_Init "SHA_CTX *context" 46.Ft void 47.Fn SHA1_Update "SHA_CTX *context" "const unsigned char *data" "unsigned int len" 48.Ft void 49.Fn SHA1_Final "unsigned char digest[20]" "SHA_CTX *context" 50.Ft "char *" 51.Fn SHA1_End "SHA_CTX *context" "char *buf" 52.Ft "char *" 53.Fn SHA1_File "const char *filename" "char *buf" 54.Ft "char *" 55.Fn SHA1_Data "const unsigned char *data" "unsigned int len" "char *buf" 56.Sh DESCRIPTION 57The 58.Li SHA_ 59and 60.Li SHA1_ 61functions calculate a 160-bit cryptographic checksum (digest) 62for any number of input bytes. A cryptographic checksum is a one-way 63hash function; that is, it is computationally impractical to find 64the input corresponding to a particular output. This net result is 65a ``fingerprint'' of the input-data, which doesn't disclose the actual 66input. 67.Pp 68.Tn SHA 69.Pq \&or Tn SHA-0 70is the original Secure Hash Algorithm specified in 71.Tn FIPS 72160. It was quickly proven insecure, and has been superseded by 73.Tn SHA-1 . 74.Tn SHA-0 75is included for compatibility purposes only. 76.Pp 77The 78.Fn SHA1_Init , 79.Fn SHA1_Update , 80and 81.Fn SHA1_Final 82functions are the core functions. Allocate an SHA_CTX, initialize it with 83.Fn SHA1_Init , 84run over the data with 85.Fn SHA1_Update , 86and finally extract the result using 87.Fn SHA1_Final . 88.Pp 89.Fn SHA1_End 90is a wrapper for 91.Fn SHA1_Final 92which converts the return value to a 41-character 93(including the terminating '\e0') 94.Tn ASCII 95string which represents the 160 bits in hexadecimal. 96.Pp 97.Fn SHA1_File 98calculates the digest of a file, and uses 99.Fn SHA1_End 100to return the result. 101If the file cannot be opened, a null pointer is returned. 102.Fn SHA1_Data 103calculates the digest of a chunk of data in memory, and uses 104.Fn SHA1_End 105to return the result. 106.Pp 107When using 108.Fn SHA1_End , 109.Fn SHA1_File , 110or 111.Fn SHA1_Data , 112the 113.Ar buf 114argument can be a null pointer, in which case the returned string 115is allocated with 116.Xr malloc 3 117and subsequently must be explicitly deallocated using 118.Xr free 3 119after use. 120If the 121.Ar buf 122argument is non-null it must point to at least 41 characters of buffer space. 123.Sh SEE ALSO 124.Xr md2 3 , 125.Xr md4 3 , 126.Xr md5 3 , 127.Xr ripemd 3 128.Sh AUTHORS 129The core hash routines were implemented by Eric Young based on the 130published 131.Tn FIPS 132standards. 133.Sh HISTORY 134These functions appeared in 135.Fx 4.0 . 136.Sh BUGS 137No method is known to exist which finds two files having the same hash value, 138nor to find a file with a specific hash value. 139There is on the other hand no guarantee that such a method doesn't exist. 140.Pp 141The 142.Tn IA32 143(Intel) implementation of 144.Tn SHA-1 145makes heavy use of the 146.Ql bswapl 147instruction, which is not present on the original 80386. Attempts 148to use 149.Tn SHA-1 150on those processors will cause an illegal instruction trap. 151(Arguably, the kernel should simply emulate this instruction.) 152