0
# Hash Functions
1

2
SJCL provides implementations of several cryptographic hash functions including SHA-1, SHA-256, SHA-512, and RIPEMD-160, with both one-shot hashing and streaming interfaces for large data processing.
3

4
## Capabilities
5

6
### SHA-256
7

8
The most commonly used hash function in SJCL, providing 256-bit hash outputs with good security and performance.
9

10
```javascript { .api }
11
/**
12
 * SHA-256 hash constructor for streaming operations
13
 * @param {Hash} [hash] - Optional existing hash state to copy
14
 */
15
new sjcl.hash.sha256(hash);
16

17
/**
18
 * Compute SHA-256 hash in one operation
19
 * @param {BitArray|string} data - Data to hash (bit array or string)
20
 * @returns {BitArray} 256-bit hash as bit array
21
 */
22
sjcl.hash.sha256.hash(data);
23

24
/**
25
 * Block size constant for SHA-256
26
 */
27
sjcl.hash.sha256.prototype.blockSize = 512;
28
```
29

30
**Instance Methods:**
31

32
```javascript { .api }
33
/**
34
 * Reset hash state to initial values
35
 * @returns {sjcl.hash.sha256} This hash instance for chaining
36
 */
37
sjcl.hash.sha256.prototype.reset();
38

39
/**
40
 * Add data to the hash
41
 * @param {BitArray|string} data - Data to add to hash
42
 * @returns {sjcl.hash.sha256} This hash instance for chaining
43
 */
44
sjcl.hash.sha256.prototype.update(data);
45

46
/**
47
 * Complete the hash and return result
48
 * @returns {BitArray} Final hash value as bit array
49
 */
50
sjcl.hash.sha256.prototype.finalize();
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
const sjcl = require('sjcl');
57

58
// One-shot hashing
59
const hash1 = sjcl.hash.sha256.hash("Hello, World!");
60
const hexHash1 = sjcl.codec.hex.fromBits(hash1);
61
console.log(hexHash1);
62

63
// Streaming hashing
64
const hasher = new sjcl.hash.sha256();
65
hasher.update("Hello, ");
66
hasher.update("World!");
67
const hash2 = hasher.finalize();
68
const hexHash2 = sjcl.codec.hex.fromBits(hash2);
69
console.log(hexHash2); // Same as hexHash1
70

71
// Hash binary data
72
const binaryData = sjcl.codec.utf8String.toBits("Hello, World!");
73
const hash3 = sjcl.hash.sha256.hash(binaryData);
74
```
75

76
### SHA-1
77

78
Legacy hash function, still supported but not recommended for new applications due to known vulnerabilities.
79

80
```javascript { .api }
81
/**
82
 * SHA-1 hash constructor for streaming operations
83
 * @param {Hash} [hash] - Optional existing hash state to copy
84
 */
85
new sjcl.hash.sha1(hash);
86

87
/**
88
 * Compute SHA-1 hash in one operation
89
 * @param {BitArray|string} data - Data to hash
90
 * @returns {BitArray} 160-bit hash as bit array
91
 */
92
sjcl.hash.sha1.hash(data);
93

94
/**
95
 * Block size constant for SHA-1
96
 */
97
sjcl.hash.sha1.prototype.blockSize = 512;
98
```
99

100
**Instance Methods:**
101

102
```javascript { .api }
103
/**
104
 * Reset hash state to initial values
105
 */
106
sjcl.hash.sha1.prototype.reset();
107

108
/**
109
 * Add data to the hash
110
 * @param {BitArray|string} data - Data to add to hash
111
 */
112
sjcl.hash.sha1.prototype.update(data);
113

114
/**
115
 * Complete the hash and return result
116
 * @returns {BitArray} Final hash value as bit array
117
 */
118
sjcl.hash.sha1.prototype.finalize();
119
```
120

121
### SHA-512
122

123
High-security hash function providing 512-bit hash outputs, suitable for applications requiring maximum security.
124

125
```javascript { .api }
126
/**
127
 * SHA-512 hash constructor for streaming operations
128
 * @param {Hash} [hash] - Optional existing hash state to copy
129
 */
130
new sjcl.hash.sha512(hash);
131

132
/**
133
 * Compute SHA-512 hash in one operation
134
 * @param {BitArray|string} data - Data to hash
135
 * @returns {BitArray} 512-bit hash as bit array
136
 */
137
sjcl.hash.sha512.hash(data);
138

139
/**
140
 * Block size constant for SHA-512
141
 */
142
sjcl.hash.sha512.prototype.blockSize = 1024;
143
```
144

145
**Instance Methods:**
146

147
```javascript { .api }
148
/**
149
 * Reset hash state to initial values
150
 */
151
sjcl.hash.sha512.prototype.reset();
152

153
/**
154
 * Add data to the hash
155
 * @param {BitArray|string} data - Data to add to hash
156
 */
157
sjcl.hash.sha512.prototype.update(data);
158

159
/**
160
 * Complete the hash and return result
161
 * @returns {BitArray} Final hash value as bit array
162
 */
163
sjcl.hash.sha512.prototype.finalize();
164
```
165

166
**Usage Examples:**
167

168
```javascript
169
const sjcl = require('sjcl');
170

171
// SHA-512 one-shot hashing
172
const hash512 = sjcl.hash.sha512.hash("Hello, World!");
173
const hex512 = sjcl.codec.hex.fromBits(hash512);
174
console.log(hex512); // 128 hex characters (512 bits)
175

176
// Large data streaming with SHA-512
177
const hasher512 = new sjcl.hash.sha512();
178
for (let i = 0; i < 1000; i++) {
179
  hasher512.update("chunk " + i + " ");
180
}
181
const finalHash = hasher512.finalize();
182
```
183

184
### RIPEMD-160
185

186
Alternative hash function providing 160-bit outputs, designed as an alternative to SHA-1.
187

188
```javascript { .api }
189
/**
190
 * RIPEMD-160 hash constructor for streaming operations
191
 * @param {Hash} [hash] - Optional existing hash state to copy
192
 */
193
new sjcl.hash.ripemd160(hash);
194

195
/**
196
 * Compute RIPEMD-160 hash in one operation
197
 * @param {BitArray|string} data - Data to hash
198
 * @returns {BitArray} 160-bit hash as bit array
199
 */
200
sjcl.hash.ripemd160.hash(data);
201
```
202

203
**Instance Methods:**
204

205
```javascript { .api }
206
/**
207
 * Reset hash state to initial values
208
 */
209
sjcl.hash.ripemd160.prototype.reset();
210

211
/**
212
 * Add data to the hash
213
 * @param {BitArray|string} data - Data to add to hash
214
 */
215
sjcl.hash.ripemd160.prototype.update(data);
216

217
/**
218
 * Complete the hash and return result
219
 * @returns {BitArray} Final hash value as bit array
220
 */
221
sjcl.hash.ripemd160.prototype.finalize();
222
```
223

224
**Usage Examples:**
225

226
```javascript
227
const sjcl = require('sjcl');
228

229
// RIPEMD-160 hashing
230
const ripemdHash = sjcl.hash.ripemd160.hash("Hello, World!");
231
const hexRipemd = sjcl.codec.hex.fromBits(ripemdHash);
232
console.log(hexRipemd); // 40 hex characters (160 bits)
233

234
// Streaming RIPEMD-160
235
const ripemdHasher = new sjcl.hash.ripemd160();
236
ripemdHasher.update("Hello, ");
237
ripemdHasher.update("World!");
238
const finalRipemd = ripemdHasher.finalize();
239
```
240

241
## Common Usage Patterns
242

243
### File Hashing
244

245
Example of hashing large amounts of data using the streaming interface:
246

247
```javascript
248
const sjcl = require('sjcl');
249

250
function hashLargeData(dataChunks) {
251
  const hasher = new sjcl.hash.sha256();
252
  
253
  dataChunks.forEach(chunk => {
254
    // Convert string chunks to bit arrays if needed
255
    const bits = typeof chunk === 'string' 
256
      ? sjcl.codec.utf8String.toBits(chunk)
257
      : chunk;
258
    hasher.update(bits);
259
  });
260
  
261
  return hasher.finalize();
262
}
263

264
// Usage
265
const chunks = ["chunk1", "chunk2", "chunk3"];
266
const hash = hashLargeData(chunks);
267
const hexHash = sjcl.codec.hex.fromBits(hash);
268
```
269

270
### Hash Comparison
271

272
Secure hash comparison using constant-time equality:
273

274
```javascript
275
const sjcl = require('sjcl');
276

277
function verifyHash(data, expectedHash) {
278
  const actualHash = sjcl.hash.sha256.hash(data);
279
  
280
  // Use bitArray.equal for constant-time comparison
281
  return sjcl.bitArray.equal(actualHash, expectedHash);
282
}
283

284
// Usage
285
const data = "Hello, World!";
286
const storedHash = sjcl.hash.sha256.hash(data);
287

288
// Later verification
289
const isValid = verifyHash(data, storedHash);
290
console.log("Hash valid:", isValid);
291
```
292

293
### Hash Chain
294

295
Creating hash chains for integrity verification:
296

297
```javascript
298
const sjcl = require('sjcl');
299

300
function createHashChain(data, rounds) {
301
  let hash = sjcl.codec.utf8String.toBits(data);
302
  
303
  for (let i = 0; i < rounds; i++) {
304
    hash = sjcl.hash.sha256.hash(hash);
305
  }
306
  
307
  return hash;
308
}
309

310
// Usage
311
const chainHash = createHashChain("initial data", 1000);
312
const hexChain = sjcl.codec.hex.fromBits(chainHash);
313
```
314

315
## Performance Considerations
316

317
- **SHA-256**: Best balance of security and performance for most applications
318
- **SHA-512**: Higher security but slower, especially on 32-bit platforms
319
- **SHA-1**: Fastest but deprecated due to security vulnerabilities
320
- **RIPEMD-160**: Good alternative to SHA-1 with similar performance
321
- **Streaming vs One-shot**: Use streaming interface for large data to avoid memory issues
322

323
## Security Recommendations
324

325
1. **Use SHA-256 or SHA-512** for new applications
326
2. **Avoid SHA-1** except for legacy compatibility
327
3. **Use streaming interface** for large files to prevent memory exhaustion
328
4. **Use constant-time comparison** (`sjcl.bitArray.equal`) when comparing hashes
329
5. **Consider salting** when hashing passwords or user data