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