| 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 $ |