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 75The 76.Fn MDXPad 77function can be used to pad message data in same way 78as done by 79.Fn MDXFinal 80without terminating calculation. 81.Pp 82The 83.Fn MDXEnd 84function is a wrapper for 85.Fn MDXFinal 86which converts the return value to a 33-character 87(including the terminating '\e0') 88.Tn ASCII 89string which represents the 128 bits in hexadecimal. 90.Pp 91The 92.Fn MDXFile 93function calculates the digest of a file, and uses 94.Fn MDXEnd 95to return the result. 96If the file cannot be opened, a null pointer is returned. 97The 98.Fn MDXFileChunk 99function is similar to 100.Fn MDXFile , 101but it only calculates the digest over a byte-range of the file specified, 102starting at 103.Fa offset 104and spanning 105.Fa length 106bytes. 107If the 108.Fa length 109parameter is specified as 0, or more than the length of the remaining part 110of the file, 111.Fn MDXFileChunk 112calculates the digest from 113.Fa offset 114to the end of file. 115The 116.Fn MDXData 117function calculates the digest of a chunk of data in memory, and uses 118.Fn MDXEnd 119to return the result. 120.Pp 121When using 122.Fn MDXEnd , 123.Fn MDXFile , 124or 125.Fn MDXData , 126the 127.Fa buf 128argument can be a null pointer, in which case the returned string 129is allocated with 130.Xr malloc 3 131and subsequently must be explicitly deallocated using 132.Xr free 3 133after use. 134If the 135.Fa buf 136argument is non-null it must point to at least 33 characters of buffer space. 137.Sh SEE ALSO 138.Xr md2 3 , 139.Xr md4 3 , 140.Xr md5 3 , 141.Xr sha 3 142.Rs 143.%A B. Kaliski 144.%T The MD2 Message-Digest Algorithm 145.%O RFC 1319 146.Re 147.Rs 148.%A R. Rivest 149.%T The MD4 Message-Digest Algorithm 150.%O RFC 1186 151.Re 152.Rs 153.%A R. Rivest 154.%T The MD5 Message-Digest Algorithm 155.%O RFC 1321 156.Re 157.Rs 158.%A RSA Laboratories 159.%T Frequently Asked Questions About today's Cryptography 160.%O \&<http://www.rsa.com/rsalabs/faq/> 161.Re 162.Rs 163.%A H. Dobbertin 164.%T Alf Swindles Ann 165.%J CryptoBytes 166.%N 1(3):5 167.%D 1995 168.Re 169.Rs 170.%A MJ. B. Robshaw 171.%T On Recent Results for MD2, MD4 and MD5 172.%J RSA Laboratories Bulletin 173.%N 4 174.%D November 12, 1996 175.Re 176.Sh AUTHORS 177The original MDX routines were developed by 178.Tn RSA 179Data Security, Inc., and published in the above references. 180This code is derived directly from these implementations by 181.An Poul-Henning Kamp Aq phk@FreeBSD.org 182.Pp 183Phk ristede runen. 184.Sh HISTORY 185These functions appeared in 186.Fx 2.0 . 187.Sh BUGS 188No method is known to exist which finds two files having the same hash value, 189nor to find a file with a specific hash value. 190There is on the other hand no guarantee that such a method doesn't exist. 191.Pp 192MD2 has only been licensed for use in Privacy Enhanced Mail. 193Use MD4 or MD5 if that isn't what you're doing. 194