0
# Parameter Profiles
1

2
Predefined parameter configurations following RFC 9106 recommendations and utilities for parameter management, extraction, and platform validation.
3

4
## Capabilities
5

6
### Parameter Management
7

8
Container class for Argon2 hash parameters with all necessary configuration options.
9

10
```python { .api }
11
@dataclass
12
class Parameters:
13
    """
14
    Argon2 hash parameters.
15
    
16
    Contains all parameters needed to configure Argon2 hashing
17
    including algorithm variant, memory usage, time cost, and output formats.
18
    """
19
    
20
    type: Type           # Hash type (I, D, or ID)
21
    version: int        # Argon2 version number
22
    salt_len: int       # Length of salt in bytes
23
    hash_len: int       # Length of hash output in bytes
24
    time_cost: int      # Time cost in iterations
25
    memory_cost: int    # Memory cost in kibibytes
26
    parallelism: int    # Number of parallel threads
27
```
28

29
#### Usage Example
30

31
```python
32
from argon2 import Parameters, Type, PasswordHasher
33

34
# Create custom parameters
35
custom_params = Parameters(
36
    type=Type.ID,
37
    version=19,
38
    salt_len=16,
39
    hash_len=32,
40
    time_cost=4,
41
    memory_cost=131072,  # 128 MiB
42
    parallelism=2
43
)
44

45
# Use with PasswordHasher
46
ph = PasswordHasher.from_parameters(custom_params)
47
```
48

49
### Parameter Extraction
50

51
Extract parameters from existing hash strings to understand their configuration.
52

53
```python { .api }
54
def extract_parameters(hash: str) -> Parameters:
55
    """
56
    Extract parameters from an encoded hash string.
57
    
58
    Parses an Argon2 hash string and returns a Parameters object
59
    containing all the configuration used to create that hash.
60
    
61
    Args:
62
        hash: Encoded Argon2 hash string (e.g., from PasswordHasher.hash())
63
    
64
    Returns:
65
        Parameters object with extracted configuration
66
    
67
    Raises:
68
        argon2.exceptions.InvalidHashError: If hash format is invalid
69
    """
70
```
71

72
#### Usage Example
73

74
```python
75
from argon2 import PasswordHasher, extract_parameters
76

77
# Create a hash
78
ph = PasswordHasher()
79
hash_string = ph.hash("password")
80
print(hash_string)
81
# $argon2id$v=19$m=65536,t=3,p=4$base64salt$base64hash
82

83
# Extract parameters from the hash
84
params = extract_parameters(hash_string)
85
print(f"Type: {params.type}")           # Type.ID
86
print(f"Memory: {params.memory_cost}")  # 65536
87
print(f"Time: {params.time_cost}")      # 3
88
print(f"Parallelism: {params.parallelism}")  # 4
89

90
# Create hasher with same parameters
91
ph_same = PasswordHasher.from_parameters(params)
92
```
93

94
### Platform-Aware Defaults
95

96
Get default parameters that are compatible with the current platform.
97

98
```python { .api }
99
def get_default_parameters() -> Parameters:
100
    """
101
    Create default parameters for current platform.
102
    
103
    Returns platform-compatible parameters based on RFC 9106 low-memory
104
    profile, with automatic adjustments for platform limitations
105
    (e.g., parallelism=1 in WebAssembly environments).
106
    
107
    Returns:
108
        Default Parameters object for current platform
109
    """
110
```
111

112
#### Usage Example
113

114
```python
115
from argon2.profiles import get_default_parameters
116
from argon2 import PasswordHasher
117

118
# Get platform-aware defaults
119
default_params = get_default_parameters()
120
print(f"Default parameters for this platform:")
121
print(f"  Memory: {default_params.memory_cost} KiB")
122
print(f"  Time: {default_params.time_cost}")
123
print(f"  Parallelism: {default_params.parallelism}")
124

125
# Use defaults
126
ph = PasswordHasher.from_parameters(default_params)
127
```
128

129
### Parameter Validation
130

131
Validate parameters against current platform capabilities.
132

133
```python { .api }
134
def validate_params_for_platform(params: Parameters) -> None:
135
    """
136
    Validate parameters against current platform limitations.
137
    
138
    Checks if the provided parameters are supported on the current
139
    platform and raises an exception if they are not.
140
    
141
    Args:
142
        params: Parameters to validate
143
    
144
    Raises:
145
        argon2.exceptions.UnsupportedParametersError: If parameters
146
            are not supported on current platform
147
    """
148
```
149

150
#### Usage Example
151

152
```python
153
from argon2 import Parameters, Type
154
from argon2._utils import validate_params_for_platform
155
from argon2.exceptions import UnsupportedParametersError
156

157
# Create parameters that might not work everywhere
158
params = Parameters(
159
    type=Type.ID,
160
    version=19,
161
    salt_len=16,
162
    hash_len=32,
163
    time_cost=3,
164
    memory_cost=65536,
165
    parallelism=8  # Might fail in WebAssembly
166
)
167

168
try:
169
    validate_params_for_platform(params)
170
    print("Parameters are supported on this platform")
171
except UnsupportedParametersError as e:
172
    print(f"Parameters not supported: {e}")
173
    # Fall back to platform defaults
174
    params = get_default_parameters()
175
```
176

177
## Predefined Profiles
178

179
Standard parameter configurations following security recommendations.
180

181
### RFC 9106 High Memory Profile
182

183
High security configuration for systems with abundant memory.
184

185
```python { .api }
186
RFC_9106_HIGH_MEMORY: Parameters
187
"""
188
First recommended option per RFC 9106.
189

190
Configuration:
191
- Type: Argon2id  
192
- Memory: 2 GiB (2,097,152 KiB)
193
- Time cost: 1 iteration
194
- Parallelism: 4 threads
195
- Hash length: 32 bytes
196
- Salt length: 16 bytes
197

198
Use when: System has ample memory and security is paramount.
199
"""
200
```
201

202
#### Usage Example
203

204
```python
205
from argon2.profiles import RFC_9106_HIGH_MEMORY
206
from argon2 import PasswordHasher
207

208
# Use high-security profile for sensitive applications
209
ph_secure = PasswordHasher.from_parameters(RFC_9106_HIGH_MEMORY)
210
admin_hash = ph_secure.hash("admin_password")
211

212
print(f"Using {RFC_9106_HIGH_MEMORY.memory_cost // 1024} MiB memory")
213
# Output: Using 2048 MiB memory
214
```
215

216
### RFC 9106 Low Memory Profile
217

218
Balanced security configuration for memory-constrained environments.
219

220
```python { .api }
221
RFC_9106_LOW_MEMORY: Parameters
222
"""
223
Second recommended option per RFC 9106.
224

225
Configuration:  
226
- Type: Argon2id
227
- Memory: 64 MiB (65,536 KiB)
228
- Time cost: 3 iterations
229
- Parallelism: 4 threads  
230
- Hash length: 32 bytes
231
- Salt length: 16 bytes
232

233
Use when: Memory is limited but good security is still needed.
234
This is the default profile used by argon2-cffi.
235
"""
236
```
237

238
#### Usage Example
239

240
```python
241
from argon2.profiles import RFC_9106_LOW_MEMORY
242
from argon2 import PasswordHasher
243

244
# Balanced security/performance (default for new PasswordHasher())
245
ph_balanced = PasswordHasher.from_parameters(RFC_9106_LOW_MEMORY)
246
user_hash = ph_balanced.hash("user_password")
247

248
# This is equivalent to:
249
ph_default = PasswordHasher()  # Uses RFC_9106_LOW_MEMORY internally
250
```
251

252
### Legacy Compatibility Profile
253

254
Historical parameter configuration for compatibility with older versions.
255

256
```python { .api }
257
PRE_21_2: Parameters
258
"""
259
Pre-21.2.0 defaults for legacy compatibility.
260

261
Configuration:
262
- Type: Argon2id
263
- Memory: 100 MiB (102,400 KiB)  
264
- Time cost: 2 iterations
265
- Parallelism: 8 threads
266
- Hash length: 16 bytes
267
- Salt length: 16 bytes
268

269
Use when: Need compatibility with argon2-cffi versions 18.2.0-21.1.0.
270
"""
271
```
272

273
#### Usage Example
274

275
```python
276
from argon2.profiles import PRE_21_2
277
from argon2 import PasswordHasher
278

279
# For systems upgrading from older argon2-cffi versions
280
ph_legacy = PasswordHasher.from_parameters(PRE_21_2)
281

282
# Check if existing hashes need upgrade
283
old_hash = "$argon2id$v=19$m=102400,t=2,p=8$..."
284
if ph_legacy.check_needs_rehash(old_hash):
285
    print("Hash uses legacy parameters")
286
```
287

288
### Testing Profile
289

290
Minimal parameters for testing and development only.
291

292
```python { .api }
293
CHEAPEST: Parameters
294
"""
295
Minimal parameters for testing purposes only.
296

297
Configuration:
298
- Type: Argon2id
299
- Memory: 8 KiB (very low)
300
- Time cost: 1 iteration  
301
- Parallelism: 1 thread
302
- Hash length: 4 bytes
303
- Salt length: 8 bytes
304

305
WARNING: Only use for testing! Provides minimal security.
306
"""
307
```
308

309
#### Usage Example
310

311
```python
312
from argon2.profiles import CHEAPEST
313
from argon2 import PasswordHasher
314

315
# Only for unit tests and development
316
if __name__ == "__main__":
317
    ph_test = PasswordHasher.from_parameters(CHEAPEST)
318
    test_hash = ph_test.hash("test_password")
319
    print("Fast hash for testing:", test_hash)
320
```
321

322
## Profile Selection Guide
323

324
### High Security Applications
325

326
For applications requiring maximum security (financial, healthcare, government):
327

328
```python
329
from argon2.profiles import RFC_9106_HIGH_MEMORY
330
from argon2 import PasswordHasher
331

332
# Maximum security - requires 2GB RAM per hash
333
ph = PasswordHasher.from_parameters(RFC_9106_HIGH_MEMORY)
334
```
335

336
### General Web Applications
337

338
For typical web applications balancing security and performance:
339

340
```python
341
from argon2 import PasswordHasher
342

343
# Uses RFC_9106_LOW_MEMORY by default (64MB RAM per hash)
344
ph = PasswordHasher()
345
```
346

347
### Resource-Constrained Environments
348

349
For embedded systems, mobile apps, or shared hosting:
350

351
```python
352
from argon2 import PasswordHasher, Parameters, Type
353

354
# Custom low-resource configuration
355
low_resource = Parameters(
356
    type=Type.ID,
357
    version=19,
358
    salt_len=16,
359
    hash_len=32,
360
    time_cost=2,        # Reduced iterations
361
    memory_cost=32768,  # 32 MiB memory
362
    parallelism=1       # Single thread
363
)
364

365
ph = PasswordHasher.from_parameters(low_resource)
366
```
367

368
### Platform-Specific Configurations
369

370
Automatically adapt to platform capabilities:
371

372
```python
373
from argon2.profiles import get_default_parameters
374
from argon2 import PasswordHasher
375

376
# Automatically adjusts for WebAssembly, mobile, etc.
377
platform_params = get_default_parameters()
378
ph = PasswordHasher.from_parameters(platform_params)
379

380
print(f"Using {platform_params.parallelism} threads")
381
# WebAssembly: 1 thread, other platforms: 4 threads
382
```
383

384
## Migration Between Profiles
385

386
Handle password rehashing when changing security parameters:
387

388
```python
389
from argon2 import PasswordHasher, extract_parameters
390
from argon2.profiles import RFC_9106_HIGH_MEMORY, RFC_9106_LOW_MEMORY
391

392
def upgrade_password_security(stored_hash: str, password: str) -> str:
393
    """Upgrade password hash to higher security parameters."""
394
    
395
    # Check current parameters
396
    current_params = extract_parameters(stored_hash)
397
    print(f"Current memory: {current_params.memory_cost} KiB")
398
    
399
    # Create new hasher with higher security
400
    new_ph = PasswordHasher.from_parameters(RFC_9106_HIGH_MEMORY)
401
    
402
    # Verify password with any parameters (auto-detects type)
403
    old_ph = PasswordHasher()
404
    old_ph.verify(stored_hash, password)  # Raises exception if wrong
405
    
406
    # Generate new hash with higher security
407
    new_hash = new_ph.hash(password)
408
    print(f"Upgraded to {RFC_9106_HIGH_MEMORY.memory_cost} KiB memory")
409
    
410
    return new_hash
411
```