Netgraph port from FreeBSD - initial porting work
[dragonfly.git] / lib / libmd / ripemd.3
blobc9fb13974b77d5a7aa7c53b0b7f86bbe1f365736
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 .\"     From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp
10 .\" $FreeBSD: src/lib/libmd/ripemd.3,v 1.2.2.5 2001/12/17 10:08:31 ru Exp $
11 .\" $DragonFly: src/lib/libmd/ripemd.3,v 1.3 2006/02/17 19:35:07 swildner Exp $
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 ,
22 .Nm RIPEMD160_Data
23 .Nd calculate the RIPEMD160 message digest
24 .Sh LIBRARY
25 .Lb libmd
26 .Sh SYNOPSIS
27 .In sys/types.h
28 .In ripemd.h
29 .Ft void
30 .Fn RIPEMD160_Init "RIPEMD160_CTX *context"
31 .Ft void
32 .Fn RIPEMD160_Update "RIPEMD160_CTX *context" "const unsigned char *data" "unsigned int len"
33 .Ft void
34 .Fn RIPEMD160_Final "unsigned char digest[20]" "RIPEMD160_CTX *context"
35 .Ft "char *"
36 .Fn RIPEMD160_End "RIPEMD160_CTX *context" "char *buf"
37 .Ft "char *"
38 .Fn RIPEMD160_File "const char *filename" "char *buf"
39 .Ft "char *"
40 .Fn RIPEMD160_Data "const unsigned char *data" "unsigned int len" "char *buf"
41 .Sh DESCRIPTION
42 The
43 .Li RIPEMD160_
44 functions calculate a 160-bit cryptographic checksum (digest)
45 for any number of input bytes.  A cryptographic checksum is a one-way
46 hash function; that is, it is computationally impractical to find
47 the input corresponding to a particular output.  This net result is
48 a ``fingerprint'' of the input-data, which doesn't disclose the actual
49 input.
50 .Pp
51 The
52 .Fn RIPEMD160_Init  ,
53 .Fn RIPEMD160_Update ,
54 and
55 .Fn RIPEMD160_Final
56 functions are the core functions.  Allocate an RIPEMD160_CTX, initialize it with
57 .Fn RIPEMD160_Init ,
58 run over the data with
59 .Fn RIPEMD160_Update ,
60 and finally extract the result using
61 .Fn RIPEMD160_Final .
62 .Pp
63 .Fn RIPEMD160_End
64 is a wrapper for
65 .Fn RIPEMD160_Final
66 which converts the return value to a 41-character
67 (including the terminating '\e0')
68 .Tn ASCII
69 string which represents the 160 bits in hexadecimal.
70 .Pp
71 .Fn RIPEMD160_File
72 calculates the digest of a file, and uses
73 .Fn RIPEMD160_End
74 to return the result.
75 If the file cannot be opened, a null pointer is returned.
76 .Fn RIPEMD160_Data
77 calculates the digest of a chunk of data in memory, and uses
78 .Fn RIPEMD160_End
79 to return the result.
80 .Pp
81 When using
82 .Fn RIPEMD160_End ,
83 .Fn RIPEMD160_File ,
85 .Fn RIPEMD160_Data ,
86 the
87 .Fa buf
88 argument can be a null pointer, in which case the returned string
89 is allocated with
90 .Xr malloc 3
91 and subsequently must be explicitly deallocated using
92 .Xr free 3
93 after use.
94 If the
95 .Fa buf
96 argument is non-null it must point to at least 41 characters of buffer space.
97 .Sh SEE ALSO
98 .Xr md2 3 ,
99 .Xr md4 3 ,
100 .Xr md5 3 ,
101 .Xr sha 3
102 .Sh HISTORY
103 These functions appeared in
104 .Fx 4.0 .
105 .Sh AUTHORS
106 The core hash routines were implemented by Eric Young based on the
107 published
108 .Tn RIPEMD160
109 specification.
110 .Sh BUGS
111 No method is known to exist which finds two files having the same hash value,
112 nor to find a file with a specific hash value.
113 There is on the other hand no guarantee that such a method doesn't exist.