1
2 hashlib++ - a simple hash library for C++
3 Copyright (c) 2007,2008 Benjamin Grüdelbach
4
5 About this document:
6 This document explains the basics of the hashlib++ library. You should read this
7 stuff if you are new to hashlib++.
8
9 MI 17 Feb 2008
10
11 -------------------------------------------------------------------------------
12
13 Table of contents:
14
15 0) About hashlib++
16 1) Current version / What's new?
17 2) Supported hash functions
18 3) Installing hashlib++
19 4) The structure of hashlib++
20 5) The library's files
21 6) Using hashlib++
22 7) Supported operation systems
23 8) License
24 9) Feedback, Questions, Contact
25 10) Third party agreements
26
27 -------------------------------------------------------------------------------
28
29 0) About hashlib++?
30
31 hashlib++ is a simple and very easy to use library to create a cryptographic
32 checksum called "hash". hashlib++ is written in plain C++ and should work with
33 every compiler and platform. hashlib++ is released under the BSD-license (see
34 section 8) and therefore free software.
35
36 -------------------------------------------------------------------------------
37
38 1) Current version / What's new?
39
40 The current stable version of hashlib++ is: 0.3.1
41
42 Improvements for hashlib++ version 0.3.1:
43
44 Version 0.3.1 is basicly a bugfix release.
45
46 * Added hl_types.h which defines basic typdefs to avoid
47 compile-errors on some systems.
48 * Added DEBUG flag to the Unix-Makefile
49 * Added hashlibpp.h which is just an include-wrapper.
50
51 -------------------------------------------------------------------------------
52
53 2) Supported hash functions
54
55 By now hashlib++ supports the following functions:
56
57 * MD5 Message-Digest algorithm 5
58 * SHA1 Secure Hash Algorithm 1
59 * SHA2-Family Secure Hash Algorithm 256, 384 and 512
60
61 -------------------------------------------------------------------------------
62 3) Installing hashlib++
63
64 Windows:
65
66 For Windows user it is recommend to download the binary setup program
67 "Setup.exe" which will install hashlib++ as a static library to your
68 system.
69
70 Run Setup.exe and read the license agreements. If you agree click on
71 "I Agree" and choose a destination folder for hashlib++ within the
72 following page. Finally, click on "Install" to start the installation.
73
74 Linux/FreeBSD:
75
76 Download the source tarball and untar it. Make sure that g++ is installed
77 and in you $PATH. Switch to the "src" directory and have a look at the
78 makefile. hashlib++ will be compiled and installed as a static library.
79 The headerfiles will be placed into /usr/local/include and the library
80 itself (libhl++.a) will be installed into /usr/local/lib by default.
81 You can change the default paths by editing "INCLUDE_PATH" and/or
82 "LIB_PATH" in line 44 and 47 of the makefile to meet your needs.
83
84 Now type 'make' to build hashlib++ as a static library and
85 'make install' to install hashlib++ into LIB_PATH and INCLUDE_PATH.
86 Type 'make clean' to clean up the *.o files.
87
88 Alternative use for Windows, Linux and FreeBSD:
89
90 By default hashlib++ will be installed as a static library and you can
91 link your application against it. If you don't want that you can
92 alternatively add all source and header files (or only those you need)
93 to your project and compile them with your application.
94
95 -------------------------------------------------------------------------------
96
97 4) The structure of hashlib++
98
99 hashlib++ provides so called "wrappers" for each supported hash function which
100 simplify the creation of the relevant hash. Instead of implementing the full
101 algorithm for the hash function you only have to instantiate a desired wrapper
102 and call a memberfunction like getHashFromString() or getHashFromFile().
103
104 The wrappers:
105
106 * md5wrapper for MD5 in hl_md5wrapper.h
107 * sha1wrapper for SHA1 in hl_sha1wrapper.h
108 * sha256wrapper for SHA256 in hl_sha256wrapper.h
109 * sha384wrapper for SHA384 in hl_sha384wrapper.h
110 * sha512wrapper for SHA512 in hl_sha512wrapper.h
111
112
113 -------------------------------------------------------------------------------
114
115 5) The library's files
116
117 The library consist of the the following files:
118
119 * hashlibpp.h
120 Basic include-file. Include this file to
121 access hashlib++.
122
123 * hl_hashwrapper.h
124 This is a baseclass of all wrappers.
125
126 * hl_exception.h
127 Class for error-handling.
128
129 * hl_md5.h and hl_md5.cpp
130 These two files implement the MD5 algorithm.
131
132 * hl_md5wrapper.h and hl_md5wrapper.cpp
133 These files represents the MD5 wrapper.
134
135 * hl_sha1.h and hl_sha1.cpp
136 These two files implement the SHA1 algorithm.
137
138 * hl_sha1wrapper.h and hl_sha1wrapper.cpp
139 These files represents the SHA1 wrapper.
140
141 * hl_sha256.h and hl_sha256.cpp
142 These two files implement the SHA256 algorithm.
143
144 * hl_sha256wrapper.h and hl_sha256wrapper.cpp
145 These files represents the SHA256 wrapper.
146
147 * hl_sha2ext.h and hl_sha2ext.cpp
148 This is the implementation of SHA384 and SHA512
149 algorithm.
150
151 * hl_2mac.h
152 Contains some macros used in the SHA384 and SHA512
153 implementation.
154
155 * hl_sha384wrapper.h and hl_sha384wrapper.cpp
156 The wrapper class for SHA384.
157
158 * hl_sha512wrapper.h and hl_sha512wrapper.cpp
159 The wrapper class for SHA512.
160
161 * libtest.cpp
162 This is a example program which shows how to
163 use hashlib++. The program expected a filename
164 or a string and creates the hashes of the given
165 file or characters.
166
167 -------------------------------------------------------------------------------
168
169 6) Using hashlib++
170
171 This section explains how to create a hash with the help of hashlib++. First of
172 all you have to include hashlibpp.h:
173
174 #include <hashlibpp.h>
175
176 After that you can create wrapper objects:
177
178 hashwrapper *md5 = new md5wrapper();
179 hashwrapper *sha1 = new sha1wrapper();
180
181 Once a wrapper has been instantiated, you can basically call the memberfunctions
182 getHashFromFile() and getHashFromString() to create a hash from a file or
183 string.
184
185 try
186 {
187 std::string mytexthash = md5->getHashFromString("Hello World");
188 std::string myfilehash = md5->getHashFromFile("README.TXT");
189 }
190 catch(hlException &e)
191 {
192 // your error handling here.
193 // use: e.error_number() and
194 // e.error_message()
195 }
196
197
198 And that's all!
199
200 delete md5;
201 delete sha1;
202
203 Now you can compile your project. Don't forget to link against hashlib++,
204 if you use it as a static library.
205 If you are on Linux/FreeBSD/etc. you probably want to build your application
206 using g++. For example:
207
208 g++ -I/usr/local/include -L/usr/local/lib libtest.cpp -lhl++
209
210 If you are using Windows and Visual C++ you can easily add the library to your
211 project by using "Project -> Add Existing Item".
212
213 For other compilers or IDEs please see the specific documentation of the vendor.
214
215 -------------------------------------------------------------------------------
216
217 7) Supported operation systems
218
219 hashlib++ was written in standard C++, so it is platform independent and
220 should work with every C++ compiler. It was tested on the following systems
221 which are official supported:
222
223 FreeBSD 6.2 with g++ 3.4.6 and 4.1.3
224 Microsoft Windows XP with Microsoft Visual C++ 2005 Express Edition
225 Gnu/Linux 2.6 with g++ 3.4.6
226
227 -------------------------------------------------------------------------------
228
229 8) License
230
231 hashlib++ - a simple hash library for C++
232
233 Copyright (c) 2007,2008 Benjamin Grüdelbach
234
235 Redistribution and use in source and binary forms, with or without modification,
236 are permitted provided that the following conditions are met:
237
238 1) Redistributions of source code must retain the above copyright
239 notice, this list of conditions and the following disclaimer.
240
241 2) Redistributions in binary form must reproduce the above copyright
242 notice, this list of conditions and the following disclaimer in
243 the documentation and/or other materials provided with the
244 distribution.
245
246 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
247 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
248 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
249 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
250 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
251 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
252 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
253 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
254 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
255 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
256
257 -------------------------------------------------------------------------------
258
259 9) Feedback, Questions, Contact
260
261 I would be pleased to hear some feedback from you.
262 For special question feel free to send me an e-mail.
263
264 Benjamin Grüdelbach
265 bennygr@users.sourceforge.net
266 http://hashlib2plus.sourceforge.net/
267
268 -------------------------------------------------------------------------------
269
270 10) Third party agreements
271
272 * MD5 implementation
273
274 The hashlib++ MD5 implementation is derivative from the sourcecode
275 published in RFC 1321 which contains the following copyright:
276
277 Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All rights
278 reserved.
279
280 License to copy and use this software is granted provided that it is
281 identified as the "RSA Data Security, Inc. MD5 Message-Digest
282 Algorithm" in all material mentioning or referencing this software or
283 this function.
284
285 License is also granted to make and use derivative works provided that
286 such works are identified as "derived from the RSA Data Security, Inc.
287 MD5 Message-Digest Algorithm" in all material mentioning or
288 referencing the derived work.
289
290 RSA Data Security, Inc. makes no representations concerning either the
291 merchantability of this software or the suitability of this software
292 for any particular purpose. It is provided "as is" without express or
293 implied warranty of any kind.
294
295 These notices must be retained in any copies of any part of this
296 documentation and/or software.
297
298 * SHA1 implementation
299
300 The hashlib++ SHA1 implementation is derivative from the sourcecode
301 published in RFC 3174 which contains the following copyright:
302
303 Copyright (C) The Internet Society (2001). All Rights Reserved.
304
305 This document and translations of it may be copied and furnished to
306 others, and derivative works that comment on or otherwise explain it
307 or assist in its implementation may be prepared, copied, published and
308 distributed, in whole or in part, without restriction of any kind,
309 provided that the above copyright notice and this paragraph are
310 included on all such copies and derivative works. However, this
311 document itself may not be modified in any way, such as by removing
312 the copyright notice or references to the Internet Society or other
313 Internet organizations, except as needed for the purpose of developing
314 Internet standards in which case the procedures for copyrights defined
315 in the Internet Standards process must be followed, or as required to
316 translate it into languages other than English.
317
318 The limited permissions granted above are perpetual and will not be
319 revoked by the Internet Society or its successors or assigns.
320
321 This document and the information contained herein is provided on an
322 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
323 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
324 NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN
325 WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
326 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
327
328 * SHA256 implementation
329
330 The hashlib++ SHA256,SHA384 and SHA512 implementation is derivative
331 from the sourcecode published by Aaron D. Gifford
332
333 Copyright (c) 2000-2001, Aaron D. Gifford All rights reserved.
334
335 Redistribution and use in source and binary forms, with or without
336 modification, are permitted provided that the following conditions are
337 met:
338 1. Redistributions of source code must retain the above copyright
339 notice, this list of conditions and the following disclaimer.
340 2. Redistributions in binary form must reproduce the above copyright
341 notice, this list of conditions and the following disclaimer in the
342 documentation and/or other materials provided with the distribution.
343 3. Neither the name of the copyright holder nor the names of
344 contributors may be used to endorse or promote products derived from
345 this software without specific prior written permission.
346
347 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTOR(S) ``AS IS''
348 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
349 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
350 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTOR(S)
351 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
352 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
353 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
354 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
355 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
356 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
357 THE POSSIBILITY OF SUCH DAMAGE.
358
359 -------------------------------------------------------------------------------
360 EOF