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.\" $FreeBSD$ 10.\" 11.Dd February 11, 1999 12.Dt MDX 3 13.Os 14.Sh NAME 15.Nm MDXInit , 16.Nm MDXUpdate , 17.Nm MDXPad , 18.Nm MDXFinal , 19.Nm MDXEnd , 20.Nm MDXFile , 21.Nm MDXFileChunk , 22.Nm MDXData 23.Nd calculate the RSA Data Security, Inc., ``MDX'' message digest 24.Sh LIBRARY 25.Lb libmd 26.Sh SYNOPSIS 27.In sys/types.h 28.In mdX.h 29.Ft void 30.Fn MDXInit "MDX_CTX *context" 31.Ft void 32.Fn MDXUpdate "MDX_CTX *context" "const unsigned char *data" "unsigned int len" 33.Ft void 34.Fn MDXPad "MDX_CTX *context" 35.Ft void 36.Fn MDXFinal "unsigned char digest[16]" "MDX_CTX *context" 37.Ft "char *" 38.Fn MDXEnd "MDX_CTX *context" "char *buf" 39.Ft "char *" 40.Fn MDXFile "const char *filename" "char *buf" 41.Ft "char *" 42.Fn MDXFileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 43.Ft "char *" 44.Fn MDXData "const unsigned char *data" "unsigned int len" "char *buf" 45.Sh DESCRIPTION 46The MDX functions calculate a 128-bit cryptographic checksum (digest) 47for any number of input bytes. A cryptographic checksum is a one-way 48hash-function, that is, you cannot find (except by exhaustive search) 49the input corresponding to a particular output. This net result is 50a ``fingerprint'' of the input-data, which doesn't disclose the actual 51input. 52.Pp 53MD2 is the slowest, MD4 is the fastest and MD5 is somewhere in the middle. 54MD2 can only be used for Privacy-Enhanced Mail. 55MD4 has now been broken; it should only be used where necessary for 56backward compatibility. 57MD5 has not yet (1999-02-11) been broken, but sufficient attacks have been 58made that its security is in some doubt. The attacks on both MD4 and MD5 59are both in the nature of finding ``collisions'' \- that is, multiple 60inputs which hash to the same value; it is still unlikely for an attacker 61to be able to determine the exact original input given a hash value. 62.Pp 63The 64.Fn MDXInit , 65.Fn MDXUpdate , 66and 67.Fn MDXFinal 68functions are the core functions. Allocate an MDX_CTX, initialize it with 69.Fn MDXInit , 70run over the data with 71.Fn MDXUpdate , 72and finally extract the result using 73.Fn MDXFinal . 74.Pp 75.Fn MDXPad 76can be used to pad message data in same way 77as done by 78.Fn MDXFinal 79without terminating calculation. 80.Pp 81.Fn MDXEnd 82is a wrapper for 83.Fn MDXFinal 84which converts the return value to a 33-character 85(including the terminating '\e0') 86.Tn ASCII 87string which represents the 128 bits in hexadecimal. 88.Pp 89.Fn MDXFile 90calculates the digest of a file, and uses 91.Fn MDXEnd 92to return the result. 93If the file cannot be opened, a null pointer is returned. 94.Fn MDXFileChunk 95is similar to 96.Fn MDXFile , 97but it only calculates the digest over a byte-range of the file specified, 98starting at 99.Fa offset 100and spanning 101.Fa length 102bytes. 103If the 104.Fa length 105parameter is specified as 0, or more than the length of the remaining part 106of the file, 107.Fn MDXFileChunk 108calculates the digest from 109.Fa offset 110to the end of file. 111.Fn MDXData 112calculates the digest of a chunk of data in memory, and uses 113.Fn MDXEnd 114to return the result. 115.Pp 116When using 117.Fn MDXEnd , 118.Fn MDXFile , 119or 120.Fn MDXData , 121the 122.Fa buf 123argument can be a null pointer, in which case the returned string 124is allocated with 125.Xr malloc 3 126and subsequently must be explicitly deallocated using 127.Xr free 3 128after use. 129If the 130.Fa buf 131argument is non-null it must point to at least 33 characters of buffer space. 132.Sh SEE ALSO 133.Xr md2 3 , 134.Xr md4 3 , 135.Xr md5 3 , 136.Xr sha 3 137.Rs 138.%A B. Kaliski 139.%T The MD2 Message-Digest Algorithm 140.%O RFC 1319 141.Re 142.Rs 143.%A R. Rivest 144.%T The MD4 Message-Digest Algorithm 145.%O RFC 1186 146.Re 147.Rs 148.%A R. Rivest 149.%T The MD5 Message-Digest Algorithm 150.%O RFC 1321 151.Re 152.Rs 153.%A RSA Laboratories 154.%T Frequently Asked Questions About today's Cryptography 155.%O \&<http://www.rsa.com/rsalabs/faq/> 156.Re 157.Rs 158.%A H. Dobbertin 159.%T Alf Swindles Ann 160.%J CryptoBytes 161.%N 1(3):5 162.%D 1995 163.Re 164.Rs 165.%A MJ. B. Robshaw 166.%T On Recent Results for MD2, MD4 and MD5 167.%J RSA Laboratories Bulletin 168.%N 4 169.%D November 12, 1996 170.Re 171.Sh AUTHORS 172The original MDX routines were developed by 173.Tn RSA 174Data Security, Inc., and published in the above references. 175This code is derived directly from these implementations by 176.An Poul-Henning Kamp Aq phk@FreeBSD.org 177.Pp 178Phk ristede runen. 179.Sh HISTORY 180These functions appeared in 181.Fx 2.0 . 182.Sh BUGS 183No method is known to exist which finds two files having the same hash value, 184nor to find a file with a specific hash value. 185There is on the other hand no guarantee that such a method doesn't exist. 186.Pp 187MD2 has only been licensed for use in Privacy Enhanced Mail. 188Use MD4 or MD5 if that isn't what you're doing. 189