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