lib/libmd/mdX.3

   1 .\"
   2 .\" ----------------------------------------------------------------------------
   3 .\" "THE BEER-WARE LICENSE" (Revision 42):
   4 .\" <phk@FreeBSD.org> 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 .Dd March 8, 2022
  10 .Dt MDX 3
  11 .Os
  12 .Sh NAME
  13 .Nm MDXInit ,
  14 .Nm MDXUpdate ,
  15 .Nm MDXPad ,
  16 .Nm MDXFinal ,
  17 .Nm MDXEnd ,
  18 .Nm MDXFd ,
  19 .Nm MDXFdChunk ,
  20 .Nm MDXFile ,
  21 .Nm MDXFileChunk ,
  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 void *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 MDXFd "int fd" "char *buf"
  41 .Ft "char *"
  42 .Fn MDXFdChunk "int fd" "char *buf" "off_t offset" "off_t length"
  43 .Ft "char *"
  44 .Fn MDXFile "const char *filename" "char *buf"
  45 .Ft "char *"
  46 .Fn MDXFileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  47 .Ft "char *"
  48 .Fn MDXData "const void *data" "unsigned int len" "char *buf"
  49 .Sh DESCRIPTION
  50 The MDX functions calculate a 128-bit cryptographic checksum (digest)
  51 for any number of input bytes.
  52 A cryptographic checksum is a one-way
  53 hash-function, that is, you cannot find (except by exhaustive search)
  54 the input corresponding to a particular output.
  55 This net result is a
  56 .Dq fingerprint
  57 of the input-data, which does not disclose the actual input.
  58 .Pp
  59 MD4 is the fastest and MD5 is somewhat slower.
  60 MD4 has now been broken; it should only be used where necessary for
  61 backward compatibility.
  62 MD5 has not yet (1999-02-11) been broken, but sufficient attacks have been
  63 made that its security is in some doubt.
  64 The attacks on both MD4 and MD5
  65 are both in the nature of finding
  66 .Dq collisions
  67 \[en]
  68 that is, multiple
  69 inputs which hash to the same value; it is still unlikely for an attacker
  70 to be able to determine the exact original input given a hash value.
  71 .Pp
  72 The
  73 .Fn MDXInit ,
  74 .Fn MDXUpdate ,
  75 and
  76 .Fn MDXFinal
  77 functions are the core functions.
  78 Allocate an
  79 .Vt MDX_CTX ,
  80 initialize it with
  81 .Fn MDXInit ,
  82 run over the data with
  83 .Fn MDXUpdate ,
  84 and finally extract the result using
  85 .Fn MDXFinal ,
  86 which will also erase the
  87 .Vt MDX_CTX .
  88 .Pp
  89 The
  90 .Fn MDXPad
  91 function can be used to pad message data in same way
  92 as done by
  93 .Fn MDXFinal
  94 without terminating calculation.
  95 .Pp
  96 The
  97 .Fn MDXEnd
  98 function is a wrapper for
  99 .Fn MDXFinal
 100 which converts the return value to a 33-character
 101 (including the terminating '\e0')
 102 ASCII string which represents the 128 bits in hexadecimal.
 103 .Pp
 104 The
 105 .Fn MDXFile
 106 function calculates the digest of a file, and uses
 107 .Fn MDXEnd
 108 to return the result.
 109 If the file cannot be opened, a null pointer is returned.
 110 The
 111 .Fn MDXFileChunk
 112 function is similar to
 113 .Fn MDXFile ,
 114 but it only calculates the digest over a byte-range of the file specified,
 115 starting at
 116 .Fa offset
 117 and spanning
 118 .Fa length
 119 bytes.
 120 If the
 121 .Fa length
 122 parameter is specified as 0, or more than the length of the remaining part
 123 of the file,
 124 .Fn MDXFileChunk
 125 calculates the digest from
 126 .Fa offset
 127 to the end of file.
 128 The
 129 .Fn MDXData
 130 function calculates the digest of a chunk of data in memory, and uses
 131 .Fn MDXEnd
 132 to return the result.
 133 .Pp
 134 The
 135 .Fn MDXFd
 136 and
 137 .Fn MDXFdChunk
 138 functions are identical to their
 139 .Fn MDXFile
 140 and
 141 .Fn MDXFileChunk
 142 counterparts, with the exception that the first argument is an
 143 .Fa fd
 144 instead of a
 145 .Fa filename .
 146 .Pp
 147 When using
 148 .Fn MDXEnd ,
 149 .Fn MDXFile ,
 150 or
 151 .Fn MDXData ,
 152 the
 153 .Fa buf
 154 argument can be a null pointer, in which case the returned string
 155 is allocated with
 156 .Xr malloc 3
 157 and subsequently must be explicitly deallocated using
 158 .Xr free 3
 159 after use.
 160 If the
 161 .Fa buf
 162 argument is non-null it must point to at least 33 characters of buffer space.
 163 .Sh ERRORS
 164 The
 165 .Fn MDXEnd
 166 function called with a null buf argument may fail and return NULL if:
 167 .Bl -tag -width Er
 168 .It Bq Er ENOMEM
 169 Insufficient storage space is available.
 170 .El
 171 .Pp
 172 The
 173 .Fn MDXFile
 174 and
 175 .Fn MDXFileChunk
 176 may return NULL when underlying
 177 .Xr open 2 ,
 178 .Xr fstat 2 ,
 179 .Xr lseek 2 ,
 180 or
 181 .Xr MDXEnd 3
 182 fail.
 183 .Sh SEE ALSO
 184 .Xr md4 3 ,
 185 .Xr md5 3 ,
 186 .Xr ripemd 3 ,
 187 .Xr sha 3 ,
 188 .Xr sha256 3 ,
 189 .Xr sha512 3 ,
 190 .Xr skein 3
 191 .Rs
 192 .%A R. Rivest
 193 .%T The MD4 Message-Digest Algorithm
 194 .%O RFC 1186
 195 .Re
 196 .Rs
 197 .%A R. Rivest
 198 .%T The MD5 Message-Digest Algorithm
 199 .%O RFC 1321
 200 .Re
 201 .Rs
 202 .%A H. Dobbertin
 203 .%T Alf Swindles Ann
 204 .%J CryptoBytes
 205 .%N 1(3):5
 206 .%D 1995
 207 .Re
 208 .Rs
 209 .%A MJ. B. Robshaw
 210 .%T On Recent Results for MD2, MD4 and MD5
 211 .%J RSA Laboratories Bulletin
 212 .%N 4
 213 .%D November 12, 1996
 214 .Re
 215 .Sh HISTORY
 216 These functions appeared in
 217 .Fx 2.0 .
 218 .Sh AUTHORS
 219 The original MDX routines were developed by
 220 RSA Data Security, Inc., and published in the above references.
 221 This code is derived directly from these implementations by
 222 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
 223 .Pp
 224 Phk ristede runen.
 225 .Sh BUGS
 226 The MD5 algorithm has been proven to be vulnerable to practical collision
 227 attacks and should not be relied upon to produce unique outputs,
 228 .Em nor should they be used as part of a cryptographic signature scheme.