0
# HTTP-01 Challenge Handler
1
2
The NginxHttp01 class implements ACME HTTP-01 challenge authentication for nginx. It handles the creation of temporary challenge server blocks, configuration of challenge responses, and cleanup after domain validation.
3
4
## Capabilities
5
6
### Challenge Handler Initialization
7
8
Initialize the HTTP-01 challenge handler with nginx configurator integration.
9
10
```python { .api }
11
class NginxHttp01:
12
"""HTTP-01 authenticator for nginx.
13
14
Args:
15
configurator: NginxConfigurator object for nginx operations
16
17
Attributes:
18
configurator: NginxConfigurator - Parent configurator instance
19
challenge_conf: str - Path to challenge configuration file
20
achalls: list - Annotated challenges to perform
21
indices: list - Challenge indices for response ordering
22
"""
23
24
def __init__(self, configurator: "NginxConfigurator") -> None:
25
"""Initialize HTTP-01 challenge handler."""
26
```
27
28
### Challenge Performance
29
30
Perform HTTP-01 challenges by configuring nginx to serve challenge responses.
31
32
```python { .api }
33
def perform(self) -> list[KeyAuthorizationChallengeResponse]:
34
"""Perform HTTP-01 challenges on nginx.
35
36
Creates challenge server blocks, configures nginx to serve challenge
37
responses, and restarts nginx to activate the configuration.
38
39
Returns:
40
List of KeyAuthorizationChallengeResponse objects
41
42
Raises:
43
errors.MisconfigurationError: Unable to find suitable HTTP block
44
"""
45
```
46
47
### Challenge Registration
48
49
Add challenges to be performed by the handler.
50
51
```python { .api }
52
def add_chall(self, achall: KeyAuthorizationAnnotatedChallenge, index: int) -> None:
53
"""Add challenge to be performed.
54
55
Args:
56
achall: Annotated challenge containing challenge details
57
index: Index position for response ordering
58
"""
59
```
60
61
## Internal Methods
62
63
```python { .api }
64
def _mod_config(self) -> None:
65
"""Modify nginx config to include challenge blocks.
66
67
Adds server_names_hash_bucket_size directive and includes challenge
68
configuration file in the main nginx configuration.
69
70
Raises:
71
errors.MisconfigurationError: Unable to find HTTP block for challenges
72
"""
73
74
def _make_or_mod_server_block(self, achall: KeyAuthorizationAnnotatedChallenge) -> Optional[list[Any]]:
75
"""Create or modify server block for challenge.
76
77
Args:
78
achall: Annotated challenge to create server block for
79
80
Returns:
81
Server block configuration or None if not needed
82
"""
83
84
def _default_listen_addresses(self) -> list[Addr]:
85
"""Find addresses for challenge block to listen on.
86
87
Returns:
88
List of Addr objects for challenge server block
89
"""
90
91
def _get_http_block(self) -> Optional[UnspacedList]:
92
"""Find the HTTP block in nginx configuration.
93
94
Returns:
95
HTTP block as UnspacedList or None if not found
96
"""
97
```
98
99
## Usage Examples
100
101
### Basic Challenge Handling
102
103
```python
104
from certbot_nginx._internal.configurator import NginxConfigurator
105
from certbot_nginx._internal.http_01 import NginxHttp01
106
from certbot.achallenges import KeyAuthorizationAnnotatedChallenge
107
108
# Initialize configurator and HTTP-01 handler
109
configurator = NginxConfigurator(config, name='nginx')
110
configurator.prepare()
111
112
http_doer = NginxHttp01(configurator)
113
114
# Add challenges
115
for i, achall in enumerate(challenges):
116
http_doer.add_chall(achall, i)
117
118
# Perform challenges
119
responses = http_doer.perform()
120
121
# Process responses
122
for response in responses:
123
print(f"Challenge response: {response}")
124
```
125
126
### Challenge Configuration Details
127
128
The HTTP-01 challenge handler automatically:
129
130
1. **Configures server_names_hash_bucket_size**: Sets appropriate hash bucket size for handling multiple server names
131
2. **Creates challenge server blocks**: Generates temporary server blocks to serve challenge responses
132
3. **Manages challenge file paths**: Handles the `.well-known/acme-challenge/` URL path routing
133
4. **Coordinates with configurator**: Integrates with the main nginx configurator for restart and cleanup operations
134
135
### Challenge Server Block Structure
136
137
The challenge handler creates server blocks similar to:
138
139
```nginx
140
server {
141
listen 80;
142
server_name example.com;
143
144
location ~ "^/\.well-known/acme-challenge/([-_A-Za-z0-9]+)$" {
145
default_type text/plain;
146
return 200 "challenge-response-content";
147
}
148
}
149
```
150
151
### Error Handling
152
153
```python
154
from certbot import errors
155
156
try:
157
responses = http_doer.perform()
158
except errors.MisconfigurationError as e:
159
print(f"Configuration error: {e}")
160
# Handle configuration issues
161
except Exception as e:
162
print(f"Challenge failed: {e}")
163
# Handle other challenge failures
164
```
165
166
## Integration with Configurator
167
168
The NginxHttp01 class works closely with the main NginxConfigurator:
169
170
- **Challenge file management**: Creates temporary challenge configuration files
171
- **Server restart coordination**: Uses configurator's restart functionality
172
- **Configuration cleanup**: Integrates with configurator's checkpoint and recovery system
173
- **Address resolution**: Uses configurator's address and virtual host detection
174
175
## Challenge Flow
176
177
1. **Challenge Registration**: Challenges are added with `add_chall()`
178
2. **Configuration Generation**: `perform()` generates challenge server blocks
179
3. **Nginx Configuration**: Challenge config is included in main nginx configuration
180
4. **Server Restart**: Nginx is restarted to activate challenge configuration
181
5. **Response Generation**: Challenge responses are returned for ACME protocol
182
6. **Cleanup**: Temporary configuration is cleaned up after validation
183
184
The challenge handler ensures that nginx can properly serve ACME challenge responses while maintaining existing site functionality.