tessl/pypi-certbot-nginx

Nginx plugin for Certbot that enables automated SSL/TLS certificate management and deployment for Nginx web servers.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

HTTP-01 Challenge Handler

Name: tessl/pypi-certbot-nginx
Author: tessl

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.

Capabilities

Challenge Handler Initialization

Initialize the HTTP-01 challenge handler with nginx configurator integration.

class NginxHttp01:
    """HTTP-01 authenticator for nginx.
    
    Args:
        configurator: NginxConfigurator object for nginx operations
        
    Attributes:
        configurator: NginxConfigurator - Parent configurator instance
        challenge_conf: str - Path to challenge configuration file
        achalls: list - Annotated challenges to perform
        indices: list - Challenge indices for response ordering
    """
    
    def __init__(self, configurator: "NginxConfigurator") -> None:
        """Initialize HTTP-01 challenge handler."""

Challenge Performance

Perform HTTP-01 challenges by configuring nginx to serve challenge responses.

def perform(self) -> list[KeyAuthorizationChallengeResponse]:
    """Perform HTTP-01 challenges on nginx.
    
    Creates challenge server blocks, configures nginx to serve challenge
    responses, and restarts nginx to activate the configuration.
    
    Returns:
        List of KeyAuthorizationChallengeResponse objects
        
    Raises:
        errors.MisconfigurationError: Unable to find suitable HTTP block
    """

Challenge Registration

Add challenges to be performed by the handler.

def add_chall(self, achall: KeyAuthorizationAnnotatedChallenge, index: int) -> None:
    """Add challenge to be performed.
    
    Args:
        achall: Annotated challenge containing challenge details
        index: Index position for response ordering
    """

Internal Methods

def _mod_config(self) -> None:
    """Modify nginx config to include challenge blocks.
    
    Adds server_names_hash_bucket_size directive and includes challenge
    configuration file in the main nginx configuration.
    
    Raises:
        errors.MisconfigurationError: Unable to find HTTP block for challenges
    """

def _make_or_mod_server_block(self, achall: KeyAuthorizationAnnotatedChallenge) -> Optional[list[Any]]:
    """Create or modify server block for challenge.
    
    Args:
        achall: Annotated challenge to create server block for
        
    Returns:
        Server block configuration or None if not needed
    """

def _default_listen_addresses(self) -> list[Addr]:
    """Find addresses for challenge block to listen on.
    
    Returns:
        List of Addr objects for challenge server block
    """

def _get_http_block(self) -> Optional[UnspacedList]:
    """Find the HTTP block in nginx configuration.
    
    Returns:
        HTTP block as UnspacedList or None if not found
    """

Usage Examples

Basic Challenge Handling

from certbot_nginx._internal.configurator import NginxConfigurator
from certbot_nginx._internal.http_01 import NginxHttp01
from certbot.achallenges import KeyAuthorizationAnnotatedChallenge

# Initialize configurator and HTTP-01 handler
configurator = NginxConfigurator(config, name='nginx')
configurator.prepare()

http_doer = NginxHttp01(configurator)

# Add challenges
for i, achall in enumerate(challenges):
    http_doer.add_chall(achall, i)

# Perform challenges
responses = http_doer.perform()

# Process responses
for response in responses:
    print(f"Challenge response: {response}")

Challenge Configuration Details

The HTTP-01 challenge handler automatically:

Configures server_names_hash_bucket_size: Sets appropriate hash bucket size for handling multiple server names
Creates challenge server blocks: Generates temporary server blocks to serve challenge responses
Manages challenge file paths: Handles the .well-known/acme-challenge/ URL path routing
Coordinates with configurator: Integrates with the main nginx configurator for restart and cleanup operations

Challenge Server Block Structure

The challenge handler creates server blocks similar to:

server {
    listen 80;
    server_name example.com;
    
    location ~ "^/\.well-known/acme-challenge/([-_A-Za-z0-9]+)$" {
        default_type text/plain;
        return 200 "challenge-response-content";
    }
}

Error Handling

from certbot import errors

try:
    responses = http_doer.perform()
except errors.MisconfigurationError as e:
    print(f"Configuration error: {e}")
    # Handle configuration issues
except Exception as e:
    print(f"Challenge failed: {e}")
    # Handle other challenge failures

Integration with Configurator

The NginxHttp01 class works closely with the main NginxConfigurator:

Challenge file management: Creates temporary challenge configuration files
Server restart coordination: Uses configurator's restart functionality
Configuration cleanup: Integrates with configurator's checkpoint and recovery system
Address resolution: Uses configurator's address and virtual host detection

Challenge Flow

Challenge Registration: Challenges are added with add_chall()
Configuration Generation: perform() generates challenge server blocks
Nginx Configuration: Challenge config is included in main nginx configuration
Server Restart: Nginx is restarted to activate challenge configuration
Response Generation: Challenge responses are returned for ACME protocol
Cleanup: Temporary configuration is cleaned up after validation