lib/libmd/mdX.3

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