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 .\"     $Id: mdX.3,v 1.12 1998/03/19 07:34:12 charnier Exp $
  10 .\"
  11 .Dd October 9, 1996
  12 .Dt MDX 3
  13 .Os FreeBSD 2
  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 SYNOPSIS
  24 .Fd #include <sys/types.h>
  25 .Fd #include <mdX.h>
  26 .Ft void
  27 .Fn MDXInit "MDX_CTX *context"
  28 .Ft void
  29 .Fn MDXUpdate "MDX_CTX *context" "const unsigned char *data" "unsigned int len"
  30 .Ft void
  31 .Fn MDXPad "MDX_CTX *context"
  32 .Ft void
  33 .Fn MDXFinal "unsigned char digest[16]" "MDX_CTX *context"
  34 .Ft "char *"
  35 .Fn MDXEnd "MDX_CTX *context" "char *buf"
  36 .Ft "char *"
  37 .Fn MDXFile "const char *filename" "char *buf"
  38 .Ft "char *"
  39 .Fn MDXData "const unsigned char *data" "unsigned int len" "char *buf"
  40 .Sh DESCRIPTION
  41 The MDX functions calculate a 128-bit cryptographic checksum (digest)
  42 for any number of input bytes.  A cryptographic checksum is a one-way
  43 hash-function, that is, you cannot find (except by exhaustive search)
  44 the input corresponding to a particular output.  This net result is
  45 a ``fingerprint'' of the input-data, which doesn't disclose the actual
  46 input.
  47 .Pp
  48 MD2 is the slowest, MD4 is the fastest and MD5 is somewhere in the middle.
  49 MD2 can only be used for Privacy-Enhanced Mail.
  50 MD4 has been criticized for being too weak, so MD5 was developed in
  51 response as ``MD4 with safety-belts''.  When in doubt, use MD5.
  52 .Pp
  53 The
  54 .Fn MDXInit ,
  55 .Fn MDXUpdate ,
  56 and
  57 .Fn MDXFinal
  58 functions are the core functions.  Allocate an MDX_CTX, initialize it with
  59 .Fn MDXInit ,
  60 run over the data with
  61 .Fn MDXUpdate ,
  62 and finally extract the result using
  63 .Fn MDXFinal .
  64 .Pp
  65 .Fn MDXPad
  66 can be used to pad message data in same way
  67 as done by
  68 .Fn MDXFinal
  69 without terminating calculation.
  70 .Pp
  71 .Fn MDXEnd
  72 is a wrapper for
  73 .Fn MDXFinal
  74 which converts the return value to a 33-character
  75 (including the terminating '\e0')
  76 .Tn ASCII
  77 string which represents the 128 bits in hexadecimal.
  78 .Pp
  79 .Fn MDXFile
  80 calculates the digest of a file, and uses
  81 .Fn MDXEnd
  82 to return the result.
  83 If the file cannot be opened, a null pointer is returned.
  84 .Fn MDXData
  85 calculates the digest of a chunk of data in memory, and uses
  86 .Fn MDXEnd
  87 to return the result.
  88 .Pp
  89 When using
  90 .Fn MDXEnd ,
  91 .Fn MDXFile ,
  92 or
  93 .Fn MDXData ,
  94 the
  95 .Ar buf
  96 argument can be a null pointer, in which case the returned string
  97 is allocated with
  98 .Xr malloc 3
  99 and subsequently must be explicitly deallocated using
 100 .Xr free 3
 101 after use.
 102 If the
 103 .Ar buf
 104 argument is non-null it must point to at least 33 characters of buffer space.
 105 .Sh SEE ALSO
 106 .Xr md2 3 ,
 107 .Xr md4 3 ,
 108 .Xr md5 3
 109 .Rs
 110 .%A B. Kaliski
 111 .%T The MD2 Message-Digest Algorithm
 112 .%O RFC 1319
 113 .Re
 114 .Rs
 115 .%A R. Rivest
 116 .%T The MD4 Message-Digest Algorithm
 117 .%O RFC 1186
 118 .Re
 119 .Rs
 120 .%A R. Rivest
 121 .%T The MD5 Message-Digest Algorithm
 122 .%O RFC 1321
 123 .Re
 124 .Rs
 125 .%A RSA Laboratories
 126 .%T Frequently Asked Questions About today's Cryptography
 127 .Re
 128 .Sh AUTHORS
 129 The original MDX routines were developed by
 130 .Tn RSA
 131 Data Security, Inc., and published in the above references.
 132 This code is derived directly from these implementations by
 133 .An Poul-Henning Kamp Aq phk@login.dkuug.dk
 134 .Pp
 135 Phk ristede runen.
 136 .Sh HISTORY
 137 These functions appeared in
 138 .Fx 2.0 .
 139 .Sh BUGS
 140 No method is known to exist which finds two files having the same hash value,
 141 nor to find a file with a specific hash value.
 142 There is on the other hand no guarantee that such a method doesn't exist.
 143 .Pp
 144 MD2 has only been licensed for use in Privacy Enhanced Mail.
 145 Use MD4 or MD5 if that isn't what you're doing.
 146 .Sh COPYRIGHT