lib/libc/md/mdX.3

   1 .\"     $NetBSD: mdX.3,v 1.10 2003/06/13 01:28:41 lukem Exp $
   2 .\"
   3 .\" ----------------------------------------------------------------------------
   4 .\" "THE BEER-WARE LICENSE" (Revision 42):
   5 .\" <phk@login.dkuug.dk> wrote this file.  As long as you retain this notice you
   6 .\" can do whatever you want with this stuff. If we meet some day, and you think
   7 .\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
   8 .\" ----------------------------------------------------------------------------
   9 .\"
  10 .\"     from FreeBSD Id: mdX.3,v 1.7 1996/10/22 16:28:56 phk Exp
  11 .\"
  12 .Dd June 13, 2003
  13 .Dt MDX 3
  14 .Os
  15 .Sh NAME
  16 .Nm MDXInit ,
  17 .Nm MDXUpdate ,
  18 .Nm MDXFinal ,
  19 .Nm MDXEnd ,
  20 .Nm MDXFile ,
  21 .Nm MDXData
  22 .Nd calculate the RSA Data Security, Inc.,
  23 .Dq MDX
  24 message digest
  25 .Sh LIBRARY
  26 .Lb libc
  27 .Sh SYNOPSIS
  28 .In sys/types.h
  29 .In mdX.h
  30 .Ft void
  31 .Fn MDXInit "MDX_CTX *context"
  32 .Ft void
  33 .Fn MDXUpdate "MDX_CTX *context" "const unsigned char *data" "unsigned int len"
  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.
  45 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.
  48 This net result is
  49 a ``fingerprint'' of the input-data, which doesn't disclose the actual
  50 input.
  51 .Pp
  52 MD2 is the slowest, MD4 is the fastest and MD5 is somewhere in the middle.
  53 MD2 can only be used for Privacy-Enhanced Mail.
  54 MD4 has been criticized for being too weak, so MD5 was developed in
  55 response as ``MD4 with safety-belts''.
  56 When in doubt, use MD5.
  57 .Pp
  58 The
  59 .Fn MDXInit ,
  60 .Fn MDXUpdate ,
  61 and
  62 .Fn MDXFinal
  63 functions are the core functions.
  64 Allocate an MDX_CTX, initialize it with
  65 .Fn MDXInit ,
  66 run over the data with
  67 .Fn MDXUpdate ,
  68 and finally extract the result using
  69 .Fn MDXFinal .
  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 HISTORY
 129 These functions appeared in
 130 .Nx 1.3 .
 131 .Sh AUTHORS
 132 The original MDX routines were developed by
 133 .Tn RSA
 134 Data Security, Inc., and published in the above references.
 135 This code is derived directly from these implementations by Poul-Henning Kamp
 136 .Aq Li phk@login.dkuug.dk
 137 .Pp
 138 Phk ristede runen.
 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 .Sh COPYRIGHT