tessl/pypi-certbot

ACME client that automates the process of obtaining, installing, and renewing SSL/TLS certificates from Let's Encrypt certificate authority.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Certbot

Name: tessl/pypi-certbot
Author: tessl

Certbot is an ACME (Automatic Certificate Management Environment) client that automates the process of obtaining, installing, and renewing SSL/TLS certificates from Let's Encrypt and other ACME-compliant certificate authorities. It provides a command-line interface for securely requesting and deploying certificates on web servers, supporting various web server configurations including Apache and Nginx through plugins.

Package Information

Package Name: certbot
Language: Python
Installation: pip install certbot
Python Version: >=3.10

Core Imports

import certbot

For main entry point:

from certbot.main import main

For plugin development:

from certbot import interfaces
from certbot.plugins.common import Plugin, Installer

For error handling:

from certbot import errors

For utilities and types:

from certbot import util
from certbot import crypto_util
from certbot.display import ops

Basic Usage

Command-line Usage

Certbot is primarily used as a command-line tool:

from certbot.main import main

# Run certbot with command-line arguments
result = main(['certonly', '--standalone', '-d', 'example.com'])

# Run with default sys.argv arguments
result = main()

Plugin Development

from certbot import interfaces
from certbot.plugins.common import Plugin
from certbot import configuration

class MyAuthenticator(Plugin, interfaces.Authenticator):
    """Custom authenticator plugin."""
    
    description = "Custom authentication plugin"
    name = "my-auth"
    
    def __init__(self, config: configuration.NamespaceConfig, name: str):
        super().__init__(config, name)
    
    def prepare(self):
        """Prepare the plugin for use."""
        pass
    
    def perform(self, achalls):
        """Perform the authentication challenges."""
        responses = []
        for achall in achalls:
            # Implement challenge response logic
            response = achall.response_and_validation(self.account_key)
            responses.append(response)
        return responses
    
    def cleanup(self, achalls):
        """Clean up after authentication."""
        pass

Architecture

Certbot follows a plugin-based architecture that enables extensibility:

Main Entry Point: certbot.main.main() provides the primary CLI interface
Plugin System: Authenticator and Installer plugins handle different challenge types and web server configurations
Configuration Management: NamespaceConfig handles command-line arguments and configuration files
Error Handling: Comprehensive exception hierarchy for different failure modes
Utility Functions: Cryptographic operations, file handling, and user interaction utilities

The plugin system allows extending Certbot with custom authentication methods (DNS providers, custom challenge types) and installation methods (additional web servers, custom deployment logic).

Capabilities

Main Entry Point & Configuration

Core functionality for running Certbot and managing configuration, including the main CLI entry point, configuration handling, and argument processing.

def main(cli_args: Optional[list[str]] = None) -> Optional[Union[str, int]]:
    """
    Run Certbot with optional command line arguments.
    
    Args:
        cli_args: Command line arguments, defaults to sys.argv[1:]
    
    Returns:
        Exit status code or None
    """

class NamespaceConfig:
    """Configuration wrapper around argparse.Namespace."""
    def __init__(self, namespace: argparse.Namespace): ...
    def set_argument_sources(self, argument_sources: dict[str, ArgumentSource]): ...

Main Entry Point & Configuration

Plugin Development

Plugin interfaces and base classes for developing custom authenticator and installer plugins to extend Certbot's functionality with new challenge types and web server support.

class Plugin(metaclass=ABCMeta):
    """Base plugin interface."""
    description: str
    name: str
    def __init__(self, config: Optional[NamespaceConfig], name: str): ...
    def prepare(self): ...
    def more_info(self) -> str: ...

class Authenticator(Plugin):
    """Interface for challenge authenticator plugins."""
    def get_chall_pref(self, domain: str) -> Iterable[type[Challenge]]: ...
    def perform(self, achalls: list[AnnotatedChallenge]) -> list[ChallengeResponse]: ...
    def cleanup(self, achalls: list[AnnotatedChallenge]): ...

class Installer(Plugin):
    """Interface for certificate installer plugins."""
    def deploy_cert(self, domain: str, cert_path: str, key_path: str, chain_path: str, fullchain_path: str): ...
    def enhance(self, domain: str, enhancement: str, options: Optional[Union[list[str], str]]): ...

Plugin Development

Cryptographic Utilities

Certificate and key generation, management, and validation functions for handling SSL/TLS certificates, private keys, and certificate signing requests.

def generate_key(key_size: int, key_dir: Optional[str], key_type: str = "rsa", 
                elliptic_curve: str = "secp256r1", keyname: str = "key-certbot.pem", 
                strict_permissions: bool = True) -> util.Key: ...

def generate_csr(privkey: util.Key, names: Union[list[str], set[str]], 
                path: Optional[str], must_staple: bool = False,
                strict_permissions: bool = True) -> util.CSR: ...

def notAfter(cert_path: str) -> datetime: ...
def notBefore(cert_path: str) -> datetime: ...

Cryptographic Utilities

Error Handling & Exceptions

Comprehensive exception hierarchy for handling different types of errors that can occur during certificate operations, plugin usage, and configuration management.

class Error(Exception):
    """Generic Certbot client error."""

class AuthorizationError(Error):
    """Authorization error."""

class PluginError(Error):
    """Certbot Plugin error."""

class AccountStorageError(Error):
    """Generic account storage error."""

Error Handling & Exceptions

Display & User Interface

User interaction utilities for prompting, displaying information, and managing user interface elements in command-line and interactive environments.

def get_email(invalid: bool = False, **kwargs) -> str:
    """Prompt for valid email address."""

def choose_account(accounts: list[Account]) -> Optional[Account]:
    """Choose an account from available accounts."""

def choose_values(values: list[str], question: Optional[str] = None) -> list[str]:
    """Display screen to let user pick one or multiple values."""

Display & User Interface

Utility Functions

General utility functions for file operations, system information, validation, and process management used throughout Certbot operations.

def make_or_verify_dir(directory: str, mode: int, strict: bool = True) -> None: ...
def safe_open(path: str, mode: str = 'w', chmod: int = 0o644) -> IO: ...
def unique_file(path: str, chmod: int = 0o644, mode: str = 'w') -> tuple[IO, str]: ...
def get_os_info() -> tuple[str, str]: ...
def run_script(params: list[str]) -> tuple[str, str]: ...
def safe_email(email: str) -> bool: ...
def enforce_le_validity(domain: str) -> str: ...

Utility Functions

Types

class Key(NamedTuple):
    """Container for an optional file path and contents for a PEM-formatted private key."""
    file: Optional[str]
    pem: bytes

class CSR(NamedTuple):
    """Container for an optional file path and contents for a PEM or DER-formatted CSR."""
    file: Optional[str]
    data: bytes
    form: str

class ArgumentSource(enum.Enum):
    """Enum for describing where a configuration argument was set."""
    COMMAND_LINE = enum.auto()
    CONFIG_FILE = enum.auto()
    DEFAULT = enum.auto()
    ENV_VAR = enum.auto()
    RUNTIME = enum.auto()

class AnnotatedChallenge:
    """Client annotated challenge wrapper."""
    challb: Any  # ChallengeBody from acme library

Install with Tessl CLI