0
# Platform Constants and Configuration
1

2
Platform-specific constants and configuration values used throughout the certbot-nginx plugin. These values handle cross-platform compatibility and provide default configuration settings.
3

4
## Capabilities
5

6
### Platform-Specific Server Roots
7

8
Default nginx server root directories for different operating systems.
9

10
```python { .api }
11
# Platform-specific server root paths
12
FREEBSD_DARWIN_SERVER_ROOT: str = "/usr/local/etc/nginx"
13
LINUX_SERVER_ROOT: str = "/etc/nginx"
14
PKGSRC_SERVER_ROOT: str = "/usr/pkg/etc/nginx"
15
```
16

17
### CLI Configuration Defaults
18

19
Default values for command-line interface options.
20

21
```python { .api }
22
CLI_DEFAULTS: dict[str, Any] = {
23
    "server_root": str,      # Platform-dependent server root path
24
    "ctl": "nginx",         # Default nginx binary name
25
    "sleep_seconds": 1      # Default sleep time after configuration changes
26
}
27
```
28

29
### SSL Configuration Constants
30

31
SSL-related configuration file names and paths.
32

33
```python { .api }
34
MOD_SSL_CONF_DEST: str = "options-ssl-nginx.conf"
35
UPDATED_MOD_SSL_CONF_DIGEST: str = ".updated-options-ssl-nginx-conf-digest.txt"
36
```
37

38
### Security Headers Configuration
39

40
Default security header configurations for enhancements.
41

42
```python { .api }
43
HSTS_ARGS: list[str] = ['"max-age=31536000"', ' ', 'always']
44
HEADER_ARGS: dict[str, list[str]] = {'Strict-Transport-Security': HSTS_ARGS}
45
```
46

47
### SSL Configuration Version Control
48

49
Hash values for tracking SSL configuration file versions across nginx and OpenSSL updates.
50

51
```python { .api }
52
ALL_SSL_OPTIONS_HASHES: list[str] = [
53
    # List of SHA256 hashes for different SSL configuration versions
54
    # Used to detect when SSL configuration needs updating
55
]
56
```
57

58
### Platform Detection Function
59

60
Utility function for retrieving platform-specific configuration values.
61

62
```python { .api }
63
def os_constant(key: str) -> Any:
64
    """Get platform-specific constant value.
65
    
66
    Retrieves configuration constants based on the current operating system,
67
    with fallback values for unsupported platforms.
68
    
69
    Args:
70
        key: Constant key to retrieve
71
        
72
    Returns:
73
        Platform-appropriate constant value
74
        
75
    Raises:
76
        KeyError: If the constant key is not recognized
77
    """
78
```
79

80
## Usage Examples
81

82
### Getting Platform-Specific Paths
83

84
```python
85
from certbot_nginx._internal import constants
86

87
# Get the default server root for current platform
88
server_root = constants.os_constant("server_root")
89
print(f"Nginx server root: {server_root}")
90

91
# Access CLI defaults
92
nginx_ctl = constants.CLI_DEFAULTS["ctl"]
93
sleep_time = constants.CLI_DEFAULTS["sleep_seconds"]
94
```
95

96
### Working with SSL Configuration
97

98
```python
99
# SSL configuration file paths
100
ssl_conf_file = constants.MOD_SSL_CONF_DEST
101
ssl_digest_file = constants.UPDATED_MOD_SSL_CONF_DIGEST
102

103
print(f"SSL config will be written to: {ssl_conf_file}")
104
print(f"SSL config digest: {ssl_digest_file}")
105

106
# Check if current SSL config hash is known
107
current_hash = "sha256_hash_of_current_config"
108
is_known_version = current_hash in constants.ALL_SSL_OPTIONS_HASHES
109
```
110

111
### Security Headers Setup
112

113
```python
114
# Get HSTS header configuration
115
hsts_config = constants.HEADER_ARGS['Strict-Transport-Security']
116
hsts_value = ''.join(hsts_config)
117
print(f"HSTS header value: {hsts_value}")
118

119
# Apply to nginx configuration
120
hsts_directive = ['add_header', 'Strict-Transport-Security'] + hsts_config
121
```
122

123
## Platform Compatibility
124

125
The constants module handles differences between:
126

127
- **Linux systems**: Uses `/etc/nginx` as default server root
128
- **FreeBSD/macOS**: Uses `/usr/local/etc/nginx` as default server root  
129
- **pkgsrc systems**: Uses `/usr/pkg/etc/nginx` as default server root
130

131
This ensures the plugin works correctly across different nginx installation methods and operating systems.
132

133
## SSL Configuration Management
134

135
The SSL configuration hash tracking system ensures:
136

137
1. **Version Detection**: Identifies when SSL configurations need updates
138
2. **Backward Compatibility**: Maintains support for older SSL configurations
139
3. **Security Updates**: Enables automatic security enhancements over time
140
4. **Conflict Resolution**: Prevents overwriting user-customized SSL settings
141

142
The hash-based system allows the plugin to detect when the SSL configuration file has been modified and decide whether to update it with newer security settings.