0
# Message Authentication
1

2
Message authentication functions provide cryptographic proof of message authenticity and integrity using HMAC (Hash-based Message Authentication Code) with various hash functions.
3

4
## Supported Algorithms
5

6
- **HMAC-SHA256**: Fast, widely supported, 32-byte output
7
- **HMAC-SHA512**: Higher security margin, 64-byte output  
8
- **HMAC-SHA512/256**: SHA-512 truncated to 32 bytes for performance
9
- **Generic Auth**: Defaults to HMAC-SHA512/256, recommended for new applications
10

11
## Generic Authentication (Recommended)
12

13
The generic authentication functions use HMAC-SHA512/256 and are recommended for new applications.
14

15
### Key Generation
16

17
```javascript { .api }
18
/**
19
 * Generate a random key for message authentication
20
 * @returns Uint8Array - 32-byte authentication key
21
 */
22
function crypto_auth_keygen(): Uint8Array;
23
```
24

25
### Authentication
26

27
```javascript { .api }
28
/**
29
 * Compute authentication tag for a message
30
 * @param message - Data to authenticate
31
 * @param key - 32-byte authentication key
32
 * @returns Uint8Array - 32-byte authentication tag
33
 */
34
function crypto_auth(message: Uint8Array, key: Uint8Array): Uint8Array;
35
```
36

37
### Verification
38

39
```javascript { .api }
40
/**
41
 * Verify authentication tag for a message
42
 * @param tag - Authentication tag to verify
43
 * @param message - Original message data
44
 * @param key - 32-byte authentication key
45
 * @returns boolean - True if tag is valid
46
 */
47
function crypto_auth_verify(
48
  tag: Uint8Array, 
49
  message: Uint8Array, 
50
  key: Uint8Array
51
): boolean;
52
```
53

54
### Constants
55

56
```javascript { .api }
57
const crypto_auth_BYTES: number;      // 32 (tag length)
58
const crypto_auth_KEYBYTES: number;   // 32 (key length)
59
```
60

61
## HMAC-SHA256
62

63
Fast HMAC implementation using SHA-256 hash function.
64

65
### Key Generation
66

67
```javascript { .api }
68
/**
69
 * Generate a random key for HMAC-SHA256
70
 * @returns Uint8Array - 32-byte key
71
 */
72
function crypto_auth_hmacsha256_keygen(): Uint8Array;
73
```
74

75
### One-Shot Operations
76

77
```javascript { .api }
78
/**
79
 * Compute HMAC-SHA256 authentication tag
80
 * @param message - Data to authenticate
81
 * @param key - 32-byte HMAC key
82
 * @returns Uint8Array - 32-byte authentication tag
83
 */
84
function crypto_auth_hmacsha256(
85
  message: Uint8Array, 
86
  key: Uint8Array
87
): Uint8Array;
88

89
/**
90
 * Verify HMAC-SHA256 authentication tag
91
 * @param tag - Tag to verify
92
 * @param message - Original message
93
 * @param key - 32-byte HMAC key
94
 * @returns boolean - True if tag is valid
95
 */
96
function crypto_auth_hmacsha256_verify(
97
  tag: Uint8Array, 
98
  message: Uint8Array, 
99
  key: Uint8Array
100
): boolean;
101
```
102

103
### Streaming Operations
104

105
```javascript { .api }
106
/**
107
 * Initialize HMAC-SHA256 streaming state
108
 * @param key - HMAC key (can be null for keyless operation)
109
 * @returns Uint8Array - State object for streaming
110
 */
111
function crypto_auth_hmacsha256_init(key: Uint8Array | null): Uint8Array;
112

113
/**
114
 * Update HMAC-SHA256 state with data chunk
115
 * @param state_address - State from init function
116
 * @param message_chunk - Data chunk to process
117
 */
118
function crypto_auth_hmacsha256_update(
119
  state_address: any, 
120
  message_chunk: Uint8Array
121
): void;
122

123
/**
124
 * Finalize HMAC-SHA256 and return authentication tag
125
 * @param state_address - State from init/update functions
126
 * @returns Uint8Array - Final authentication tag
127
 */
128
function crypto_auth_hmacsha256_final(state_address: any): Uint8Array;
129
```
130

131
### Constants
132

133
```javascript { .api }
134
const crypto_auth_hmacsha256_BYTES: number;      // 32
135
const crypto_auth_hmacsha256_KEYBYTES: number;   // 32
136
```
137

138
## HMAC-SHA512
139

140
HMAC implementation using SHA-512 hash function for maximum security.
141

142
### Key Generation
143

144
```javascript { .api }
145
/**
146
 * Generate a random key for HMAC-SHA512
147
 * @returns Uint8Array - 32-byte key
148
 */
149
function crypto_auth_hmacsha512_keygen(): Uint8Array;
150
```
151

152
### One-Shot Operations
153

154
```javascript { .api }
155
/**
156
 * Compute HMAC-SHA512 authentication tag
157
 * @param message - Data to authenticate
158
 * @param key - 32-byte HMAC key
159
 * @returns Uint8Array - 64-byte authentication tag
160
 */
161
function crypto_auth_hmacsha512(
162
  message: Uint8Array, 
163
  key: Uint8Array
164
): Uint8Array;
165

166
/**
167
 * Verify HMAC-SHA512 authentication tag
168
 * @param tag - Tag to verify
169
 * @param message - Original message
170
 * @param key - 32-byte HMAC key
171
 * @returns boolean - True if tag is valid
172
 */
173
function crypto_auth_hmacsha512_verify(
174
  tag: Uint8Array, 
175
  message: Uint8Array, 
176
  key: Uint8Array
177
): boolean;
178
```
179

180
### Streaming Operations
181

182
```javascript { .api }
183
function crypto_auth_hmacsha512_init(key: Uint8Array | null): Uint8Array;
184
function crypto_auth_hmacsha512_update(state_address: any, message_chunk: Uint8Array): void;
185
function crypto_auth_hmacsha512_final(state_address: any): Uint8Array;
186
```
187

188
### Constants
189

190
```javascript { .api }
191
const crypto_auth_hmacsha512_BYTES: number;      // 64
192
const crypto_auth_hmacsha512_KEYBYTES: number;   // 32
193
```
194

195
## HMAC-SHA512/256
196

197
HMAC using SHA-512 internally but truncated to 256 bits for better performance with security equivalent to SHA-256.
198

199
### Key Generation
200

201
```javascript { .api }
202
/**
203
 * Generate a random key for HMAC-SHA512/256
204
 * @returns Uint8Array - 32-byte key
205
 */
206
function crypto_auth_hmacsha512256_keygen(): Uint8Array;
207
```
208

209
### One-Shot Operations
210

211
```javascript { .api }
212
/**
213
 * Compute HMAC-SHA512/256 authentication tag
214
 * @param message - Data to authenticate
215
 * @param key - 32-byte HMAC key
216
 * @returns Uint8Array - 32-byte authentication tag
217
 */
218
function crypto_auth_hmacsha512256(
219
  message: Uint8Array, 
220
  key: Uint8Array
221
): Uint8Array;
222

223
/**
224
 * Verify HMAC-SHA512/256 authentication tag
225
 * @param tag - Tag to verify
226
 * @param message - Original message
227
 * @param key - 32-byte HMAC key
228
 * @returns boolean - True if tag is valid
229
 */
230
function crypto_auth_hmacsha512256_verify(
231
  tag: Uint8Array, 
232
  message: Uint8Array, 
233
  key: Uint8Array
234
): boolean;
235
```
236

237
### Streaming Operations
238

239
```javascript { .api }
240
function crypto_auth_hmacsha512256_init(key: Uint8Array | null): Uint8Array;
241
function crypto_auth_hmacsha512256_update(state_address: any, message_chunk: Uint8Array): void;
242
function crypto_auth_hmacsha512256_final(state_address: any): Uint8Array;
243
```
244

245
### Constants
246

247
```javascript { .api }
248
const crypto_auth_hmacsha512256_BYTES: number;      // 32
249
const crypto_auth_hmacsha512256_KEYBYTES: number;   // 32
250
```
251

252
## Usage Examples
253

254
### Basic Message Authentication
255

256
```javascript
257
import _sodium from 'libsodium-wrappers-sumo';
258
await _sodium.ready;
259
const sodium = _sodium;
260

261
// Generate authentication key
262
const key = sodium.crypto_auth_keygen();
263

264
// Message to authenticate
265
const message = sodium.from_string('Important message');
266

267
// Create authentication tag
268
const tag = sodium.crypto_auth(message, key);
269

270
// Verify authentication tag
271
const isValid = sodium.crypto_auth_verify(tag, message, key);
272
console.log('Message is authentic:', isValid); // true
273

274
// Tampered message verification
275
const tamperedMessage = sodium.from_string('Tampered message');
276
const isValidTampered = sodium.crypto_auth_verify(tag, tamperedMessage, key);
277
console.log('Tampered message is authentic:', isValidTampered); // false
278
```
279

280
### HMAC-SHA256 Authentication
281

282
```javascript
283
// Use HMAC-SHA256 specifically
284
const key = sodium.crypto_auth_hmacsha256_keygen();
285
const message = sodium.from_string('Data to authenticate');
286

287
const tag = sodium.crypto_auth_hmacsha256(message, key);
288
const isValid = sodium.crypto_auth_hmacsha256_verify(tag, message, key);
289

290
console.log('Tag length:', tag.length); // 32 bytes
291
console.log('Is valid:', isValid); // true
292
```
293

294
### Streaming Authentication for Large Data
295

296
```javascript
297
// Initialize streaming HMAC
298
const key = sodium.crypto_auth_hmacsha256_keygen();
299
const state = sodium.crypto_auth_hmacsha256_init(key);
300

301
// Process data in chunks
302
const chunk1 = sodium.from_string('First chunk of ');
303
const chunk2 = sodium.from_string('large data file');
304

305
sodium.crypto_auth_hmacsha256_update(state, chunk1);
306
sodium.crypto_auth_hmacsha256_update(state, chunk2);
307

308
// Finalize and get tag
309
const tag = sodium.crypto_auth_hmacsha256_final(state);
310

311
// Verify with complete message
312
const completeMessage = sodium.from_string('First chunk of large data file');
313
const isValid = sodium.crypto_auth_hmacsha256_verify(tag, completeMessage, key);
314
console.log('Streaming authentication valid:', isValid); // true
315
```
316

317
### API Token Authentication
318

319
```javascript
320
// Create API authentication system
321
class APIAuth {
322
  constructor() {
323
    this.key = sodium.crypto_auth_keygen();
324
  }
325
  
326
  createToken(payload) {
327
    const message = sodium.from_string(JSON.stringify(payload));
328
    const tag = sodium.crypto_auth(message, this.key);
329
    return {
330
      payload,
331
      signature: sodium.to_base64(tag)
332
    };
333
  }
334
  
335
  verifyToken(token) {
336
    try {
337
      const message = sodium.from_string(JSON.stringify(token.payload));
338
      const tag = sodium.from_base64(token.signature);
339
      return sodium.crypto_auth_verify(tag, message, this.key);
340
    } catch (e) {
341
      return false;
342
    }
343
  }
344
}
345

346
// Usage
347
const auth = new APIAuth();
348
const token = auth.createToken({ user: 'alice', exp: Date.now() + 3600000 });
349
console.log('Token valid:', auth.verifyToken(token)); // true
350
```
351

352
### Performance Comparison
353

354
```javascript
355
const message = new Uint8Array(1024 * 1024); // 1MB of data
356
const key = sodium.crypto_auth_keygen();
357

358
console.time('HMAC-SHA256');
359
const tag256 = sodium.crypto_auth_hmacsha256(message, key);
360
console.timeEnd('HMAC-SHA256');
361

362
console.time('HMAC-SHA512');
363
const tag512 = sodium.crypto_auth_hmacsha512(message, key);
364
console.timeEnd('HMAC-SHA512');
365

366
console.time('HMAC-SHA512/256');
367
const tag512256 = sodium.crypto_auth_hmacsha512256(message, key);
368
console.timeEnd('HMAC-SHA512/256');
369

370
console.log('Tag lengths:', tag256.length, tag512.length, tag512256.length);
371
// Output: Tag lengths: 32 64 32
372
```
373

374
## Security Considerations
375

376
- **Key Management**: Keep authentication keys secret and use crypto_auth_keygen() for generation
377
- **Constant-Time Verification**: All verify functions use constant-time comparison to prevent timing attacks
378
- **Algorithm Selection**: Use generic crypto_auth() for new applications, specific variants for compatibility
379
- **Tag Storage**: Authentication tags can be stored publicly but should not be modified
380
- **Message Integrity**: Authentication provides integrity but not confidentiality - use AEAD for both
381

382
## Algorithm Selection Guide
383

384
- **crypto_auth()**: Recommended for new applications (HMAC-SHA512/256)
385
- **HMAC-SHA256**: Wide compatibility, good performance
386
- **HMAC-SHA512**: Maximum security, larger tags
387
- **HMAC-SHA512/256**: Good balance of security and performance