"Fossies" - the Fresh Open Source Software Archive 
Member "duff-0.5.2/README.SHA" (10 Apr 2011, 8547 Bytes) of package /linux/privat/old/duff-0.5.2.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 shaX-asaddi (X = 1, 256, 384, 512)
2 ==================================
3 Copyright (c) 2001-2003 Allan Saddi <allan@saddi.com>
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 ALLAN SADDI AND HIS CONTRIBUTORS ``AS IS''
16 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 ARE DISCLAIMED. IN NO EVENT SHALL ALLAN SADDI OR HIS CONTRIBUTORS BE
19 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25 POSSIBILITY OF SUCH DAMAGE.
26
27 Introduction
28 ------------
29 These are portable implementations of the National Institute of
30 Standards and Technology's Secure Hash Algorithms. Implementations
31 for SHA-1, SHA-256, SHA-384, and SHA-512 are available. All are
32 equally portable, assuming your compiler supports 64-bit integers
33 (which gcc does).
34
35 For more information on SHA (the algorithms), visit:
36 http://csrc.nist.gov/encryption/tkhash.html
37
38 The following documentation and examples will refer to the SHA-1
39 implementation. However, they equally apply to the SHA-256, SHA-384,
40 and SHA-512 implementations except where noted.
41
42 API
43 ---
44 SHA1Context
45 This is the hash context. There should be one SHA1Context for each
46 object to be hashed. (This only applies if hashing is being done
47 in parallel. Otherwise, it's perfectly safe to reuse a SHA1Context
48 to hash objects serially, e.g. one file at a time.)
49
50 A SHA1Context can be declared static, automatic, or allocated from
51 the heap. There are certain alignment restrictions, but it shouldn't
52 be of any concern in normal usage (malloc() should return suitably
53 aligned memory, and the compiler will take care of the other cases).
54
55 There's nothing really special about a SHA1Context. It should be
56 safe to copy it, e.g. using memcpy() or bcopy().
57
58 void SHA1Init (SHA1Context *sc);
59 Initializes a SHA1Context. This should be called before any of the
60 following functions are called.
61
62 void SHA1Update (SHA1Context *sc, const void *data, uint32_t len);
63 Hashes some data. len is in bytes.
64
65 void SHA1Final (SHA1Context *sc, uint8_t hash[SHA1_HASH_SIZE]);
66 Gets the SHA-1 hash and "closes" the context. The context should
67 no longer be used. (Due to padding, etc.) If you wish to hash a
68 new set of data using the same SHA1Context, be sure to call
69 SHA1Init(). If you want to continue hashing data using the
70 same context, simply make a copy of the context and call
71 SHA1Final() on the copy.
72
73 hash may be NULL, in which case no hash is generated (but the
74 context is still closed). Regardless if hash is NULL or not, a
75 word representation of the hash (32-bit words for SHA-1 and SHA-256,
76 64-bit words for SHA-384 and SHA-512) is available in
77 sc->hash[0..SHA1_HASH_WORDS-1]. This may be useful in other
78 applications.
79
80 If being used for cryptography, it's probably a good idea to zero-out
81 the SHA1Context after you're done.
82
83 Compile-Time Options
84 --------------------
85 HAVE_CONFIG_H
86 Define this if you want the code to include <config.h>. This is useful
87 if you use GNU configure.
88
89 HAVE_INTTYPES_H
90 HAVE_STDINT_H
91 Define one of these to 1 if you have the respective header file. If you
92 have neither, be sure to typedef/define uint8_t, uint32_t, and uint64_t
93 appropriately (perhaps in config.h above).
94
95 WORDS_BIGENDIAN
96 Define this if you're on a big-endian processor.
97
98 RUNTIME_ENDIAN
99 Define this if you would rather determine processor endianess at
100 runtime. WORDS_BIGENDIAN will be ignored if this is defined. The
101 generated code may be slightly slower, but at least you won't
102 have to worry about big-endian vs. little-endian!
103
104 SHA1_FAST_COPY
105 Defining this will eliminate some copying overhead of hashed data.
106 Also, calculating the hash in SHA1Final() should be slightly faster.
107 This isn't on by default because of alignment issues. See Portability
108 Notes.
109
110 SHA1_UNROLL
111 If undefined, it will default to 1. This is the number of rounds
112 to perform in a loop iteration. The larger the number, the bigger
113 the code, but also the less loop overhead there will be. It must
114 be between 1 and 20 inclusive, and it must be a factor of 20 or
115 a product of some of its factors. (Don't worry, you'll get a nice
116 error message if you defined it wrong.)
117
118 SHA-256 is the only other implementation that has something
119 similar (SHA256_UNROLL). It must be a power of 2 between 1 and
120 64 inclusive and it defaults to 1.
121
122 You may want to experiment with different values. I've generally
123 found that big code is slower, despite being more efficient. This
124 is most likely due to cache space limitations.
125
126 SHA1_TEST
127 Define this to compile a simple test program. See the comments in
128 sha1.c for what the output should look like. If the output doesn't
129 look right, try flipping WORDS_BIGENDIAN (define it if you didn't
130 define it, undefine it if you did). For example:
131
132 > gcc -Wall -O2 -DSHA1_TEST -o test sha1.c
133
134 Portability Notes
135 -----------------
136 As was mentioned, you need a compiler that supports 64-bit integers.
137 You will also need <inttypes.h> for uint8_t, uint32_t, uint64_t. I'm not
138 sure how common or standard this include file is, but it was available
139 on all platforms I tested.
140
141 It was actually surprising to find that all but one of the processors
142 tested supported unaligned word accesses. (I came from a MC680x0 +
143 MIPS background.) I developed the code on i386 and powerpc architectures,
144 which both supported unaligned words. It wasn't until I tried out my
145 code on a sparc that I realized I needed to be a little more careful.
146 (Bus errors... yum!)
147
148 With SHA1_FAST_COPY undefined, the code should be very portable. If you
149 define it, the code may be slightly faster, but there are a few things
150 you need to be careful about, especially on architectures that don't
151 support unaligned word accesses. Here are some general guidelines:
152
153 Use SHA1_FAST_COPY if:
154
155 * You call SHA1Update() with a consistent buffer size every time.
156 (The last time you call it before calling SHA1Final() can be the
157 exception.) And:
158
159 * The buffer size is a multiple of 64-bytes (SHA-1, SHA-256) or
160 128-bytes (SHA-384, SHA-512). And:
161
162 * The buffer address is evenly divisible by 4 (SHA-1, SHA-256) or
163 evenly divisible by 8 (SHA-384, SHA-512). And finally:
164
165 * The hash address passed to SHA1Final() is evenly divisible by
166 4 (SHA-1, SHA-256) or evenly divisible by 8 (SHA-384, SHA-512).
167
168 You can ensure proper address alignment by using malloc() (read your
169 man page to verify this) or by doing something like:
170
171 union {
172 uint32_t w; /* use uint64_t for SHA-384, SHA-512 */
173 uint8_t b[SHA1_HASH_SIZE];
174 } hash;
175 ...
176 SHA1Final (&sha, hash.b);
177
178 If you're on an architecture that supports unaligned word accesses,
179 it may be safe to define SHA1_FAST_COPY anyway. However, it would be
180 a good idea to experiment, since unaligned word accesses may actually
181 take longer and cancel the benefits of faster code.
182
183 Example
184 -------
185 #include <inttypes.h> /* for uint8_t, etc. */
186 #include <string.h> /* for memset() */
187
188 #include "sha1.h"
189
190 ...
191 SHA1Context sha;
192 uint8_t hash[SHA1_HASH_SIZE];
193 ...
194 SHA1Init (&sha);
195 ...
196 SHA1Update (&sha, buffer, length);
197 ...
198 SHA1Update (&sha, buffer2, length2);
199 ...
200 call SHA1Update() with more data
201 ...
202 SHA1Final (&sha, hash);
203 memset (&sha, 0, sizeof (sha)); /* for the truly paranoid */
204 ...
205 do something with hash
206 ...
207
208 Platforms Tested
209 ----------------
210 gcc was the compiler used on all tested platforms.
211
212 FreeBSD i386
213 Darwin powerpc
214 Linux i386
215 Linux alpha
216 Linux powerpc
217 Solaris sparc
218
219 Comments? Suggestions? Bugs?
220 ----------------------------
221 Please let me know!
222
223 - Allan Saddi <allan@saddi.com>