0
# Low-Level Functions
1

2
Direct access to Argon2 C library functions for advanced users who need fine-grained control over hashing parameters, raw hash outputs, or custom implementations.
3

4
**Warning**: This is a "Hazardous Materials" module. Only use if you're absolutely sure you know what you're doing, as this module contains many potential pitfalls.
5

6
## Capabilities
7

8
### Secret Hashing (Encoded)
9

10
Hash secrets and return encoded hash strings that contain all parameters and salt information.
11

12
```python { .api }
13
def hash_secret(
14
    secret: bytes,
15
    salt: bytes,
16
    time_cost: int,
17
    memory_cost: int,
18
    parallelism: int,
19
    hash_len: int,
20
    type: Type,
21
    version: int = ARGON2_VERSION,
22
) -> bytes:
23
    """
24
    Hash secret and return an encoded hash.
25
    
26
    An encoded hash can be directly passed into verify_secret() as it
27
    contains all parameters and the salt.
28
    
29
    Args:
30
        secret: Secret to hash (must be bytes)
31
        salt: Salt bytes (should be random and different for each secret)
32
        time_cost: Number of iterations
33
        memory_cost: Memory usage in kibibytes
34
        parallelism: Number of parallel threads
35
        hash_len: Length of hash output in bytes
36
        type: Argon2 variant (Type.I, Type.D, or Type.ID)
37
        version: Argon2 version number (default: latest)
38
    
39
    Returns:
40
        Encoded Argon2 hash as bytes
41
    
42
    Raises:
43
        argon2.exceptions.HashingError: If hashing fails
44
    """
45
```
46

47
#### Usage Example
48

49
```python
50
from argon2.low_level import hash_secret, Type
51
import os
52

53
# Prepare inputs
54
secret = b"my_secret_data"
55
salt = os.urandom(16)  # 16-byte random salt
56

57
# Hash with Argon2id
58
encoded_hash = hash_secret(
59
    secret=secret,
60
    salt=salt,
61
    time_cost=3,
62
    memory_cost=65536,  # 64 MiB
63
    parallelism=4,
64
    hash_len=32,
65
    type=Type.ID
66
)
67

68
print(encoded_hash.decode('ascii'))
69
# Output: $argon2id$v=19$m=65536,t=3,p=4$base64salt$base64hash
70
```
71

72
### Secret Hashing (Raw)
73

74
Hash secrets and return raw hash bytes without encoding or parameter information.
75

76
```python { .api }
77
def hash_secret_raw(
78
    secret: bytes,
79
    salt: bytes,
80
    time_cost: int,
81
    memory_cost: int,
82
    parallelism: int,
83
    hash_len: int,
84
    type: Type,
85
    version: int = ARGON2_VERSION,
86
) -> bytes:
87
    """
88
    Hash secret and return a raw hash.
89
    
90
    Returns only the hash bytes without encoding or parameter information.
91
    Takes the same parameters as hash_secret().
92
    
93
    Args:
94
        secret: Secret to hash (must be bytes)
95
        salt: Salt bytes
96
        time_cost: Number of iterations
97
        memory_cost: Memory usage in kibibytes
98
        parallelism: Number of parallel threads
99
        hash_len: Length of hash output in bytes
100
        type: Argon2 variant
101
        version: Argon2 version number
102
    
103
    Returns:
104
        Raw hash bytes (length = hash_len)
105
    
106
    Raises:
107
        argon2.exceptions.HashingError: If hashing fails
108
    """
109
```
110

111
#### Usage Example
112

113
```python
114
from argon2.low_level import hash_secret_raw, Type
115
import os
116

117
# Get raw hash bytes for custom processing
118
raw_hash = hash_secret_raw(
119
    secret=b"my_secret",
120
    salt=os.urandom(16),
121
    time_cost=2,
122
    memory_cost=102400,  # 100 MiB
123
    parallelism=8,
124
    hash_len=64,        # 64-byte output
125
    type=Type.ID
126
)
127

128
print(f"Raw hash length: {len(raw_hash)} bytes")
129
print(f"Raw hash (hex): {raw_hash.hex()}")
130
```
131

132
### Secret Verification
133

134
Verify secrets against encoded hashes with specified Argon2 type.
135

136
```python { .api }
137
def verify_secret(hash: bytes, secret: bytes, type: Type) -> Literal[True]:
138
    """
139
    Verify whether secret is correct for hash of specified type.
140
    
141
    Args:
142
        hash: Encoded Argon2 hash (from hash_secret())
143
        secret: Secret to verify (must be bytes)
144
        type: Argon2 type used for the hash
145
    
146
    Returns:
147
        True if secret matches hash
148
    
149
    Raises:
150
        argon2.exceptions.VerifyMismatchError: Secret doesn't match hash
151
        argon2.exceptions.VerificationError: Verification failed for other reasons
152
    """
153
```
154

155
#### Usage Example
156

157
```python
158
from argon2.low_level import hash_secret, verify_secret, Type
159

160
# Hash a secret
161
secret = b"my_secret_password"
162
salt = os.urandom(16)
163
hash_bytes = hash_secret(
164
    secret, salt, 3, 65536, 4, 32, Type.ID
165
)
166

167
# Later, verify the secret
168
try:
169
    result = verify_secret(hash_bytes, secret, Type.ID)
170
    print("Verification successful!")
171
except argon2.exceptions.VerifyMismatchError:
172
    print("Secret doesn't match!")
173
```
174

175
### Direct C Library Access
176

177
Direct binding to the Argon2 C library's core function for maximum control.
178

179
```python { .api }
180
def core(context: Any, type: int) -> int:
181
    """
182
    Direct binding to the argon2_ctx function.
183
    
184
    WARNING: This is strictly advanced functionality working on raw C data
185
    structures. All parameter validation and memory management is your
186
    responsibility. The context structure can change with any release.
187
    
188
    Args:
189
        context: CFFI Argon2 context object (struct Argon2_Context)
190
        type: Argon2 type value (use Type enum's .value attribute)
191
    
192
    Returns:
193
        Argon2 error code (0 = success)
194
    """
195
```
196

197
### Error Code Conversion
198

199
Convert Argon2 C library error codes to human-readable strings.
200

201
```python { .api }
202
def error_to_str(error: int) -> str:
203
    """
204
    Convert an Argon2 error code into a native string.
205
    
206
    Args:
207
        error: Argon2 error code (from core() function)
208
    
209
    Returns:
210
        Human-readable error description
211
    """
212
```
213

214
#### Usage Example
215

216
```python
217
from argon2.low_level import core, error_to_str
218

219
# Advanced usage with direct C library access
220
try:
221
    # ... setup context object ...
222
    error_code = core(context, type_value)
223
    if error_code != 0:  # ARGON2_OK = 0
224
        error_msg = error_to_str(error_code)
225
        print(f"Argon2 error: {error_msg}")
226
except Exception as e:
227
    print(f"Failed: {e}")
228
```
229

230
## Constants
231

232
```python { .api }
233
ARGON2_VERSION: int
234
"""
235
The latest version of the Argon2 algorithm that is supported
236
and used by default.
237
"""
238

239
ffi: Any
240
"""
241
Foreign function interface (CFFI) object for direct C library access.
242
Provides access to C data structures and functions.
243
"""
244
```
245

246
## Types
247

248
```python { .api }
249
class Type(Enum):
250
    """
251
    Enum of Argon2 variants.
252
    
253
    D: Argon2d - Uses data-dependent memory access patterns.
254
       Faster but vulnerable to side-channel attacks.
255
       
256
    I: Argon2i - Uses data-independent memory access patterns.
257
       Slower but resistant to side-channel attacks.
258
       
259
    ID: Argon2id - Hybrid approach using both patterns.
260
        Recommended for most use cases.
261
    """
262
    D = ...   # Argon2d (data-dependent)
263
    I = ...   # Argon2i (data-independent)  
264
    ID = ...  # Argon2id (hybrid, recommended)
265
```
266

267
## Platform Considerations
268

269
### WebAssembly Limitations
270

271
When running in WebAssembly environments (detected automatically), parallelism must be set to 1:
272

273
```python
274
# This will work in WebAssembly
275
hash_secret(secret, salt, 3, 65536, 1, 32, Type.ID)  # parallelism=1
276

277
# This will raise UnsupportedParametersError in WebAssembly
278
hash_secret(secret, salt, 3, 65536, 4, 32, Type.ID)  # parallelism=4
279
```
280

281
### Memory Considerations
282

283
Memory cost is specified in kibibytes (1024 bytes). Large values may cause issues on memory-constrained systems:
284

285
```python
286
# Conservative memory usage (64 MiB)
287
hash_secret(secret, salt, 3, 65536, 4, 32, Type.ID)
288

289
# High memory usage (2 GiB) - ensure system has sufficient RAM
290
hash_secret(secret, salt, 1, 2097152, 4, 32, Type.ID)
291
```