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