0
# Hash Functions
1

2
Cryptographic hash functions including BLAKE2b, SHA-256, and SHA-512 for data integrity, key derivation, and digital fingerprints.
3

4
## Capabilities
5

6
### BLAKE2b Generic Hash
7

8
High-performance cryptographic hash function with optional keying support.
9

10
```javascript { .api }
11
/**
12
 * Compute BLAKE2b hash (one-shot)
13
 * @param output - Output buffer for hash (length determines hash size)
14
 * @param input - Input buffer to hash
15
 * @param key - Optional key buffer for keyed hashing (can be null/undefined)
16
 * @throws Error if buffer sizes are invalid or hashing fails
17
 */
18
function crypto_generichash(output: Buffer, input: Buffer, key?: Buffer): void;
19
```
20

21
**Usage Example:**
22

23
```javascript
24
const sodium = require('sodium-native');
25

26
// Basic hashing
27
const message = Buffer.from('Hello, World!');
28
const hash = Buffer.alloc(32); // 256-bit hash
29
sodium.crypto_generichash(hash, message);
30

31
// Keyed hashing (HMAC-like)
32
const key = Buffer.alloc(sodium.crypto_generichash_KEYBYTES);
33
sodium.randombytes_buf(key);
34
const keyedHash = Buffer.alloc(64); // 512-bit hash
35
sodium.crypto_generichash(keyedHash, message, key);
36
```
37

38
### BLAKE2b Batch Hashing
39

40
Efficiently hash multiple buffers in a single operation.
41

42
```javascript { .api }
43
/**
44
 * Compute BLAKE2b hash of multiple buffers
45
 * @param output - Output buffer for hash
46
 * @param batch - Array of buffers to hash
47
 * @param key - Optional key buffer for keyed hashing
48
 * @throws Error if hashing fails
49
 */
50
function crypto_generichash_batch(output: Buffer, batch: Buffer[], key?: Buffer): void;
51
```
52

53
### BLAKE2b Streaming Hash
54

55
Initialize, update, and finalize BLAKE2b hash computation for large data.
56

57
```javascript { .api }
58
/**
59
 * Generate random key for BLAKE2b
60
 * @param key - Output buffer for key (must be KEYBYTES long)
61
 * @throws Error if key generation fails
62
 */
63
function crypto_generichash_keygen(key: Buffer): void;
64

65
/**
66
 * Initialize BLAKE2b streaming hash
67
 * @param state - State buffer (must be STATEBYTES long)
68
 * @param key - Optional key buffer for keyed hashing
69
 * @param outputLength - Desired output hash length in bytes
70
 * @throws Error if initialization fails or parameters invalid
71
 */
72
function crypto_generichash_init(state: Buffer, key?: Buffer, outputLength?: number): void;
73

74
/**
75
 * Update BLAKE2b streaming hash with more data
76
 * @param state - State buffer from init
77
 * @param input - Input buffer to add to hash
78
 * @throws Error if update fails
79
 */
80
function crypto_generichash_update(state: Buffer, input: Buffer): void;
81

82
/**
83
 * Finalize BLAKE2b streaming hash and get result
84
 * @param state - State buffer from init/update
85
 * @param output - Output buffer for final hash
86
 * @throws Error if finalization fails
87
 */
88
function crypto_generichash_final(state: Buffer, output: Buffer): void;
89
```
90

91
**Usage Example:**
92

93
```javascript
94
const sodium = require('sodium-native');
95

96
// Streaming hash for large data
97
const state = Buffer.alloc(sodium.crypto_generichash_STATEBYTES);
98
const key = Buffer.alloc(sodium.crypto_generichash_KEYBYTES);
99
sodium.crypto_generichash_keygen(key);
100

101
sodium.crypto_generichash_init(state, key, 32);
102

103
// Process data in chunks
104
const chunk1 = Buffer.from('First part ');
105
const chunk2 = Buffer.from('of large message');
106
sodium.crypto_generichash_update(state, chunk1);
107
sodium.crypto_generichash_update(state, chunk2);
108

109
const finalHash = Buffer.alloc(32);
110
sodium.crypto_generichash_final(state, finalHash);
111
```
112

113
### SHA-512 Hash
114

115
Standard SHA-512 cryptographic hash function.
116

117
```javascript { .api }
118
/**
119
 * Compute SHA-512 hash (one-shot)
120
 * @param out - Output buffer for hash (must be BYTES long)
121
 * @param input - Input buffer to hash
122
 * @throws Error if hashing fails
123
 */
124
function crypto_hash(out: Buffer, input: Buffer): void;
125

126
/**
127
 * Compute SHA-512 hash (one-shot, explicit function)
128
 * @param out - Output buffer for hash (must be BYTES long)
129
 * @param input - Input buffer to hash
130
 * @throws Error if hashing fails
131
 */
132
function crypto_hash_sha512(out: Buffer, input: Buffer): void;
133
```
134

135
### SHA-512 Streaming Hash
136

137
Initialize, update, and finalize SHA-512 hash computation.
138

139
```javascript { .api }
140
/**
141
 * Initialize SHA-512 streaming hash
142
 * @param state - State buffer (must be STATEBYTES long)
143
 * @throws Error if initialization fails
144
 */
145
function crypto_hash_sha512_init(state: Buffer): void;
146

147
/**
148
 * Update SHA-512 streaming hash with more data
149
 * @param state - State buffer from init
150
 * @param input - Input buffer to add to hash
151
 * @throws Error if update fails
152
 */
153
function crypto_hash_sha512_update(state: Buffer, input: Buffer): void;
154

155
/**
156
 * Finalize SHA-512 streaming hash and get result
157
 * @param state - State buffer from init/update
158
 * @param out - Output buffer for final hash (must be BYTES long)
159
 * @throws Error if finalization fails
160
 */
161
function crypto_hash_sha512_final(state: Buffer, out: Buffer): void;
162
```
163

164
### SHA-256 Hash
165

166
Standard SHA-256 cryptographic hash function.
167

168
```javascript { .api }
169
/**
170
 * Compute SHA-256 hash (one-shot)
171
 * @param out - Output buffer for hash (must be BYTES long)
172
 * @param input - Input buffer to hash
173
 * @throws Error if hashing fails
174
 */
175
function crypto_hash_sha256(out: Buffer, input: Buffer): void;
176

177
/**
178
 * Initialize SHA-256 streaming hash
179
 * @param state - State buffer (must be STATEBYTES long)
180
 * @throws Error if initialization fails
181
 */
182
function crypto_hash_sha256_init(state: Buffer): void;
183

184
/**
185
 * Update SHA-256 streaming hash with more data
186
 * @param state - State buffer from init
187
 * @param input - Input buffer to add to hash
188
 * @throws Error if update fails
189
 */
190
function crypto_hash_sha256_update(state: Buffer, input: Buffer): void;
191

192
/**
193
 * Finalize SHA-256 streaming hash and get result
194
 * @param state - State buffer from init/update
195
 * @param out - Output buffer for final hash (must be BYTES long)
196
 * @throws Error if finalization fails
197
 */
198
function crypto_hash_sha256_final(state: Buffer, out: Buffer): void;
199
```
200

201
**Usage Example:**
202

203
```javascript
204
const sodium = require('sodium-native');
205

206
// SHA-256 one-shot
207
const message = Buffer.from('Hello, World!');
208
const sha256Hash = Buffer.alloc(sodium.crypto_hash_sha256_BYTES);
209
sodium.crypto_hash_sha256(sha256Hash, message);
210

211
// SHA-256 streaming
212
const sha256State = Buffer.alloc(sodium.crypto_hash_sha256_STATEBYTES);
213
sodium.crypto_hash_sha256_init(sha256State);
214
sodium.crypto_hash_sha256_update(sha256State, Buffer.from('Hello, '));
215
sodium.crypto_hash_sha256_update(sha256State, Buffer.from('World!'));
216

217
const streamedHash = Buffer.alloc(sodium.crypto_hash_sha256_BYTES);
218
sodium.crypto_hash_sha256_final(sha256State, streamedHash);
219
```
220

221
## Constants
222

223
```javascript { .api }
224
// BLAKE2b generic hash constants
225
const crypto_generichash_STATEBYTES: number;
226
const crypto_generichash_BYTES_MIN: number;
227
const crypto_generichash_BYTES_MAX: number;
228
const crypto_generichash_BYTES: number;
229
const crypto_generichash_KEYBYTES_MIN: number;
230
const crypto_generichash_KEYBYTES_MAX: number;
231
const crypto_generichash_KEYBYTES: number;
232

233
// SHA-512 constants
234
const crypto_hash_BYTES: number;
235
const crypto_hash_sha512_STATEBYTES: number;
236
const crypto_hash_sha512_BYTES: number;
237

238
// SHA-256 constants
239
const crypto_hash_sha256_STATEBYTES: number;
240
const crypto_hash_sha256_BYTES: number;
241
```
242

243
## Common Patterns
244

245
### File Hashing
246

247
```javascript
248
const sodium = require('sodium-native');
249
const fs = require('fs');
250

251
function hashFile(filename, algorithm = 'blake2b') {
252
  const data = fs.readFileSync(filename);
253
  
254
  switch (algorithm) {
255
    case 'blake2b':
256
      const blake2bHash = Buffer.alloc(32);
257
      sodium.crypto_generichash(blake2bHash, data);
258
      return blake2bHash;
259
      
260
    case 'sha256':
261
      const sha256Hash = Buffer.alloc(sodium.crypto_hash_sha256_BYTES);
262
      sodium.crypto_hash_sha256(sha256Hash, data);
263
      return sha256Hash;
264
      
265
    case 'sha512':
266
      const sha512Hash = Buffer.alloc(sodium.crypto_hash_sha512_BYTES);
267
      sodium.crypto_hash_sha512(sha512Hash, data);
268
      return sha512Hash;
269
      
270
    default:
271
      throw new Error('Unsupported algorithm');
272
  }
273
}
274
```
275

276
### Merkle Tree Implementation
277

278
```javascript
279
const sodium = require('sodium-native');
280

281
class MerkleTree {
282
  constructor(leaves) {
283
    this.leaves = leaves.map(leaf => this.hash(leaf));
284
    this.tree = this.buildTree(this.leaves);
285
  }
286
  
287
  hash(data) {
288
    const hash = Buffer.alloc(32);
289
    sodium.crypto_generichash(hash, data);
290
    return hash;
291
  }
292
  
293
  buildTree(nodes) {
294
    if (nodes.length === 1) return nodes[0];
295
    
296
    const nextLevel = [];
297
    for (let i = 0; i < nodes.length; i += 2) {
298
      const left = nodes[i];
299
      const right = nodes[i + 1] || left;
300
      const combined = Buffer.concat([left, right]);
301
      nextLevel.push(this.hash(combined));
302
    }
303
    
304
    return this.buildTree(nextLevel);
305
  }
306
  
307
  getRoot() {
308
    return this.tree;
309
  }
310
}
311
```
312

313
### Key Derivation Function
314

315
```javascript
316
const sodium = require('sodium-native');
317

318
function deriveKey(password, salt, keyLength = 32) {
319
  // Simple key derivation using BLAKE2b
320
  const combined = Buffer.concat([password, salt]);
321
  const key = Buffer.alloc(keyLength);
322
  sodium.crypto_generichash(key, combined);
323
  return key;
324
}
325

326
function deriveMultipleKeys(masterKey, context, count) {
327
  const keys = [];
328
  for (let i = 0; i < count; i++) {
329
    const input = Buffer.concat([
330
      masterKey,
331
      Buffer.from(context),
332
      Buffer.from([i])
333
    ]);
334
    const derivedKey = Buffer.alloc(32);
335
    sodium.crypto_generichash(derivedKey, input);
336
    keys.push(derivedKey);
337
  }
338
  return keys;
339
}
340
```