1.\" $NetBSD: tiger.3,v 1.4 2014/02/17 07:23:18 agc Exp $
2.\"
3.\" Copyright (c) 2011 Alistair Crooks <agc@NetBSD.org>
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25.\"
26.Dd May 30, 2011
27.Dt TIGER 3
28.Os
29.Sh NAME
30.Nm TIGER_Init ,
31.Nm TIGER_Update ,
32.Nm TIGER_Final ,
33.Nm TIGER_End ,
34.Nm TIGER_File ,
35.Nm TIGER_Data
36.Nd calculate TIGER message digests
37.Sh SYNOPSIS
38.In tiger.h
39.Ft void
40.Fo TIGER_Init
41.Fa "TIGER_CTX *context"
42.Fc
43.Ft void
44.Fo TIGER_Update
45.Fa "TIGER_CTX *context" "const uint8_t *data" "u_int len"
46.Fc
47.Ft void
48.Fo TIGER_Final
49.Fa "uint8_t digest[20]" "TIGER_CTX *context"
50.Fc
51.Ft "char *"
52.Fo TIGER_End
53.Fa "TIGER_CTX *context" "char *buf"
54.Fc
55.Ft "char *"
56.Fo TIGER_File
57.Fa "char *filename" "char *buf"
58.Fc
59.Ft "char *"
60.Fo TIGER_Data
61.Fa "uint8_t *data" "size_t len" "char *buf"
62.Fc
63.Sh DESCRIPTION
64The TIGER functions calculate TIGER message digest functions,
65as defined by Ross Anderson and Eli Biham.
66The algorithm takes a
67message less than 2^64 bits as input and produces a 192-bit digest
68suitable for use as a digital signature.
69.Pp
70At the time of writing,
71May 2011,
72no attacks or pre-imaging have been discovered against the
73.Nm
74message digests, whilst the same cannot be said of
75.Xr md5 3
76or
77.Xr sha1 3 .
78.Pp
79The
80.Fn TIGER_Init
81function initializes a TIGER_CTX
82.Ar context
83for use with
84.Fn TIGER_Update ,
85and
86.Fn TIGER_Final .
87The
88.Fn TIGER_Update
89function adds
90.Ar data
91of length
92.Ar len
93to the TIGER_CTX specified by
94.Ar context .
95.Fn TIGER_Final
96is called when all data has been added via
97.Fn TIGER_Update
98and stores a message digest in the
99.Ar digest
100parameter.
101When a
102.Dv NULL
103pointer is passed to
104.Fn TIGER_Final
105as first argument only the final padding will be applied and the
106current context can still be used with
107.Fn TIGER_Update .
108.Pp
109The core of the TIGER message digest is performed by
110.Fn TIGER_Update .
111Most programs should use the interface provided by
112.Fn TIGER_Init ,
113.Fn TIGER_Update ,
114and
115.Fn TIGER_Final .
116.Pp
117The
118.Fn TIGER_End
119function is a frontend for
120.Fn TIGER_Final
121which converts the digest into an
122.Tn ASCII
123representation of the 160 bit digest in hexadecimal.
124.Pp
125The
126.Fn TIGER_File
127function calculates the digest for a file and returns the result via
128.Fn TIGER_End .
129If
130.Fn TIGER_File
131is unable to open the file a
132.Dv NULL
133pointer is returned.
134.Pp
135The
136.Fn TIGER_Data
137function
138calculates the digest of an arbitrary string and returns the result via
139.Fn TIGER_End .
140.Pp
141For each of the
142.Fn TIGER_End ,
143.Fn TIGER_File ,
144and
145.Fn TIGER_Data
146functions the
147.Ar buf
148parameter should either be a string of at least 41 characters in
149size or a
150.Dv NULL
151pointer.
152In the latter case, space will be dynamically allocated via
153.Xr malloc 3
154and should be freed using
155.Xr free 3
156when it is no longer needed.
157.Sh EXAMPLES
158The follow code fragment will calculate the digest for the string
159.Dq The quick brown fox jumps over the lazy dog ,
160which is
161.Dq 6d12a41e72e644f017b6f0e2f7b44c6285f06dd5d2c5b075 .
162.Bd -literal -offset indent
163TIGER_CTX tiger;
164uint8_t results[24];
165char *buf;
166int n;
167
168buf = "The quick brown fox jumps over the lazy dog";
169n = strlen(buf);
170TIGER_Init(\*[Am]tiger);
171TIGER_Update(\*[Am]tiger, (uint8_t *)buf, n);
172TIGER_Final(results, \*[Am]tiger);
173
174/* Print the digest as one long hex value */
175printf("0x");
176for (n = 0; n \*[Lt] 24; n++)
177	printf("%02x", results[n]);
178putchar('\en');
179.Ed
180.Pp
181Alternately, the helper functions could be used in the following way:
182.Bd -literal -offset indent
183TIGER_CTX tiger;
184uint8_t output[49];
185char *buf = "The quick brown fox jumps over the lazy dog";
186
187printf("0x%s", TIGER_Data(buf, strlen(buf), output));
188.Ed
189.Sh SEE ALSO
190.Xr md5 3 ,
191.Xr sha1 3
192.Rs
193.%A Ross Anderson
194.%A Eli Biham
195.%T "Tiger \- A Fast New Hash Function"
196.%B Proceedings of Fast Software Encryption 3, Cambridge
197.%D 1996
198.Re
199.Sh HISTORY
200The TIGER functions appeared in
201.Nx 6.0 .
202.Sh AUTHORS
203.An -nosplit
204This implementation of TIGER was adapted by
205.An Alistair Crooks Aq Mt agc@NetBSD.org
206from the original reference code.
207.Pp
208The
209.Fn TIGER_End ,
210.Fn TIGER_File ,
211and
212.Fn TIGER_Data
213helper functions are derived from code written by Poul-Henning Kamp.
214.Sh BUGS
215All attempts have been made to optimise for the underlying hardware,
216as well as to format the digest properly in an endian-neutral manner.
217The author has no VAX hardware on which to test, and so it is not known
218whether that platform is supported.
219