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 H. Dobbertin 168.%T Alf Swindles Ann 169.%J CryptoBytes 170.%N 1(3):5 171.%D 1995 172.Re 173.Rs 174.%A MJ. B. Robshaw 175.%T On Recent Results for MD2, MD4 and MD5 176.%J RSA Laboratories Bulletin 177.%N 4 178.%D November 12, 1996 179.Re 180.Sh HISTORY 181These functions appeared in 182.Fx 2.0 . 183.Sh AUTHORS 184The original MDX routines were developed by 185.Tn RSA 186Data Security, Inc., and published in the above references. 187This code is derived directly from these implementations by 188.An Poul-Henning Kamp Aq phk@FreeBSD.org 189.Pp 190Phk ristede runen. 191.Sh BUGS 192No method is known to exist which finds two files having the same hash value, 193nor to find a file with a specific hash value. 194There is on the other hand no guarantee that such a method does not exist. 195.Pp 196MD2 has only been licensed for use in Privacy Enhanced Mail. 197Use MD4 or MD5 if that is not what you are doing. 198