lib/libc/hash/md2/md2.3

   1 .\" $NetBSD: md2.3,v 1.1 2005/09/24 20:51:14 elad 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 September 24, 2005
  13 .Dt MD2 3
  14 .Os
  15 .Sh NAME
  16 .Nm MD2Init ,
  17 .Nm MD2Update ,
  18 .Nm MD2Final ,
  19 .Nm MD2End ,
  20 .Nm MD2File ,
  21 .Nm MD2Data
  22 .Nd calculate the RSA Data Security, Inc.,
  23 .Dq MD2
  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 MD2Init "MD2_CTX *context"
  32 .Ft void
  33 .Fn MD2Update "MD2_CTX *context" "const unsigned char *data" "unsigned int len"
  34 .Ft void
  35 .Fn MD2Final "unsigned char digest[16]" "MD2_CTX *context"
  36 .Ft "char *"
  37 .Fn MD2End "MD2_CTX *context" "char *buf"
  38 .Ft "char *"
  39 .Fn MD2File "const char *filename" "char *buf"
  40 .Ft "char *"
  41 .Fn MD2Data "const unsigned char *data" "unsigned int len" "char *buf"
  42 .Sh DESCRIPTION
  43 The MD2 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 The MD2 routines should not be used for any security-related purpose.
  53 .Pp
  54 The
  55 .Fn MD2Init ,
  56 .Fn MD2Update ,
  57 and
  58 .Fn MD2Final
  59 functions are the core functions.
  60 Allocate an MD2_CTX, initialize it with
  61 .Fn MD2Init ,
  62 run over the data with
  63 .Fn MD2Update ,
  64 and finally extract the result using
  65 .Fn MD2Final .
  66 .Pp
  67 .Fn MD2End
  68 is a wrapper for
  69 .Fn MD2Final
  70 which converts the return value to a 33-character
  71 (including the terminating '\e0')
  72 .Tn ASCII
  73 string which represents the 128 bits in hexadecimal.
  74 .Pp
  75 .Fn MD2File
  76 calculates the digest of a file, and uses
  77 .Fn MD2End
  78 to return the result.
  79 If the file cannot be opened, a null pointer is returned.
  80 .Fn MD2Data
  81 calculates the digest of a chunk of data in memory, and uses
  82 .Fn MD2End
  83 to return the result.
  84 .Pp
  85 When using
  86 .Fn MD2End ,
  87 .Fn MD2File ,
  88 or
  89 .Fn MD2Data ,
  90 the
  91 .Ar buf
  92 argument can be a null pointer, in which case the returned string
  93 is allocated with
  94 .Xr malloc 3
  95 and subsequently must be explicitly deallocated using
  96 .Xr free 3
  97 after use.
  98 If the
  99 .Ar buf
 100 argument is non-null it must point to at least 33 characters of buffer space.
 101 .Sh SEE ALSO
 102 .Xr md2 3 ,
 103 .Rs
 104 .%A B. Kaliski
 105 .%T The MD2 Message-Digest Algorithm
 106 .%O RFC 1319
 107 .Re
 108 .Rs
 109 .%A RSA Laboratories
 110 .%T Frequently Asked Questions About today's Cryptography
 111 .Re
 112 .Sh HISTORY
 113 These functions appeared in
 114 .Nx 1.3 .
 115 .Sh AUTHORS
 116 The original MD2 routines were developed by
 117 .Tn RSA
 118 Data Security, Inc., and published in the above references.
 119 This code is a public domain implementation by Andrew Brown.
 120 .Sh BUGS
 121 No method is known to exist which finds two files having the same hash value,
 122 nor to find a file with a specific hash value.
 123 There is on the other hand no guarantee that such a method doesn't exist.