README.md (7614B)
1 # Hardware-Accelerated Hash Library 2 3 Fast implementations of SHA-256, SHA-512, SHA-1, MD5, and CRC32 with CPU hardware acceleration. 4 5 ## Features 6 7 - **SHA-256**: Hardware accelerated with Intel SHA extensions (10x+ faster) 8 - **SHA-512**: Optimized for 64-bit processors 9 - **SHA-1**: Legacy support (cryptographically broken) 10 - **MD5**: Legacy support (cryptographically broken) 11 - **CRC32**: Hardware accelerated with SSE 4.2 CRC32 instruction 12 - **Unified API**: Simple interface for all algorithms 13 - **Test Vectors**: Includes standard test vectors for verification 14 15 ## Hardware Acceleration 16 17 ### SHA-256 (Intel SHA Extensions) 18 - Available on: Intel Goldmont+ (2017+), AMD Zen (2017+) 19 - Speedup: ~10-20x over software implementation 20 - Automatic fallback to software on older CPUs 21 22 ### CRC32 (SSE 4.2) 23 - Available on: Intel Nehalem (2008+), AMD Bulldozer (2011+) 24 - Speedup: ~4-8x over table-based software 25 - Processes 8 bytes per instruction on 64-bit 26 27 ## Building 28 29 ```bash 30 # Build everything 31 make 32 33 # Build individual tests 34 make sha256_test 35 make sha512_test 36 make sha1_test 37 make md5_test 38 make crc32_test 39 make hash_demo 40 41 # Run all tests 42 make run 43 44 # Run specific test 45 make run-sha256 46 make run-unified 47 48 # Clean 49 make clean 50 ``` 51 52 ## Usage 53 54 ### Unified API (Recommended) 55 56 ```c 57 #include "hash.h" 58 59 // Hash a string 60 HashResult result = hash_compute(HASH_SHA256, (uint8_t*)"hello", 5); 61 hash_print("Result", &result); 62 hash_free(&result); 63 64 // Using convenience macros 65 HashResult h = HASH(HASH_SHA512, "password"); 66 char *hex = hash_to_hex(&h); 67 printf("Hash: %s\n", hex); 68 free(hex); 69 hash_free(&h); 70 71 // Compare hashes 72 HashResult h1 = hash_sha256_str("data1"); 73 HashResult h2 = hash_sha256_str("data2"); 74 if (hash_equals(&h1, &h2)) { 75 printf("Hashes match!\n"); 76 } 77 hash_free(&h1); 78 hash_free(&h2); 79 ``` 80 81 ### Direct API 82 83 ```c 84 #include <stdint.h> 85 86 // SHA-256 87 uint8_t sha256_digest[32]; 88 sha256((uint8_t*)"hello", 5, sha256_digest); 89 90 // SHA-512 91 uint8_t sha512_digest[64]; 92 sha512((uint8_t*)"hello", 5, sha512_digest); 93 94 // SHA-1 95 uint8_t sha1_digest[20]; 96 sha1((uint8_t*)"hello", 5, sha1_digest); 97 98 // MD5 99 uint8_t md5_digest[16]; 100 md5((uint8_t*)"hello", 5, md5_digest); 101 102 // CRC32 103 uint32_t crc = crc32((uint8_t*)"hello", 5); 104 ``` 105 106 ### Incremental Hashing 107 108 ```c 109 #include "hash.h" 110 111 // SHA-256 example 112 sha256_context ctx; 113 sha256_init(&ctx); 114 sha256_update(&ctx, (uint8_t*)"hello", 5); 115 sha256_update(&ctx, (uint8_t*)"world", 5); 116 uint8_t digest[32]; 117 sha256_final(&ctx, digest); 118 119 // CRC32 incremental 120 uint32_t crc = crc32((uint8_t*)"hello", 5); 121 crc = crc32_continue((uint8_t*)"world", 5, crc); 122 ``` 123 124 ## Algorithm Selection Guide 125 126 ### Cryptographic Security 127 128 | Algorithm | Security Status | Recommended Use | 129 |-----------|----------------|-----------------| 130 | **SHA-256** | ✅ Secure | General cryptographic use, digital signatures | 131 | **SHA-512** | ✅ Secure | Maximum security, 64-bit systems | 132 | **SHA-1** | ⚠️ Broken | Legacy compatibility only | 133 | **MD5** | ⚠️ Broken | Checksums, non-security applications | 134 | **CRC32** | ❌ Not secure | Error detection, checksums | 135 136 ### Use Cases 137 138 **SHA-256** 139 - Password hashing (with proper KDF) 140 - Digital signatures 141 - File integrity verification 142 - Blockchain applications 143 - General cryptographic purposes 144 145 **SHA-512** 146 - High-security applications 147 - Long-term data integrity 148 - Systems with 64-bit processors 149 - When maximum security margin needed 150 151 **SHA-1** 152 - Git commit hashes (legacy) 153 - Legacy protocol support 154 - Non-security checksums 155 156 **MD5** 157 - File checksums (non-security) 158 - Hash tables 159 - Data deduplication 160 - Legacy system compatibility 161 162 **CRC32** 163 - Network packet validation 164 - File format integrity (ZIP, PNG) 165 - Error detection in storage/transmission 166 - Fast checksums 167 168 ## Performance 169 170 Approximate throughput on modern CPU (Intel i7, 3.0 GHz): 171 172 | Algorithm | Software | Hardware | Speedup | 173 |-----------|----------|----------|---------| 174 | SHA-256 | ~200 MB/s | ~2 GB/s | 10x | 175 | SHA-512 | ~300 MB/s | ~300 MB/s | - | 176 | SHA-1 | ~400 MB/s | ~400 MB/s | - | 177 | MD5 | ~500 MB/s | ~500 MB/s | - | 178 | CRC32 | ~500 MB/s | ~4 GB/s | 8x | 179 180 ## Output Formats 181 182 ### Digest Sizes 183 184 - SHA-256: 32 bytes (256 bits) 185 - SHA-512: 64 bytes (512 bits) 186 - SHA-1: 20 bytes (160 bits) 187 - MD5: 16 bytes (128 bits) 188 - CRC32: 4 bytes (32 bits) 189 190 ### Hex Format Examples 191 192 ``` 193 SHA-256: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad 194 SHA-512: ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a 195 2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f 196 SHA-1: a9993e364706816aba3e25717850c26c9cd0d89d 197 MD5: 900150983cd24fb0d6963f7d28e17f72 198 CRC32: 0xcbf43926 199 ``` 200 201 ## Security Considerations 202 203 ### DO NOT Use for Password Storage Directly 204 205 These hash functions are **too fast** for password storage. Use proper password hashing: 206 - **Recommended**: Argon2, bcrypt, scrypt 207 - **Not recommended**: Plain SHA-256/512/MD5/SHA-1 208 209 ### Collision Attacks 210 211 - **MD5**: Practical collision attacks exist (broken since 2004) 212 - **SHA-1**: Practical collision attacks exist (broken since 2017) 213 - **SHA-256**: No known practical attacks 214 - **SHA-512**: No known practical attacks 215 - **CRC32**: Not designed for security, easy to create collisions 216 217 ### Side-Channel Resistance 218 219 Hardware-accelerated implementations (SHA-256, CRC32) provide better side-channel resistance than software implementations due to constant-time execution. 220 221 ## Test Vectors 222 223 The implementations are verified against standard test vectors: 224 225 ### SHA-256 ("abc") 226 ``` 227 ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad 228 ``` 229 230 ### SHA-512 ("abc") 231 ``` 232 ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a 233 2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f 234 ``` 235 236 ### SHA-1 ("abc") 237 ``` 238 a9993e364706816aba3e25717850c26c9cd0d89d 239 ``` 240 241 ### MD5 ("abc") 242 ``` 243 900150983cd24fb0d6963f7d28e17f72 244 ``` 245 246 ### CRC32 ("123456789") 247 ``` 248 0xcbf43926 249 ``` 250 251 ## Files 252 253 - `SHA256.c` - SHA-256 with hardware acceleration 254 - `SHA512.c` - SHA-512 implementation 255 - `SHA1.c` - SHA-1 implementation 256 - `MD5.c` - MD5 implementation 257 - `CRC32.c` - CRC32 with hardware acceleration 258 - `hash.h` - Unified API header 259 - `hash.c` - Unified API implementation 260 - `example_hash.c` - Comprehensive demo 261 - `Makefile` - Build system 262 - `README.md` - This file 263 264 ## Requirements 265 266 - **CPU**: x86-64 processor 267 - Optional: SHA extensions for SHA-256 acceleration 268 - Optional: SSE 4.2 for CRC32 acceleration 269 - **Compiler**: GCC or compatible 270 - **OS**: Linux (tested), should work on other Unix-like systems 271 272 ## Compilation Flags 273 274 - `-msha`: Enable SHA extensions (fallback if not available) 275 - `-msse4.2`: Enable SSE 4.2 for CRC32 276 - `-march=native`: Optimize for current CPU 277 - `-O3`: Maximum optimization 278 279 ## Example Output 280 281 ``` 282 Input: "The quick brown fox jumps over the lazy dog" 283 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 284 SHA-256: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592 285 SHA-512: 07e547d9586f6a73f73fbac0435ed76951218fb7d0c8d788a309d785436bbb64 286 2e93a252a954f23912547d1e8a3b5ed6e1bfd7097821233fa0538f3db854fee6 287 SHA-1: 2fd4e1c67a2d28fced849ee1bb76e7391b93eb12 288 MD5: 9e107d9d372bb6826bd81d3542a419d6 289 CRC32: 0x414fa339 290 ``` 291 292 ## License 293 294 Public domain / MIT-0. Use freely for any purpose. 295 296 ## References 297 298 - FIPS 180-4: Secure Hash Standard (SHA-2) 299 - FIPS 180-1: Secure Hash Standard (SHA-1) [Deprecated] 300 - RFC 1321: The MD5 Message-Digest Algorithm [Historic] 301 - ISO 3309: CRC-32 302 - Intel® SHA Extensions: [Intel Documentation](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sha-extensions.html)