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