0
# Certbot
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: certbot
7
- **Language**: Python
8
- **Installation**: `pip install certbot`
9
- **Python Version**: >=3.10
10

11
## Core Imports
12

13
```python
14
import certbot
15
```
16

17
For main entry point:
18

19
```python
20
from certbot.main import main
21
```
22

23
For plugin development:
24

25
```python
26
from certbot import interfaces
27
from certbot.plugins.common import Plugin, Installer
28
```
29

30
For error handling:
31

32
```python
33
from certbot import errors
34
```
35

36
For utilities and types:
37

38
```python
39
from certbot import util
40
from certbot import crypto_util
41
from certbot.display import ops
42
```
43

44
## Basic Usage
45

46
### Command-line Usage
47

48
Certbot is primarily used as a command-line tool:
49

50
```python
51
from certbot.main import main
52

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

56
# Run with default sys.argv arguments
57
result = main()
58
```
59

60
### Plugin Development
61

62
```python
63
from certbot import interfaces
64
from certbot.plugins.common import Plugin
65
from certbot import configuration
66

67
class MyAuthenticator(Plugin, interfaces.Authenticator):
68
    """Custom authenticator plugin."""
69
    
70
    description = "Custom authentication plugin"
71
    name = "my-auth"
72
    
73
    def __init__(self, config: configuration.NamespaceConfig, name: str):
74
        super().__init__(config, name)
75
    
76
    def prepare(self):
77
        """Prepare the plugin for use."""
78
        pass
79
    
80
    def perform(self, achalls):
81
        """Perform the authentication challenges."""
82
        responses = []
83
        for achall in achalls:
84
            # Implement challenge response logic
85
            response = achall.response_and_validation(self.account_key)
86
            responses.append(response)
87
        return responses
88
    
89
    def cleanup(self, achalls):
90
        """Clean up after authentication."""
91
        pass
92
```
93

94
## Architecture
95

96
Certbot follows a plugin-based architecture that enables extensibility:
97

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

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

106
## Capabilities
107

108
### Main Entry Point & Configuration
109

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

112
```python { .api }
113
def main(cli_args: Optional[list[str]] = None) -> Optional[Union[str, int]]:
114
    """
115
    Run Certbot with optional command line arguments.
116
    
117
    Args:
118
        cli_args: Command line arguments, defaults to sys.argv[1:]
119
    
120
    Returns:
121
        Exit status code or None
122
    """
123

124
class NamespaceConfig:
125
    """Configuration wrapper around argparse.Namespace."""
126
    def __init__(self, namespace: argparse.Namespace): ...
127
    def set_argument_sources(self, argument_sources: dict[str, ArgumentSource]): ...
128
```
129

130
[Main Entry Point & Configuration](./main-config.md)
131

132
### Plugin Development
133

134
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.
135

136
```python { .api }
137
class Plugin(metaclass=ABCMeta):
138
    """Base plugin interface."""
139
    description: str
140
    name: str
141
    def __init__(self, config: Optional[NamespaceConfig], name: str): ...
142
    def prepare(self): ...
143
    def more_info(self) -> str: ...
144

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

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

157
[Plugin Development](./plugin-development.md)
158

159
### Cryptographic Utilities
160

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

163
```python { .api }
164
def generate_key(key_size: int, key_dir: Optional[str], key_type: str = "rsa", 
165
                elliptic_curve: str = "secp256r1", keyname: str = "key-certbot.pem", 
166
                strict_permissions: bool = True) -> util.Key: ...
167

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

172
def notAfter(cert_path: str) -> datetime: ...
173
def notBefore(cert_path: str) -> datetime: ...
174
```
175

176
[Cryptographic Utilities](./crypto-utilities.md)
177

178
### Error Handling & Exceptions
179

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

182
```python { .api }
183
class Error(Exception):
184
    """Generic Certbot client error."""
185

186
class AuthorizationError(Error):
187
    """Authorization error."""
188

189
class PluginError(Error):
190
    """Certbot Plugin error."""
191

192
class AccountStorageError(Error):
193
    """Generic account storage error."""
194
```
195

196
[Error Handling & Exceptions](./error-handling.md)
197

198
### Display & User Interface
199

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

202
```python { .api }
203
def get_email(invalid: bool = False, **kwargs) -> str:
204
    """Prompt for valid email address."""
205

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

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

213
[Display & User Interface](./display-ui.md)
214

215
### Utility Functions
216

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

219
```python { .api }
220
def make_or_verify_dir(directory: str, mode: int, strict: bool = True) -> None: ...
221
def safe_open(path: str, mode: str = 'w', chmod: int = 0o644) -> IO: ...
222
def unique_file(path: str, chmod: int = 0o644, mode: str = 'w') -> tuple[IO, str]: ...
223
def get_os_info() -> tuple[str, str]: ...
224
def run_script(params: list[str]) -> tuple[str, str]: ...
225
def safe_email(email: str) -> bool: ...
226
def enforce_le_validity(domain: str) -> str: ...
227
```
228

229
[Utility Functions](./utility-functions.md)
230

231
## Types
232

233
```python { .api }
234
class Key(NamedTuple):
235
    """Container for an optional file path and contents for a PEM-formatted private key."""
236
    file: Optional[str]
237
    pem: bytes
238

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

245
class ArgumentSource(enum.Enum):
246
    """Enum for describing where a configuration argument was set."""
247
    COMMAND_LINE = enum.auto()
248
    CONFIG_FILE = enum.auto()
249
    DEFAULT = enum.auto()
250
    ENV_VAR = enum.auto()
251
    RUNTIME = enum.auto()
252

253
class AnnotatedChallenge:
254
    """Client annotated challenge wrapper."""
255
    challb: Any  # ChallengeBody from acme library
256
```