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