Sync libmd with FreeBSD:
[dragonfly.git] / lib / libmd / ripemd.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.\"
9.\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp
3cd01911
SW
10.\" $FreeBSD: src/lib/libmd/ripemd.3,v 1.15 2005/02/13 22:25:13 ru Exp $
11.\" $DragonFly: src/lib/libmd/ripemd.3,v 1.4 2008/09/11 20:25:34 swildner Exp $
984263bc
MD
12.\"
13.Dd February 26, 1999
14.Dt RIPEMD 3
15.Os
16.Sh NAME
17.Nm RIPEMD160_Init ,
18.Nm RIPEMD160_Update ,
19.Nm RIPEMD160_Final ,
20.Nm RIPEMD160_End ,
21.Nm RIPEMD160_File ,
3cd01911 22.Nm RIPEMD160_FileChunk ,
984263bc
MD
23.Nm RIPEMD160_Data
24.Nd calculate the RIPEMD160 message digest
25.Sh LIBRARY
26.Lb libmd
27.Sh SYNOPSIS
28.In sys/types.h
29.In ripemd.h
30.Ft void
31.Fn RIPEMD160_Init "RIPEMD160_CTX *context"
32.Ft void
33.Fn RIPEMD160_Update "RIPEMD160_CTX *context" "const unsigned char *data" "unsigned int len"
34.Ft void
35.Fn RIPEMD160_Final "unsigned char digest[20]" "RIPEMD160_CTX *context"
36.Ft "char *"
37.Fn RIPEMD160_End "RIPEMD160_CTX *context" "char *buf"
38.Ft "char *"
39.Fn RIPEMD160_File "const char *filename" "char *buf"
40.Ft "char *"
3cd01911
SW
41.Fn RIPEMD160_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
42.Ft "char *"
984263bc
MD
43.Fn RIPEMD160_Data "const unsigned char *data" "unsigned int len" "char *buf"
44.Sh DESCRIPTION
45The
46.Li RIPEMD160_
47functions calculate a 160-bit cryptographic checksum (digest)
3cd01911
SW
48for any number of input bytes.
49A cryptographic checksum is a one-way
984263bc 50hash function; that is, it is computationally impractical to find
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
56The
3cd01911 57.Fn RIPEMD160_Init ,
984263bc
MD
58.Fn RIPEMD160_Update ,
59and
60.Fn RIPEMD160_Final
3cd01911
SW
61functions are the core functions.
62Allocate an
63.Vt RIPEMD160_CTX ,
64initialize it with
984263bc
MD
65.Fn RIPEMD160_Init ,
66run over the data with
67.Fn RIPEMD160_Update ,
68and finally extract the result using
69.Fn RIPEMD160_Final .
70.Pp
3cd01911 71The
984263bc 72.Fn RIPEMD160_End
3cd01911 73function is a wrapper for
984263bc
MD
74.Fn RIPEMD160_Final
75which converts the return value to a 41-character
76(including the terminating '\e0')
77.Tn ASCII
78string which represents the 160 bits in hexadecimal.
79.Pp
3cd01911 80The
984263bc 81.Fn RIPEMD160_File
3cd01911 82function calculates the digest of a file, and uses
984263bc
MD
83.Fn RIPEMD160_End
84to return the result.
85If the file cannot be opened, a null pointer is returned.
3cd01911
SW
86The
87.Fn RIPEMD160_FileChunk
88function is similar to
89.Fn RIPEMD160_File ,
90but it only calculates the digest over a byte-range of the file specified,
91starting at
92.Fa offset
93and spanning
94.Fa length
95bytes.
96If the
97.Fa length
98parameter is specified as 0, or more than the length of the remaining part
99of the file,
100.Fn RIPEMD160_FileChunk
101calculates the digest from
102.Fa offset
103to the end of file.
104The
984263bc 105.Fn RIPEMD160_Data
3cd01911 106function calculates the digest of a chunk of data in memory, and uses
984263bc
MD
107.Fn RIPEMD160_End
108to return the result.
109.Pp
110When using
111.Fn RIPEMD160_End ,
112.Fn RIPEMD160_File ,
113or
114.Fn RIPEMD160_Data ,
115the
116.Fa buf
117argument can be a null pointer, in which case the returned string
118is allocated with
119.Xr malloc 3
120and subsequently must be explicitly deallocated using
121.Xr free 3
122after use.
123If the
124.Fa buf
125argument is non-null it must point to at least 41 characters of buffer space.
126.Sh SEE ALSO
127.Xr md2 3 ,
128.Xr md4 3 ,
129.Xr md5 3 ,
130.Xr sha 3
0b84df5c
SW
131.Sh HISTORY
132These functions appeared in
133.Fx 4.0 .
984263bc
MD
134.Sh AUTHORS
135The core hash routines were implemented by Eric Young based on the
136published
137.Tn RIPEMD160
138specification.
984263bc
MD
139.Sh BUGS
140No method is known to exist which finds two files having the same hash value,
141nor to find a file with a specific hash value.
3cd01911 142There is on the other hand no guarantee that such a method does not exist.