lib/libmd/mdX.3

   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: src/lib/libmd/mdX.3,v 1.30 2006/01/17 15:35:56 phk Exp $
  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
  46 The MDX functions calculate a 128-bit cryptographic checksum (digest)
  47 for any number of input bytes.
  48 A cryptographic checksum is a one-way
  49 hash-function, that is, you cannot find (except by exhaustive search)
  50 the input corresponding to a particular output.
  51 This net result is a
  52 .Dq fingerprint
  53 of the input-data, which does not disclose the actual input.
  54 .Pp
  55 MD2 is the slowest, MD4 is the fastest and MD5 is somewhere in the middle.
  56 MD2 can only be used for Privacy-Enhanced Mail.
  57 MD4 has now been broken; it should only be used where necessary for
  58 backward compatibility.
  59 MD5 has not yet (1999-02-11) been broken, but sufficient attacks have been
  60 made that its security is in some doubt.
  61 The attacks on both MD4 and MD5
  62 are both in the nature of finding
  63 .Dq collisions
  64 \[en]
  65 that is, multiple
  66 inputs which hash to the same value; it is still unlikely for an attacker
  67 to be able to determine the exact original input given a hash value.
  68 .Pp
  69 The
  70 .Fn MDXInit ,
  71 .Fn MDXUpdate ,
  72 and
  73 .Fn MDXFinal
  74 functions are the core functions.
  75 Allocate an
  76 .Vt MDX_CTX ,
  77 initialize it with
  78 .Fn MDXInit ,
  79 run over the data with
  80 .Fn MDXUpdate ,
  81 and finally extract the result using
  82 .Fn MDXFinal .
  83 .Pp
  84 The
  85 .Fn MDXPad
  86 function can be used to pad message data in same way
  87 as done by
  88 .Fn MDXFinal
  89 without terminating calculation.
  90 .Pp
  91 The
  92 .Fn MDXEnd
  93 function is a wrapper for
  94 .Fn MDXFinal
  95 which converts the return value to a 33-character
  96 (including the terminating '\e0')
  97 .Tn ASCII
  98 string which represents the 128 bits in hexadecimal.
  99 .Pp
 100 The
 101 .Fn MDXFile
 102 function calculates the digest of a file, and uses
 103 .Fn MDXEnd
 104 to return the result.
 105 If the file cannot be opened, a null pointer is returned.
 106 The
 107 .Fn MDXFileChunk
 108 function is similar to
 109 .Fn MDXFile ,
 110 but it only calculates the digest over a byte-range of the file specified,
 111 starting at
 112 .Fa offset
 113 and spanning
 114 .Fa length
 115 bytes.
 116 If the
 117 .Fa length
 118 parameter is specified as 0, or more than the length of the remaining part
 119 of the file,
 120 .Fn MDXFileChunk
 121 calculates the digest from
 122 .Fa offset
 123 to the end of file.
 124 The
 125 .Fn MDXData
 126 function calculates the digest of a chunk of data in memory, and uses
 127 .Fn MDXEnd
 128 to return the result.
 129 .Pp
 130 When using
 131 .Fn MDXEnd ,
 132 .Fn MDXFile ,
 133 or
 134 .Fn MDXData ,
 135 the
 136 .Fa buf
 137 argument can be a null pointer, in which case the returned string
 138 is allocated with
 139 .Xr malloc 3
 140 and subsequently must be explicitly deallocated using
 141 .Xr free 3
 142 after use.
 143 If the
 144 .Fa buf
 145 argument 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 RSA Laboratories
 168 .%T Frequently Asked Questions About today's Cryptography
 169 .%O \&<http://www.rsa.com/rsalabs/faq/>
 170 .Re
 171 .Rs
 172 .%A H. Dobbertin
 173 .%T Alf Swindles Ann
 174 .%J CryptoBytes
 175 .%N 1(3):5
 176 .%D 1995
 177 .Re
 178 .Rs
 179 .%A MJ. B. Robshaw
 180 .%T On Recent Results for MD2, MD4 and MD5
 181 .%J RSA Laboratories Bulletin
 182 .%N 4
 183 .%D November 12, 1996
 184 .Re
 185 .Sh HISTORY
 186 These functions appeared in
 187 .Fx 2.0 .
 188 .Sh AUTHORS
 189 The original MDX routines were developed by
 190 .Tn RSA
 191 Data Security, Inc., and published in the above references.
 192 This code is derived directly from these implementations by
 193 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
 194 .Pp
 195 Phk ristede runen.
 196 .Sh BUGS
 197 No method is known to exist which finds two files having the same hash value,
 198 nor to find a file with a specific hash value.
 199 There is on the other hand no guarantee that such a method does not exist.
 200 .Pp
 201 MD2 has only been licensed for use in Privacy Enhanced Mail.
 202 Use MD4 or MD5 if that is not what you are doing.