0
# Password Hashing
1

2
Secure password hashing using memory-hard functions designed to resist brute-force attacks. Supports both Argon2 (recommended) and Scrypt algorithms with configurable security parameters.
3

4
## Capabilities
5

6
### Argon2 Password Hashing (Recommended)
7

8
Modern password hashing using Argon2id, the winner of the Password Hashing Competition.
9

10
```javascript { .api }
11
/**
12
 * Hashes a password into a string format suitable for storage
13
 * @param password - The password to hash (string or Uint8Array)
14
 * @param opsLimit - CPU/time cost parameter (higher = more secure, slower)
15
 * @param memLimit - Memory cost parameter in bytes (higher = more secure, more memory)
16
 * @returns String-encoded hash suitable for database storage
17
 */
18
function crypto_pwhash_str(password, opsLimit, memLimit);
19

20
/**
21
 * Verifies a password against its stored hash
22
 * @param hashed_password - String-encoded hash from crypto_pwhash_str
23
 * @param password - Password to verify
24
 * @returns true if password matches, false otherwise
25
 */
26
function crypto_pwhash_str_verify(hashed_password, password);
27

28
/**
29
 * Checks if a stored hash needs rehashing with updated parameters
30
 * @param hashed_password - String-encoded hash to check
31
 * @param opsLimit - Current recommended CPU cost
32
 * @param memLimit - Current recommended memory cost
33
 * @returns true if hash should be updated, false if current parameters are sufficient
34
 */
35
function crypto_pwhash_str_needs_rehash(hashed_password, opsLimit, memLimit);
36

37
/**
38
 * Derives a key from a password using Argon2
39
 * @param keyLength - Length of derived key in bytes
40
 * @param password - Password to derive from
41
 * @param salt - 16-byte salt (must be unique per password)
42
 * @param opsLimit - CPU/time cost parameter
43
 * @param memLimit - Memory cost parameter in bytes
44
 * @param algorithm - Algorithm to use (ALG_ARGON2I13 or ALG_ARGON2ID13)
45
 * @returns Derived key of specified length
46
 */
47
function crypto_pwhash(keyLength, password, salt, opsLimit, memLimit, algorithm);
48
```
49

50
**Usage Example:**
51

52
```javascript
53
// Hash a password for storage
54
const password = "user_password_123";
55
const hash = sodium.crypto_pwhash_str(
56
  password,
57
  sodium.crypto_pwhash_OPSLIMIT_INTERACTIVE,
58
  sodium.crypto_pwhash_MEMLIMIT_INTERACTIVE
59
);
60

61
console.log(hash); // "$argon2id$v=19$m=65536,t=2,p=1$..."
62

63
// Verify password during login
64
const isValid = sodium.crypto_pwhash_str_verify(hash, password);
65
console.log(isValid); // true
66

67
// Check if rehashing is needed (e.g., after upgrading security parameters)
68
const needsRehash = sodium.crypto_pwhash_str_needs_rehash(
69
  hash,
70
  sodium.crypto_pwhash_OPSLIMIT_SENSITIVE,
71
  sodium.crypto_pwhash_MEMLIMIT_SENSITIVE
72
);
73

74
if (needsRehash) {
75
  const newHash = sodium.crypto_pwhash_str(
76
    password,
77
    sodium.crypto_pwhash_OPSLIMIT_SENSITIVE,
78
    sodium.crypto_pwhash_MEMLIMIT_SENSITIVE
79
  );
80
  // Update stored hash in database
81
}
82
```
83

84
### Scrypt Password Hashing
85

86
Legacy support for Scrypt-based password hashing.
87

88
```javascript { .api }
89
/**
90
 * Hashes a password using Scrypt
91
 * @param password - Password to hash
92
 * @param opsLimit - CPU/time cost parameter
93
 * @param memLimit - Memory cost parameter
94
 * @returns String-encoded Scrypt hash
95
 */
96
function crypto_pwhash_scryptsalsa208sha256_str(password, opsLimit, memLimit);
97

98
/**
99
 * Verifies a password against Scrypt hash
100
 * @param hashed_password - String-encoded Scrypt hash
101
 * @param password - Password to verify
102
 * @returns true if password matches, false otherwise
103
 */
104
function crypto_pwhash_scryptsalsa208sha256_str_verify(hashed_password, password);
105

106
/**
107
 * Derives a key using Scrypt
108
 * @param keyLength - Length of derived key
109
 * @param password - Password to derive from
110
 * @param salt - 32-byte salt for Scrypt
111
 * @param opsLimit - CPU/time cost parameter
112
 * @param memLimit - Memory cost parameter
113
 * @returns Derived key
114
 */
115
function crypto_pwhash_scryptsalsa208sha256(keyLength, password, salt, opsLimit, memLimit);
116

117
/**
118
 * Low-level Scrypt function with full parameter control
119
 * @param password - Password bytes
120
 * @param salt - Salt bytes
121
 * @param opsLimit - CPU cost (N parameter)
122
 * @param r - Block size parameter
123
 * @param p - Parallelization parameter
124
 * @param keyLength - Output key length
125
 * @returns Derived key
126
 */
127
function crypto_pwhash_scryptsalsa208sha256_ll(password, salt, opsLimit, r, p, keyLength);
128
```
129

130
## Security Parameters
131

132
### Argon2 Parameters
133

134
```javascript { .api }
135
// Algorithms
136
const crypto_pwhash_ALG_ARGON2I13 = 1;   // Argon2i (side-channel resistant)
137
const crypto_pwhash_ALG_ARGON2ID13 = 2;  // Argon2id (recommended, default)
138
const crypto_pwhash_ALG_DEFAULT = 2;     // Default to Argon2id
139

140
// Operation limits (CPU cost)
141
const crypto_pwhash_OPSLIMIT_INTERACTIVE = 2;    // Fast, for interactive use
142
const crypto_pwhash_OPSLIMIT_SENSITIVE = 4;      // Slower, for sensitive data
143

144
// Memory limits  
145
const crypto_pwhash_MEMLIMIT_INTERACTIVE = 67108864;  // 64 MB
146
const crypto_pwhash_MEMLIMIT_SENSITIVE = 268435456;   // 256 MB
147

148
// Constraints
149
const crypto_pwhash_PASSWD_MIN = 0;        // Minimum password length
150
const crypto_pwhash_PASSWD_MAX = 4294967295; // Maximum password length
151
const crypto_pwhash_SALTBYTES = 16;        // Salt size for Argon2
152
const crypto_pwhash_STRBYTES = 102;        // String format length
153
```
154

155
### Scrypt Parameters
156

157
```javascript { .api }
158
// Operation limits
159
const crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_INTERACTIVE = 32768;
160
const crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_SENSITIVE = 1048576;
161

162
// Memory limits  
163
const crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_INTERACTIVE = 16777216;  // 16 MB
164
const crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_SENSITIVE = 1073741824; // 1 GB
165

166
// Constraints
167
const crypto_pwhash_scryptsalsa208sha256_SALTBYTES = 32;  // Salt size for Scrypt
168
const crypto_pwhash_scryptsalsa208sha256_STRBYTES = 102;  // String format length
169
```
170

171
## Key Derivation Example
172

173
```javascript
174
// Derive encryption key from password
175
const password = "user_password_123";
176
const salt = sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);
177

178
const encryptionKey = sodium.crypto_pwhash(
179
  32,  // 32-byte key
180
  password,
181
  salt,
182
  sodium.crypto_pwhash_OPSLIMIT_INTERACTIVE,
183
  sodium.crypto_pwhash_MEMLIMIT_INTERACTIVE,
184
  sodium.crypto_pwhash_ALG_ARGON2ID13
185
);
186

187
// Store salt with encrypted data for later key derivation
188
```
189

190
## Security Considerations
191

192
- **Parameter Selection**: Use INTERACTIVE parameters for user-facing operations, SENSITIVE for high-value data
193
- **Algorithm Choice**: Use Argon2id (default) unless you specifically need Argon2i for side-channel resistance
194
- **Salt Management**: Always use unique, random salts for each password
195
- **Upgrade Strategy**: Regularly check and update hash parameters as computing power increases
196
- **Memory Requirements**: Ensure your system can handle the memory requirements, especially for SENSITIVE parameters
197
- **Timing**: Higher parameters increase security but also increase login time - balance appropriately