xref: /freebsd/lib/libmd/mdX.3 (revision 74bf4e164ba5851606a27d4feff27717452583e5)
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.\" $FreeBSD$
10.\"
11.Dd February 11, 1999
12.Dt MDX 3
13.Os
14.Sh NAME
15.Nm MDXInit ,
16.Nm MDXUpdate ,
17.Nm MDXPad ,
18.Nm MDXFinal ,
19.Nm MDXEnd ,
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 unsigned char *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 MDXFile "const char *filename" "char *buf"
41.Ft "char *"
42.Fn MDXFileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
43.Ft "char *"
44.Fn MDXData "const unsigned char *data" "unsigned int len" "char *buf"
45.Sh DESCRIPTION
46The MDX functions calculate a 128-bit cryptographic checksum (digest)
47for any number of input bytes.
48A cryptographic checksum is a one-way
49hash-function, that is, you cannot find (except by exhaustive search)
50the input corresponding to a particular output.
51This net result is a
52.Dq fingerprint
53of the input-data, which doesn't disclose the actual input.
54.Pp
55MD2 is the slowest, MD4 is the fastest and MD5 is somewhere in the middle.
56MD2 can only be used for Privacy-Enhanced Mail.
57MD4 has now been broken; it should only be used where necessary for
58backward compatibility.
59MD5 has not yet (1999-02-11) been broken, but sufficient attacks have been
60made that its security is in some doubt.
61The attacks on both MD4 and MD5
62are both in the nature of finding
63.Dq collisions
64\[en]
65that is, multiple
66inputs which hash to the same value; it is still unlikely for an attacker
67to be able to determine the exact original input given a hash value.
68.Pp
69The
70.Fn MDXInit ,
71.Fn MDXUpdate ,
72and
73.Fn MDXFinal
74functions are the core functions.
75Allocate an
76.Vt MDX_CTX ,
77initialize it with
78.Fn MDXInit ,
79run over the data with
80.Fn MDXUpdate ,
81and finally extract the result using
82.Fn MDXFinal .
83.Pp
84The
85.Fn MDXPad
86function can be used to pad message data in same way
87as done by
88.Fn MDXFinal
89without terminating calculation.
90.Pp
91The
92.Fn MDXEnd
93function is a wrapper for
94.Fn MDXFinal
95which converts the return value to a 33-character
96(including the terminating '\e0')
97.Tn ASCII
98string which represents the 128 bits in hexadecimal.
99.Pp
100The
101.Fn MDXFile
102function calculates the digest of a file, and uses
103.Fn MDXEnd
104to return the result.
105If the file cannot be opened, a null pointer is returned.
106The
107.Fn MDXFileChunk
108function is similar to
109.Fn MDXFile ,
110but it only calculates the digest over a byte-range of the file specified,
111starting at
112.Fa offset
113and spanning
114.Fa length
115bytes.
116If the
117.Fa length
118parameter is specified as 0, or more than the length of the remaining part
119of the file,
120.Fn MDXFileChunk
121calculates the digest from
122.Fa offset
123to the end of file.
124The
125.Fn MDXData
126function calculates the digest of a chunk of data in memory, and uses
127.Fn MDXEnd
128to return the result.
129.Pp
130When using
131.Fn MDXEnd ,
132.Fn MDXFile ,
133or
134.Fn MDXData ,
135the
136.Fa buf
137argument can be a null pointer, in which case the returned string
138is allocated with
139.Xr malloc 3
140and subsequently must be explicitly deallocated using
141.Xr free 3
142after use.
143If the
144.Fa buf
145argument is non-null it must point to at least 33 characters of buffer space.
146.Sh SEE ALSO
147.Xr md2 3 ,
148.Xr md4 3 ,
149.Xr md5 3 ,
150.Xr sha 3
151.Rs
152.%A B. Kaliski
153.%T The MD2 Message-Digest Algorithm
154.%O RFC 1319
155.Re
156.Rs
157.%A R. Rivest
158.%T The MD4 Message-Digest Algorithm
159.%O RFC 1186
160.Re
161.Rs
162.%A R. Rivest
163.%T The MD5 Message-Digest Algorithm
164.%O RFC 1321
165.Re
166.Rs
167.%A RSA Laboratories
168.%T Frequently Asked Questions About today's Cryptography
169.%O \&<http://www.rsa.com/rsalabs/faq/>
170.Re
171.Rs
172.%A H. Dobbertin
173.%T Alf Swindles Ann
174.%J CryptoBytes
175.%N 1(3):5
176.%D 1995
177.Re
178.Rs
179.%A MJ. B. Robshaw
180.%T On Recent Results for MD2, MD4 and MD5
181.%J RSA Laboratories Bulletin
182.%N 4
183.%D November 12, 1996
184.Re
185.Sh AUTHORS
186The original MDX routines were developed by
187.Tn RSA
188Data Security, Inc., and published in the above references.
189This code is derived directly from these implementations by
190.An Poul-Henning Kamp Aq phk@FreeBSD.org
191.Pp
192Phk ristede runen.
193.Sh HISTORY
194These functions appeared in
195.Fx 2.0 .
196.Sh BUGS
197No method is known to exist which finds two files having the same hash value,
198nor to find a file with a specific hash value.
199There is on the other hand no guarantee that such a method doesn't exist.
200.Pp
201MD2 has only been licensed for use in Privacy Enhanced Mail.
202Use MD4 or MD5 if that isn't what you're doing.
203