0
# Message Authentication
1

2
Message Authentication Code (MAC) functions for verifying message integrity and authenticity. These functions ensure that messages have not been tampered with and confirm the identity of the sender.
3

4
## Capabilities
5

6
### Generic Authentication
7

8
HMAC-SHA512-256 based authentication providing strong security with reasonable performance.
9

10
```javascript { .api }
11
/**
12
 * Computes an authentication tag for a message
13
 * @param message - The message to authenticate
14
 * @param key - 32-byte authentication key
15
 * @returns 32-byte authentication tag
16
 */
17
function crypto_auth(message, key);
18

19
/**
20
 * Verifies an authentication tag
21
 * @param tag - 32-byte authentication tag to verify
22
 * @param message - The original message
23
 * @param key - 32-byte authentication key used for tagging
24
 * @returns true if tag is valid, false otherwise
25
 */
26
function crypto_auth_verify(tag, message, key);
27

28
/**
29
 * Generates a random authentication key
30
 * @returns 32-byte authentication key
31
 */
32
function crypto_auth_keygen();
33
```
34

35
### HMAC-SHA256
36

37
```javascript { .api }
38
function crypto_auth_hmacsha256(message, key);
39
function crypto_auth_hmacsha256_verify(tag, message, key);
40
function crypto_auth_hmacsha256_keygen();
41

42
// Streaming operations
43
function crypto_auth_hmacsha256_init(key);
44
function crypto_auth_hmacsha256_update(state_address, message_chunk);
45
function crypto_auth_hmacsha256_final(state_address);
46
```
47

48
### HMAC-SHA512
49

50
```javascript { .api }
51
function crypto_auth_hmacsha512(message, key);
52
function crypto_auth_hmacsha512_verify(tag, message, key);
53
function crypto_auth_hmacsha512_keygen();
54

55
// Streaming operations
56
function crypto_auth_hmacsha512_init(key);
57
function crypto_auth_hmacsha512_update(state_address, message_chunk);
58
function crypto_auth_hmacsha512_final(state_address);
59
```
60

61
### HMAC-SHA512-256
62

63
```javascript { .api }
64
function crypto_auth_hmacsha512256(message, key);
65
function crypto_auth_hmacsha512256_verify(tag, message, key);
66
function crypto_auth_hmacsha512256_keygen();
67

68
// Streaming operations
69
function crypto_auth_hmacsha512256_init(key);
70
function crypto_auth_hmacsha512256_update(state_address, message_chunk);
71
function crypto_auth_hmacsha512256_final(state_address);
72
```
73

74
### One-Time Authentication
75

76
Poly1305-based one-time authentication for high-speed applications.
77

78
```javascript { .api }
79
/**
80
 * Computes a Poly1305 authentication tag
81
 * @param message - The message to authenticate
82
 * @param key - 32-byte one-time key (must never be reused)
83
 * @returns 16-byte authentication tag
84
 */
85
function crypto_onetimeauth(message, key);
86

87
/**
88
 * Verifies a Poly1305 authentication tag
89
 * @param hash - 16-byte authentication tag to verify
90
 * @param message - The original message
91
 * @param key - 32-byte one-time key used for tagging
92
 * @returns true if tag is valid, false otherwise
93
 */
94
function crypto_onetimeauth_verify(hash, message, key);
95

96
/**
97
 * Generates a random one-time authentication key
98
 * @returns 32-byte one-time key
99
 */
100
function crypto_onetimeauth_keygen();
101

102
// Streaming operations
103
function crypto_onetimeauth_init(key);
104
function crypto_onetimeauth_update(state_address, message_chunk);
105
function crypto_onetimeauth_final(state_address);
106
```
107

108
## Usage Examples
109

110
**Basic Authentication:**
111

112
```javascript
113
// Generate key and authenticate message
114
const key = sodium.crypto_auth_keygen();
115
const message = sodium.from_string("Important message");
116
const tag = sodium.crypto_auth(message, key);
117

118
// Verify authentication
119
const isValid = sodium.crypto_auth_verify(tag, message, key);
120
console.log(isValid); // true
121

122
// Tampered message fails verification
123
const tamperedMessage = sodium.from_string("Tampered message");
124
const stillValid = sodium.crypto_auth_verify(tag, tamperedMessage, key);
125
console.log(stillValid); // false
126
```
127

128
**Streaming Authentication:**
129

130
```javascript
131
// Authenticate large message in chunks
132
const key = sodium.crypto_auth_hmacsha256_keygen();
133
let state = sodium.crypto_auth_hmacsha256_init(key);
134

135
sodium.crypto_auth_hmacsha256_update(state, chunk1);
136
sodium.crypto_auth_hmacsha256_update(state, chunk2);
137
sodium.crypto_auth_hmacsha256_update(state, chunk3);
138

139
const tag = sodium.crypto_auth_hmacsha256_final(state);
140
```
141

142
## Constants
143

144
```javascript { .api }
145
// Generic Auth
146
const crypto_auth_BYTES = 32;           // Tag size
147
const crypto_auth_KEYBYTES = 32;        // Key size
148

149
// HMAC-SHA256
150
const crypto_auth_hmacsha256_BYTES = 32;
151
const crypto_auth_hmacsha256_KEYBYTES = 32;
152

153
// HMAC-SHA512
154
const crypto_auth_hmacsha512_BYTES = 64;
155
const crypto_auth_hmacsha512_KEYBYTES = 32;
156

157
// HMAC-SHA512-256
158
const crypto_auth_hmacsha512256_BYTES = 32;
159
const crypto_auth_hmacsha512256_KEYBYTES = 32;
160

161
// One-time Auth (Poly1305)
162
const crypto_onetimeauth_BYTES = 16;
163
const crypto_onetimeauth_KEYBYTES = 32;
164
```
165

166
## Security Considerations
167

168
- **Key Management**: Authentication keys must be kept secret and generated securely
169
- **One-time Keys**: Poly1305 keys must never be reused - each message needs a fresh key
170
- **Verification**: Always use constant-time verification functions to prevent timing attacks
171
- **Key Derivation**: Don't use passwords directly as keys - derive them using proper KDF functions
172
- **Algorithm Choice**: Use generic auth (HMAC-SHA512-256) for new applications unless specific requirements dictate otherwise