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