0
# Hashing and Key Derivation
1

2
Cryptographic hash functions and key derivation functions for data integrity, key management, and secure key generation from master keys.
3

4
## Capabilities
5

6
### Generic Hash (BLAKE2b)
7

8
Fast, secure hash function suitable for general-purpose hashing with optional keying for MAC operations.
9

10
```javascript { .api }
11
/**
12
 * Computes a BLAKE2b hash of the input
13
 * @param hash_length - Desired hash length in bytes (1-64)
14
 * @param message - The data to hash
15
 * @param key - Optional key for keyed hashing (MAC mode)
16
 * @returns Hash digest of specified length
17
 */
18
function crypto_generichash(hash_length, message, key);
19

20
/**
21
 * Generates a random key for keyed generic hashing
22
 * @returns 32-byte key for BLAKE2b MAC mode
23
 */
24
function crypto_generichash_keygen();
25

26
/**
27
 * Initializes streaming hash computation
28
 * @param key - Optional key for keyed hashing
29
 * @param hash_length - Desired final hash length in bytes
30
 * @returns State address for streaming operations
31
 */
32
function crypto_generichash_init(key, hash_length);
33

34
/**
35
 * Updates streaming hash with a data chunk
36
 * @param state_address - State from crypto_generichash_init
37
 * @param message_chunk - Data to add to the hash
38
 */
39
function crypto_generichash_update(state_address, message_chunk);
40

41
/**
42
 * Finalizes streaming hash computation
43
 * @param state_address - State from crypto_generichash_init
44
 * @param hash_length - Final hash length in bytes
45
 * @returns Final hash digest
46
 */
47
function crypto_generichash_final(state_address, hash_length);
48

49
/**
50
 * BLAKE2b with salt and personalization parameters
51
 * @param subkey_len - Length of derived key/hash
52
 * @param key - Optional key material
53
 * @param id - Salt parameter for domain separation
54
 * @param ctx - Personalization parameter
55
 * @returns Derived key or hash
56
 */
57
function crypto_generichash_blake2b_salt_personal(subkey_len, key, id, ctx);
58
```
59

60
**Usage Example:**
61

62
```javascript
63
// Simple hash
64
const message = sodium.from_string("Hello, World!");
65
const hash = sodium.crypto_generichash(32, message);
66
console.log(sodium.to_hex(hash));
67

68
// Keyed hash (MAC)
69
const key = sodium.crypto_generichash_keygen();
70
const mac = sodium.crypto_generichash(32, message, key);
71

72
// Streaming hash
73
let state = sodium.crypto_generichash_init(null, 32);
74
sodium.crypto_generichash_update(state, sodium.from_string("Hello, "));
75
sodium.crypto_generichash_update(state, sodium.from_string("World!"));
76
const streamHash = sodium.crypto_generichash_final(state, 32);
77
```
78

79
### Standard Hash Functions
80

81
```javascript { .api }
82
/**
83
 * Computes SHA-512 hash
84
 * @param message - The data to hash
85
 * @returns 64-byte SHA-512 hash
86
 */
87
function crypto_hash(message);
88

89
/**
90
 * Computes SHA-256 hash
91
 * @param message - The data to hash
92
 * @returns 32-byte SHA-256 hash
93
 */
94
function crypto_hash_sha256(message);
95

96
/**
97
 * Computes SHA-512 hash
98
 * @param message - The data to hash
99
 * @returns 64-byte SHA-512 hash
100
 */
101
function crypto_hash_sha512(message);
102
```
103

104
### Streaming Standard Hashes
105

106
```javascript { .api }
107
// SHA-256 streaming
108
function crypto_hash_sha256_init();
109
function crypto_hash_sha256_update(state_address, message_chunk);
110
function crypto_hash_sha256_final(state_address);
111

112
// SHA-512 streaming
113
function crypto_hash_sha512_init();
114
function crypto_hash_sha512_update(state_address, message_chunk);
115
function crypto_hash_sha512_final(state_address);
116
```
117

118
### Key Derivation Function (KDF)
119

120
Derive multiple keys from a single master key using BLAKE2b-based KDF.
121

122
```javascript { .api }
123
/**
124
 * Derives a subkey from a master key
125
 * @param subkey_len - Length of derived key in bytes
126
 * @param subkey_id - Subkey identifier (number or BigInt)
127
 * @param ctx - Context string for domain separation (null-terminated)
128
 * @param key - 32-byte master key
129
 * @returns Derived subkey of specified length
130
 */
131
function crypto_kdf_derive_from_key(subkey_len, subkey_id, ctx, key);
132

133
/**
134
 * Generates a random master key for KDF operations
135
 * @returns 32-byte master key
136
 */
137
function crypto_kdf_keygen();
138
```
139

140
**KDF Usage Example:**
141

142
```javascript
143
// Generate master key
144
const masterKey = sodium.crypto_kdf_keygen();
145

146
// Derive different keys for different purposes
147
const encryptionKey = sodium.crypto_kdf_derive_from_key(32, 1, "encryption", masterKey);
148
const authKey = sodium.crypto_kdf_derive_from_key(32, 2, "authentication", masterKey);
149
const signingKey = sodium.crypto_kdf_derive_from_key(32, 3, "signing", masterKey);
150

151
// Keys are deterministic - same inputs always produce same outputs
152
const sameKey = sodium.crypto_kdf_derive_from_key(32, 1, "encryption", masterKey);
153
// encryptionKey equals sameKey
154
```
155

156
### Short Hash Functions
157

158
Fast keyed hash functions designed for hash tables, data structures, and checksums. Provides shorter outputs optimized for performance over security.
159

160
```javascript { .api }
161
/**
162
 * Computes a fast keyed short hash using SipHash-2-4
163
 * @param message - The data to hash
164
 * @param key - 16-byte key for the hash function
165
 * @returns 8-byte hash digest
166
 */
167
function crypto_shorthash(message, key);
168

169
/**
170
 * Generates a random key for short hash functions
171
 * @returns 16-byte key for short hash operations
172
 */
173
function crypto_shorthash_keygen();
174

175
/**
176
 * Computes a keyed short hash using SipHashX-2-4 variant
177
 * @param message - The data to hash  
178
 * @param key - 16-byte key for the hash function
179
 * @returns 16-byte hash digest (longer than standard short hash)
180
 */
181
function crypto_shorthash_siphashx24(message, key);
182
```
183

184
**Short Hash Usage Example:**
185

186
```javascript
187
// Generate key for consistent hashing
188
const shortHashKey = sodium.crypto_shorthash_keygen();
189

190
// Hash data for hash table or data structure
191
const data1 = sodium.from_string("user:123");
192
const data2 = sodium.from_string("user:456");
193

194
const hash1 = sodium.crypto_shorthash(data1, shortHashKey);
195
const hash2 = sodium.crypto_shorthash(data2, shortHashKey);
196

197
// Convert to numbers for hash table indexing
198
const hashNum1 = new DataView(hash1.buffer).getBigUint64(0, true);
199
const hashNum2 = new DataView(hash2.buffer).getBigUint64(0, true);
200

201
// Use SipHashX variant for 16-byte output when more hash bits are needed
202
const longHash = sodium.crypto_shorthash_siphashx24(data1, shortHashKey);
203
```
204

205
## Constants
206

207
```javascript { .api }
208
// Generic Hash (BLAKE2b)
209
const crypto_generichash_BYTES = 32;           // Default hash size
210
const crypto_generichash_BYTES_MIN = 16;       // Minimum hash size
211
const crypto_generichash_BYTES_MAX = 64;       // Maximum hash size
212
const crypto_generichash_KEYBYTES = 32;        // Key size for MAC mode
213
const crypto_generichash_KEYBYTES_MIN = 16;    // Minimum key size
214
const crypto_generichash_KEYBYTES_MAX = 64;    // Maximum key size
215

216
// Standard Hashes
217
const crypto_hash_BYTES = 64;                  // SHA-512 size
218
const crypto_hash_sha256_BYTES = 32;           // SHA-256 size
219
const crypto_hash_sha512_BYTES = 64;           // SHA-512 size
220

221
// Key Derivation
222
const crypto_kdf_BYTES_MIN = 16;               // Minimum derived key size
223
const crypto_kdf_BYTES_MAX = 64;               // Maximum derived key size
224
const crypto_kdf_KEYBYTES = 32;                // Master key size
225
const crypto_kdf_CONTEXTBYTES = 8;             // Context string size
226

227
// Short Hash
228
const crypto_shorthash_BYTES = 8;              // Short hash size
229
const crypto_shorthash_KEYBYTES = 16;          // Short hash key size
230
const crypto_shorthash_siphashx24_BYTES = 16;  // SipHashX-2-4 hash size
231
const crypto_shorthash_siphashx24_KEYBYTES = 16; // SipHashX-2-4 key size
232
```
233

234
## Security Considerations
235

236
- **Hash Selection**: Use BLAKE2b (generic hash) for new applications - it's faster and more secure than SHA-2
237
- **Key Management**: Keep KDF master keys secure - compromise exposes all derived keys
238
- **Context Separation**: Use different context strings for different key purposes in KDF
239
- **Streaming State**: Properly manage streaming hash state to avoid memory leaks
240
- **MAC Keys**: Use random keys for MAC operations, not passwords or predictable values
241
- **Short Hash Usage**: Short hashes are designed for performance, not cryptographic security
242
  - Use for hash tables, checksums, and non-security-critical applications
243
  - Do not use for cryptographic purposes - use BLAKE2b or HMAC instead
244
  - Always use a secret key to prevent hash flooding attacks in data structures