Annotation of src/lib/libc/md/mdX.3, Revision 1.10
1.10 ! lukem 1: .\" $NetBSD: mdX.3,v 1.9 2003/04/16 13:34:41 wiz Exp $
1.1 thorpej 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: .\"
1.10 ! lukem 12: .Dd June 13, 2003
1.1 thorpej 13: .Dt MDX 3
1.3 garbled 14: .Os
1.1 thorpej 15: .Sh NAME
16: .Nm MDXInit ,
17: .Nm MDXUpdate ,
18: .Nm MDXFinal ,
19: .Nm MDXEnd ,
20: .Nm MDXFile ,
21: .Nm MDXData
1.4 enami 22: .Nd calculate the RSA Data Security, Inc.,
23: .Dq MDX
24: message digest
1.2 perry 25: .Sh LIBRARY
26: .Lb libc
1.1 thorpej 27: .Sh SYNOPSIS
1.9 wiz 28: .In sys/types.h
29: .In mdX.h
1.1 thorpej 30: .Ft void
31: .Fn MDXInit "MDX_CTX *context"
32: .Ft void
1.10 ! lukem 33: .Fn MDXUpdate "MDX_CTX *context" "const unsigned char *data" "unsigned int len"
1.1 thorpej 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 *"
1.10 ! lukem 39: .Fn MDXFile "const char *filename" "char *buf"
1.1 thorpej 40: .Ft "char *"
1.10 ! lukem 41: .Fn MDXData "const unsigned char *data" "unsigned int len" "char *buf"
1.1 thorpej 42: .Sh DESCRIPTION
43: The MDX functions calculate a 128-bit cryptographic checksum (digest)
1.8 wiz 44: for any number of input bytes.
45: A cryptographic checksum is a one-way
1.1 thorpej 46: hash-function, that is, you cannot find (except by exhaustive search)
1.8 wiz 47: the input corresponding to a particular output.
48: This net result is
1.1 thorpej 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
1.8 wiz 55: response as ``MD4 with safety-belts''.
56: When in doubt, use MD5.
1.1 thorpej 57: .Pp
58: The
59: .Fn MDXInit ,
60: .Fn MDXUpdate ,
61: and
62: .Fn MDXFinal
1.8 wiz 63: functions are the core functions.
64: Allocate an MDX_CTX, initialize it with
1.1 thorpej 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
1.5 wiz 80: calculates the digest of a file, and uses
1.1 thorpej 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 ,
1.5 wiz 94: the
1.1 thorpej 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.
1.5 wiz 102: If the
1.1 thorpej 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
1.5 wiz 125: .%A RSA Laboratories
1.1 thorpej 126: .%T Frequently Asked Questions About today's Cryptography
127: .Re
1.5 wiz 128: .Sh HISTORY
129: These functions appeared in
130: .Nx 1.3 .
131: .Sh AUTHORS
1.1 thorpej 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.
1.6 wiz 143: .Sh COPYRIGHT
CVSweb <webmaster@jp.NetBSD.org>