0
# Argon2-CFFI
1

2
Python bindings for the Argon2 password hashing algorithm, winner of the Password Hashing Competition. Provides secure password hashing with industry-standard defaults, supporting all three Argon2 variants (Argon2i, Argon2d, Argon2id) with configurable memory usage, parallelism, and time costs.
3

4
## Package Information
5

6
- **Package Name**: argon2-cffi
7
- **Language**: Python
8
- **Installation**: `pip install argon2-cffi`
9
- **Requires**: Python ≥3.8
10

11
## Core Imports
12

13
```python
14
import argon2
15
```
16

17
Common usage pattern:
18

19
```python
20
from argon2 import PasswordHasher
21
```
22

23
Access to all public components:
24

25
```python
26
from argon2 import (
27
    PasswordHasher,
28
    Type,
29
    Parameters,
30
    extract_parameters,
31
    exceptions,
32
    low_level,
33
    profiles
34
)
35
```
36

37
## Basic Usage
38

39
```python
40
from argon2 import PasswordHasher
41

42
# Create a password hasher with secure defaults
43
ph = PasswordHasher()
44

45
# Hash a password
46
password = "supersecret"
47
hash = ph.hash(password)
48
print(hash)  # $argon2id$v=19$m=65536,t=3,p=4$...
49

50
# Verify a password
51
try:
52
    ph.verify(hash, password)
53
    print("Password is correct!")
54
except argon2.exceptions.VerifyMismatchError:
55
    print("Password is wrong!")
56

57
# Check if hash needs rehashing (due to changed parameters)
58
if ph.check_needs_rehash(hash):
59
    new_hash = ph.hash(password)
60
    # Update stored hash in database
61
```
62

63
## Architecture
64

65
Argon2-CFFI provides a layered architecture for different use cases:
66

67
- **High-level interface** (`PasswordHasher`): Simple, secure API with sensible defaults for typical password hashing needs
68
- **Low-level functions**: Direct bindings to Argon2 C library for advanced users requiring fine-grained control
69
- **Parameter management**: Configuration classes and predefined profiles for different security/performance trade-offs
70
- **Exception hierarchy**: Specific exceptions for different failure modes with clear error handling
71

72
The library automatically handles salt generation, constant-time verification to prevent timing attacks, and parameter validation for the current platform.
73

74
## Capabilities
75

76
### Password Hashing
77

78
High-level password hashing with the PasswordHasher class, providing secure defaults and convenient methods for common password operations including hashing, verification, and rehash detection.
79

80
```python { .api }
81
class PasswordHasher:
82
    def __init__(
83
        self,
84
        time_cost: int = DEFAULT_TIME_COST,
85
        memory_cost: int = DEFAULT_MEMORY_COST,
86
        parallelism: int = DEFAULT_PARALLELISM,
87
        hash_len: int = DEFAULT_HASH_LENGTH,
88
        salt_len: int = DEFAULT_RANDOM_SALT_LENGTH,
89
        encoding: str = "utf-8",
90
        type: Type = Type.ID,
91
    ): ...
92
    
93
    def hash(self, password: str | bytes, *, salt: bytes | None = None) -> str: ...
94
    def verify(self, hash: str | bytes, password: str | bytes) -> Literal[True]: ...
95
    def check_needs_rehash(self, hash: str | bytes) -> bool: ...
96
```
97

98
[Password Hashing](./password-hasher.md)
99

100
### Low-Level Functions
101

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

104
```python { .api }
105
def hash_secret(
106
    secret: bytes,
107
    salt: bytes, 
108
    time_cost: int,
109
    memory_cost: int,
110
    parallelism: int,
111
    hash_len: int,
112
    type: Type,
113
    version: int = ARGON2_VERSION,
114
) -> bytes: ...
115

116
def verify_secret(hash: bytes, secret: bytes, type: Type) -> Literal[True]: ...
117
```
118

119
[Low-Level Functions](./low-level.md)
120

121
### Exception Handling
122

123
Comprehensive exception hierarchy for different error conditions including verification failures, hashing errors, invalid parameters, and platform-specific limitations.
124

125
```python { .api }
126
class Argon2Error(Exception): ...
127
class VerificationError(Argon2Error): ...
128
class VerifyMismatchError(VerificationError): ...
129
class HashingError(Argon2Error): ...
130
class InvalidHashError(ValueError): ...
131
class UnsupportedParametersError(ValueError): ...
132
```
133

134
[Exception Handling](./exceptions.md)
135

136
### Parameter Profiles
137

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

140
```python { .api }
141
class Parameters:
142
    type: Type
143
    version: int
144
    salt_len: int
145
    hash_len: int
146
    time_cost: int
147
    memory_cost: int
148
    parallelism: int
149

150
def get_default_parameters() -> Parameters: ...
151
def extract_parameters(hash: str) -> Parameters: ...
152
```
153

154
[Parameter Profiles](./profiles.md)
155

156
### Legacy Functions
157

158
Deprecated functions maintained for backward compatibility with older code. Use PasswordHasher for new applications.
159

160
```python { .api }
161
def hash_password(
162
    password: bytes,
163
    salt: bytes | None = None,
164
    time_cost: int = DEFAULT_TIME_COST,
165
    memory_cost: int = DEFAULT_MEMORY_COST,
166
    parallelism: int = DEFAULT_PARALLELISM,
167
    hash_len: int = DEFAULT_HASH_LENGTH,
168
    type: Type = Type.I,
169
) -> bytes: ...
170

171
def hash_password_raw(
172
    password: bytes,
173
    salt: bytes | None = None,
174
    time_cost: int = DEFAULT_TIME_COST,
175
    memory_cost: int = DEFAULT_MEMORY_COST,
176
    parallelism: int = DEFAULT_PARALLELISM,
177
    hash_len: int = DEFAULT_HASH_LENGTH,
178
    type: Type = Type.I,
179
) -> bytes: ...
180

181
def verify_password(hash: bytes, password: bytes, type: Type = Type.I) -> Literal[True]: ...
182
```
183

184
## Types
185

186
```python { .api }
187
from typing import Literal
188

189
class Type(Enum):
190
    """Argon2 algorithm variants"""
191
    D = ...    # Argon2d (data-dependent)
192
    I = ...    # Argon2i (data-independent)
193
    ID = ...   # Argon2id (hybrid)
194

195
# Default configuration constants
196
DEFAULT_TIME_COST: int
197
DEFAULT_MEMORY_COST: int
198
DEFAULT_PARALLELISM: int
199
DEFAULT_HASH_LENGTH: int
200
DEFAULT_RANDOM_SALT_LENGTH: int
201
```