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