0
# Certifi
1

2
Python package for providing Mozilla's carefully curated collection of Root Certificates for validating the trustworthiness of SSL certificates while verifying the identity of TLS hosts. It has been extracted from the Requests project and serves as a reliable and highly portable root of trust to Python deployments.
3

4
## Package Information
5

6
- **Package Name**: certifi
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install certifi`
10

11
## Core Imports
12

13
```python
14
import certifi
15
```
16

17
For accessing specific functions:
18

19
```python
20
from certifi import where, contents
21
```
22

23
## Basic Usage
24

25
```python
26
import certifi
27

28
# Get the path to the CA bundle file
29
ca_bundle_path = certifi.where()
30
print(ca_bundle_path)
31
# Output: /path/to/site-packages/certifi/cacert.pem
32

33
# Get the contents of the CA bundle
34
ca_bundle_contents = certifi.contents()
35
print(ca_bundle_contents[:100])  # First 100 characters
36
# Output: -----BEGIN CERTIFICATE-----
37
# MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw...
38
```
39

40
Command line usage:
41

42
```bash
43
# Get the path to the CA bundle
44
python -m certifi
45
# Output: /path/to/site-packages/certifi/cacert.pem
46

47
# Get the contents of the CA bundle
48
python -m certifi --contents
49
# Output: -----BEGIN CERTIFICATE-----
50
# MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw...
51
```
52

53
## Capabilities
54

55
### Certificate Bundle Path Access
56

57
Returns the filesystem path to the bundled CA certificate file (cacert.pem).
58

59
```python { .api }
60
def where() -> str:
61
    """
62
    Get the filesystem path to the bundled CA certificate file.
63
    
64
    Returns:
65
        str: The absolute path to the cacert.pem file containing Mozilla's 
66
             CA certificate bundle. The file is guaranteed to exist and be readable.
67
    """
68
```
69

70
The `where()` function uses version-specific implementations to handle different Python environments:
71
- Python 3.11+: Uses `importlib.resources.as_file` and `files`
72
- Python 3.7+: Uses `importlib.resources.path` and manages resource cleanup
73
- Python < 3.7: Falls back to direct filesystem path manipulation
74

75
### Certificate Bundle Contents Access
76

77
Returns the complete contents of the CA certificate bundle as a string.
78

79
```python { .api }
80
def contents() -> str:
81
    """
82
    Get the contents of the bundled CA certificate file.
83
    
84
    Returns:
85
        str: The complete contents of the cacert.pem file as ASCII text,
86
             containing Mozilla's CA certificate bundle in PEM format.
87
             Each certificate begins with "-----BEGIN CERTIFICATE-----"
88
             and ends with "-----END CERTIFICATE-----".
89
    """
90
```
91

92
The `contents()` function also uses version-specific implementations:
93
- Python 3.11+: Uses `importlib.resources.files` with `read_text`
94
- Python 3.7+: Uses `importlib.resources.read_text`
95
- Python < 3.7: Reads directly from the filesystem using the `where()` function
96

97
## Module Attributes
98

99
```python { .api }
100
__version__ = "2024.12.14"
101
__all__ = ["contents", "where"]
102
```
103

104
## Command Line Interface
105

106
The package can be executed as a module to access certificate bundle information from the command line:
107

108
```python { .api }
109
# Default behavior: print path to CA bundle
110
python -m certifi
111

112
# Print contents of CA bundle
113
python -m certifi -c
114
python -m certifi --contents
115
```
116

117
## Usage Examples
118

119
### SSL Context Configuration
120

121
```python
122
import ssl
123
import certifi
124

125
# Create SSL context with certifi's CA bundle
126
context = ssl.create_default_context(cafile=certifi.where())
127

128
# Use in urllib
129
import urllib.request
130
urllib.request.urlopen('https://example.com', context=context)
131
```
132

133
### Requests Library Integration
134

135
```python
136
import requests
137
import certifi
138

139
# Use certifi's CA bundle explicitly
140
response = requests.get('https://example.com', verify=certifi.where())
141
```
142

143
### Certificate Validation
144

145
```python
146
import certifi
147

148
# Verify the CA bundle exists and contains certificates
149
ca_path = certifi.where()
150
ca_contents = certifi.contents()
151

152
print(f"CA bundle location: {ca_path}")
153
print(f"Number of certificates: {ca_contents.count('-----BEGIN CERTIFICATE-----')}")
154
```
155

156
## Architecture Notes
157

158
- **Read-only Design**: The package explicitly does not support modification of the CA trust store content
159
- **Portability**: Designed for maximum compatibility across Python environments and deployment scenarios
160
- **Resource Management**: Handles resource cleanup properly across different Python versions
161
- **Version Compatibility**: Supports Python 3.6+ with fallback implementations for older importlib.resources APIs
162
- **Bundle Source**: Uses Mozilla's carefully curated CA certificate collection
163
- **Update Strategy**: Certificate bundle is updated with new package releases, not dynamically
164

165
## Error Handling
166

167
The package is designed to be robust and typically does not raise exceptions under normal usage. However, potential issues include:
168

169
- **File Access**: If the cacert.pem file becomes corrupted or inaccessible, `where()` may still return a path but `contents()` could fail when reading
170
- **Resource Cleanup**: The package registers cleanup handlers with `atexit` to manage resource contexts properly
171
- **Import Errors**: Fallback implementations handle cases where newer `importlib.resources` APIs are not available
172

173
## Security Considerations
174

175
- **Trust Store Integrity**: The CA bundle cannot be modified at runtime, ensuring consistent certificate validation
176
- **Source Authority**: Certificates come directly from Mozilla's curated collection
177
- **No Dynamic Updates**: Certificate updates require new package versions, preventing runtime tampering
178
- **System Integration**: Designed to work alongside system certificate stores without conflicts