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