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