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