Debian Codegraph @

ext/digest/README-sha2

raw
1 sha2.c and sha2.h, and the test vectors under the data directory,
2 are from Aaron Gifford's Secure Hash Algorithm implementation
3 <http://www.aarongifford.com/computers/sha.html>
4 released under BSD license. We use the version 1.1.
5 The following is the content of the original README.
6
7 ===============================================================
8
9 VERSION:
10
11 STABLE/TESTED: 1.0 RELEASE
12
13 The 1.0 RELEASE (the previous version) appears to be quite stable
14 and has been used in quite a few places.
15
16 UNSTABLE/UNTESTED: 1.1 ALPHA
17
18 The new ALPHA version adds SHA-1 and SHA-224 functionality. It
19 also uses two perl scripts for performing tests against various
20 data sets.
21
22 The new version non longer uses a separate SHA*_CTX structure
23 for each hash type, and instead uses a single SHA_CTX structure
24 for all five hash types.
25
26 This release is ALPHA because I have not yet done testing on any
27 other platforms. I will be testing it on MAX OS X (big endian)
28 soon. I welcome other platform tests to work out portability bugs
29 that may have been introduced. I also welcome reports of issues
30 with the new test vector perl script changes.
31
32 The SHA-224 implementation appears to agree with those of other
33 folks who have posted test data on the web (as of 05 JAN 2004), the
34 very few test vectors I was able to find.
35
36 The SHA-1 implementation appears to agree with the implementation
37 in OpenSSL.
38
39
40 LICENSE:
41
42 This implementation is released under an OPEN SOURCE BSD license.
43
44
45 WHAT IT IS:
46
47 The files sha2.h and sha2.c implement the SHA-1, SHA-224, SHA-256,
48 SHA-384, and SHA-512 hash algorithms as described in the documents
49 found at the following web addresses:
50
51 http://csrc.nist.gov/cryptval/shs/sha256-384-512.pdf
52 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
53 http://csrc.nist.gov/publications/fips/fips180-2/FIPS180-2_changenotice.pdf
54
55 The interface is similar to the interface to SHA-1 found in the OpenSSL
56 library.
57
58 The file sha2prog.c is a simple program that accepts input from either
59 STDIN or reads one or more files specified on the command line, and then
60 generates the specified hash, any one, combination, or all of SHA-1,
61 SHA-224, SHA-256, SHA-384, SHA-512.
62
63
64 LIMITATIONS:
65
66 This implementation has several limitations:
67
68 * BYTE-BASED - Input data is only accepted in octet-length increments.
69 This implemendation does not handle input data lengths that do not
70 fall on byte boundaries.
71
72 * 64-BIT INTEGERS - This implementation uses 64-bit integer data types.
73 If your or compiler does not support 64-bit unsigned integer types,
74 this won't work for you.
75
76 * NOT THE FASTEST - These hashes were implemented for fun and for
77 portability, and so implementations may not be optimized for your
78 architecture. It was written entirely in C. No assembly was used.
79
80 * NO MAKEFILE/CONFIGURATION SCRIPT - There isn't a Makefile or any sort
81 of configuration script. You have to compile things by hand and
82 choose your compiler options yourself.
83
84 BEFORE YOU COMPILE (OPTIONS):
85
86 Each of the options described below may either be defined in the sha2.h
87 header file (or in the sha2.c file in some cases), or on the command
88 line at compile time if your compiler supports such things. For
89 example:
90
91 #define SHA2_USE_INTTYPES_H
92 #define SHA2_UNROLL_TRANSFORM
93
94 Or:
95
96 cc -c -DSHA2_UNROLL_TRANSFORM sha2.c
97 cc -c -DBYTE_ORDER=4321 -DBIG_ENDIAN=4321 sha2.c
98
99 Here are the available options. Read on below for a description of
100 each one:
101
102 SHA2_USE_INTTYPES_H
103 SHA2_USE_MEMSET_MEMCPY/SHA2_USE_BZERO_BCOPY
104 SHA2_UNROLL_TRANSFORM
105 BYTE_ORDER (LITTLE_ENDIAN/BIG_ENDIAN)
106
107 * SHA2_USE_INTTYPES_H option:
108 By default, this code uses u_intXX_t data types for 8 bit, 32 bit, and
109 64 bit unsigned integer type definitions. Most BSD systems define these,
110 as does Linux. However, some (like Compaq's Tru64 Unix) may instead
111 use uintXX_t data types as defined by recent ANSI C standards and as
112 included in the inttypes.h header file. Those wanting to use inttypes.h
113 need to define this either in sha.h or at compile time.
114
115 On those systems where NEITHER definitions are available, you will need
116 to edit both sha2.h and sha2.c and define things by hand in the appropriate
117 sections.
118
119 * BYTE_ORDER definitions:
120 This code assumes that BYTE_ORDER will be defined by the system during
121 compile to either equal LITTLE_ENDIAN or BIG_ENDIAN. If your system
122 does not define these, you may need to define them by hand in the sha.c
123 file according to the byte ordering conventions of your system.
124
125 * SHA2_USE_MEMSET_MEMCPY or SHA2_USE_BZERO_BCOPY
126 The code in sha2.c can use either memset()/memcpy() for memory block
127 operations, or bzero()/mcopy(). If you define neither of these, the
128 code will default to memset()/memcpy(). You can define either at the
129 command line or in sha2.h or in sha2.c.
130
131 * SHA2_UNROLL_TRANSFORM
132 By defining this either on the command line or in sha2.h or sha2.c,
133 the code will use macros to partially "unroll" the SHA transform
134 function. This usually generates bigger executables. It CAN (but
135 not necessarily WILL) generate faster code when you tell your compiler
136 to optimize things. For example, on the FreeBSD and Linux x86 systems
137 I tested things on (using gcc), when I optimized with just -O2 and
138 unrolled the transform, the hash transform was faster by 15-30%. On
139 these same systems, if I did NO optimization, the unrolled transform
140 was SLOWER, much slower (I'm guessing because the code was breaking
141 the cache, but I'm not sure). Your mileage may vary.
142
143
144 PORTABILITY:
145
146 The code in sha2.c and sha2.h is intended to be portable. It may
147 require that you do a few #definitions in the .h file. I've successfully
148 compiled and tested the sha2.c and sha2.h code on Apple's OS X (on
149 a PPC), FreeBSD 4.1.1 on Intel, Linux on Intel, FreeBSD on the Alpha,
150 and even under Windows98SE using Metrowerks C. The utility/example
151 programs (sha2prog.c, sha2test.c, and sha2speed.c) will very likely
152 have more trouble in portability since they do I/O.
153
154 To get sha2.c/sha2.h working under Windows, I had to define
155 SHA2_USE_INTTYPES_H, BYTE_ORDER, LITTLE_ENDIAN, and had to comment
156 out the include of <sys/types.h> in sha2.h. With a bit more work
157 I got the test program to run and verified that all the test
158 cases passed.
159
160
161 SUGGESTIONS/BUG FIXES:
162
163 If you make changes to get it working on other architectures, if you fix
164 any bugs, or if you make changes that improve this implementation's
165 efficiency that would be relatively portable and you're willing to release
166 your changes under the same license, please send them to me for possible
167 inclusion in future versions.
168
169 If you know where I can find some additional test vectors, please let me
170 know.
171
172
173 CHANGE HISTORY:
174
175 0.8 to 0.9 - Fixed spelling errors, changed to u_intXX_t type usage,
176 removed names from prototypes, added prototypes to sha2.c,
177 and a few things I can't recall.
178
179 0.9 to 0.9.5 - Add a new define in sha2.c that permits one to compile
180 it to either use memcpy()/memset() or bcopy()/bzero()
181 for memory block copying and zeroing. Added support
182 for unrolled SHA-256/384/512 transform loops. Just
183 compile with SHA2_UNROLL_TRANSFORM to enable. It takes
184 longer to compile, but I hope it is a bit faster. I
185 need to do some test to see whether or not it is. Oh,
186 in sha2.c, you either need to define SHA2_USE_BZERO_BCOPY
187 or SHA2_USE_MEMSET_MEMCPY to choose which way you want
188 to compile. *Whew* It's amazing how quickly something
189 simple starts to grow more complex even in the span of
190 just a few hours. I didn't really intend to do this much.
191 0.9.5 to 0.9.6 - Added a test program (sha2test) which tests against several
192 known test vectors. WARNING: Some of the test output
193 hashes are NOT from NIST's documentation and are the
194 output of this implementation and so may be incorrect.
195 0.9.6 to 0.9.7 - Fixed a bug that could cause invalid output in certain
196 cases and added an assumed scenario where zero-length
197 data is hashed. Also changed the rotation macros to use
198 a temporary variable as this reduces the number of operations.
199 When data is fed in blocks of the right length, copying of
200 data is reduced in this version. Added SHAYXZ_Data()
201 functions for ease of hashing a set of data. Added another
202 file sha2speed.c for doing speed testing. Added another test
203 vector with a larger data size (16KB). Fixed u_intXX_t and
204 uintXX_t handling by adding a define for SHA2_USE_INTTYPES_H
205 as well as made a few other minor changes to get rid of
206 warnings when compiling on Compaq's Tru64 Unix.
207 0.9.7 to 0.9.8 - The bug fix in 0.9.7 was incomplete and in some cases made
208 things worse. I believe that 0.9.8 fixes the bug completely
209 so that output is correct. I cannot verify this, however,
210 because of the lack of test vectors against which to do such
211 verification. All versions correctly matched the very few
212 NIST-provided vectors, but unfortunately the bug only
213 appeared in longer message data sets.
214 0.9.8 to 0.9.9 - Fixed some really bad typos and mistakes on my part that
215 only affected big-endian systems. I didn't have direct
216 access for testing before this version. Thanks to
217 Lucas Marshall for giving me access to his OS X system.
218 0.9.9 to 1.0.0b1 Added a few more test samples and made a few changes to
219 make things easier compiling on several other platforms.
220 Also I experimented with alternate macro definitions
221 in the SHA2_UNROLL_TRANSFORM version (see sha2.slower.c)
222 and eliminated the T1 temporary variable (the compiler
223 would of course still use internal temporary storage
224 during expression evaluation, but I'd hoped the compiler
225 would be more efficient), but unfortunately under FreeBSD
226 4.1.1-STABLE on an x86 platform, the change slowed things
227 down.
228 1.0.0b1 to 1.0 RELEASE Fixed an off-by-one implementation bug that affected
229 SHA-256 when hashed data length L = 55 + 64 * X where X is
230 either zero or a positive integer, and another (basically
231 the same bug) bug in SHA-384 and SHA-512 that showed up when
232 hashed data lengths L = 111 + 128 * X. Thanks to Rogier
233 van de Pol for sending me test data that revealed the bug.
234 The fix was very simple (just two tiny changes). Also,
235 I finally put the files into RCS so future changes will be
236 easier to manage. The sha2prog.c file was rewritten to
237 be more useful to me, and I got rid of the old C testing
238 program and now use a perl script with a subdirectory full
239 of test data. It's a more flexible test system.
240
241 1.0 RELEASE to 1.1 ALPHA - Added SHA-224 functionality, consolidated a bit of
242 redundant code, consolidated the SHAxxx_CTX data structure
243 into a single SHA_CTX union, made the sha2test.pl perl
244 script much more flexible (to allow easy creation of new
245 and interesting test vectors), though it does now require
246 the mktestdata.pl script be in the same directory. SHA-1
247 was also added to make the package complete.
248
249
250 LATEST VERSION:
251
252 The latest version and documentation (if any ;) should always be available
253 on the web at:
254
255 http://www.aarongifford.com/computers/sha.html
256
257
258 CONTACT ME:
259
260 I can be reached via email at:
261
262 Aaron Gifford <m e @ a a r o n g i f f o r d . c o m>
263
264 Please don't send support questions. I don't have the time to answer and
265 they'll probably be ignored. Bug fixes, or patches that add something useful
266 will be gratefully accepted, however.
267
268 If you use this implementation, I would enjoy getting a brief email message
269 letting me know who you are and what use to which it is being put. There
270 is no requirement to do so. I just think it would be fun.
271
272
273 EXAMPLES:
274
275 Here's an example of compiling and using the sha2 program (in this example
276 I build it using the unrolled transform version with -O2 optimizations),
277 and then running the perl testing script:
278
279 cc -O2 -DSHA2_UNROLL_TRANSFORM -Wall -o sha2 sha2prog.c sha2.c
280 % ./sha2test.pl
281
282 [most of the perl script output deleted for brevity]
283
284 ===== RESULTS (20 VECTOR DATA FILES HASHED) =====
285
286 HASH TYPE NO. OF TESTS PASSED FAILED
287 --------- ------------ ------ ------
288 SHA-1 4 4 0
289 SHA-224 20 20 0
290 SHA-256 20 20 0
291 SHA-384 20 20 0
292 SHA-512 20 20 0
293 ----------------------------------------------
294 TOTAL: 84 84 0
295
296 NO ERRORS! ALL TESTS WERE SUCCESSFUL!
297
298 ALL TEST VECTORS PASSED!
299
300 That's all folks! Have fun!
301
302 Aaron out.
303
304 $Id: README,v 1.3 2004/01/07 22:59:48 adg Exp $