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