1shaX-asaddi (X = 1, 256, 384, 512) 2================================== 3Copyright (c) 2001-2003 Allan Saddi <allan@saddi.com> 4All rights reserved. 5 6Redistribution and use in source and binary forms, with or without 7modification, are permitted provided that the following conditions 8are met: 91. Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 112. 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 15THIS SOFTWARE IS PROVIDED BY ALLAN SADDI AND HIS CONTRIBUTORS ``AS IS'' 16AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18ARE DISCLAIMED. IN NO EVENT SHALL ALLAN SADDI OR HIS CONTRIBUTORS BE 19LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25POSSIBILITY OF SUCH DAMAGE. 26 27Introduction 28------------ 29These are portable implementations of the National Institute of 30Standards and Technology's Secure Hash Algorithms. Implementations 31for SHA-1, SHA-256, SHA-384, and SHA-512 are available. All are 32equally portable, assuming your compiler supports 64-bit integers 33(which gcc does). 34 35For more information on SHA (the algorithms), visit: 36http://csrc.nist.gov/encryption/tkhash.html 37 38The following documentation and examples will refer to the SHA-1 39implementation. However, they equally apply to the SHA-256, SHA-384, 40and SHA-512 implementations except where noted. 41 42API 43--- 44SHA1Context 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 58void SHA1Init (SHA1Context *sc); 59 Initializes a SHA1Context. This should be called before any of the 60 following functions are called. 61 62void SHA1Update (SHA1Context *sc, const void *data, uint32_t len); 63 Hashes some data. len is in bytes. 64 65void 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 83Compile-Time Options 84-------------------- 85HAVE_CONFIG_H 86 Define this if you want the code to include <config.h>. This is useful 87 if you use GNU configure. 88 89HAVE_INTTYPES_H 90HAVE_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 95WORDS_BIGENDIAN 96 Define this if you're on a big-endian processor. 97 98RUNTIME_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 104SHA1_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 110SHA1_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 126SHA1_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 134Portability Notes 135----------------- 136As was mentioned, you need a compiler that supports 64-bit integers. 137You will also need <inttypes.h> for uint8_t, uint32_t, uint64_t. I'm not 138sure how common or standard this include file is, but it was available 139on all platforms I tested. 140 141It was actually surprising to find that all but one of the processors 142tested supported unaligned word accesses. (I came from a MC680x0 + 143MIPS background.) I developed the code on i386 and powerpc architectures, 144which both supported unaligned words. It wasn't until I tried out my 145code on a sparc that I realized I needed to be a little more careful. 146(Bus errors... yum!) 147 148With SHA1_FAST_COPY undefined, the code should be very portable. If you 149define it, the code may be slightly faster, but there are a few things 150you need to be careful about, especially on architectures that don't 151support unaligned word accesses. Here are some general guidelines: 152 153Use 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 168You can ensure proper address alignment by using malloc() (read your 169man 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 178If you're on an architecture that supports unaligned word accesses, 179it may be safe to define SHA1_FAST_COPY anyway. However, it would be 180a good idea to experiment, since unaligned word accesses may actually 181take longer and cancel the benefits of faster code. 182 183Example 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 208Platforms Tested 209---------------- 210gcc was the compiler used on all tested platforms. 211 212FreeBSD i386 213Darwin powerpc 214Linux i386 215Linux alpha 216Linux powerpc 217Solaris sparc 218 219Comments? Suggestions? Bugs? 220---------------------------- 221Please let me know! 222 223- Allan Saddi <allan@saddi.com> 224