0
# pyOpenSSL
1

2
A Python wrapper around the OpenSSL library providing cryptographic functionality and TLS/SSL capabilities. pyOpenSSL offers SSL.Connection objects that wrap Python's portable sockets, Python-based callbacks, and an extensive error-handling mechanism that mirrors OpenSSL's error codes. The library serves as a high-level interface for secure network communications, certificate handling, and cryptographic operations in Python applications.
3

4
## Package Information
5

6
- **Package Name**: pyOpenSSL
7
- **Language**: Python
8
- **Installation**: `pip install pyopenssl`
9

10
## Core Imports
11

12
```python
13
import OpenSSL
14
from OpenSSL import SSL, crypto, rand, debug
15
```
16

17
Individual components:
18

19
```python
20
from OpenSSL.SSL import Context, Connection, Session
21
from OpenSSL.crypto import X509, PKey, X509Store, X509Name, load_certificate, dump_certificate
22
from OpenSSL.rand import add, status  # Deprecated
23
```
24

25
Version information:
26

27
```python
28
from OpenSSL import __version__, __title__, __author__, __uri__
29
```
30

31
## Basic Usage
32

33
```python
34
from OpenSSL import SSL, crypto
35
import socket
36

37
# Create an SSL context for a client connection
38
context = SSL.Context(SSL.TLS_CLIENT_METHOD)
39
context.set_default_verify_paths()
40
context.set_verify(SSL.VERIFY_PEER, None)
41

42
# Create a socket and wrap it with SSL
43
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
44
connection = SSL.Connection(context, sock)
45
connection.connect(('www.example.com', 443))
46
connection.do_handshake()
47

48
# Send HTTP request
49
connection.send(b'GET / HTTP/1.0\r\nHost: www.example.com\r\n\r\n')
50
response = connection.recv(4096)
51
print(response.decode())
52

53
connection.close()
54
```
55

56
Certificate management example:
57

58
```python
59
from OpenSSL import crypto
60

61
# Load a certificate from file
62
with open('certificate.pem', 'rb') as f:
63
    cert_data = f.read()
64
    
65
cert = crypto.load_certificate(crypto.FILETYPE_PEM, cert_data)
66

67
# Examine certificate properties
68
print("Subject:", cert.get_subject().CN)
69
print("Issuer:", cert.get_issuer().CN)
70
print("Serial Number:", cert.get_serial_number())
71
print("Has Expired:", cert.has_expired())
72
```
73

74
## Architecture
75

76
pyOpenSSL provides several modules with distinct responsibilities:
77

78
- **SSL Module**: High-level SSL/TLS connection handling with Context objects for configuration and Connection objects that wrap sockets with SSL/TLS capabilities
79
- **Crypto Module**: X.509 certificate operations, cryptographic key management, and certificate store operations for trust validation  
80
- **Rand Module** (Deprecated): Random number generation utilities for backward compatibility
81
- **Debug Module**: Environment and build information for debugging
82

83
The library integrates with Python's cryptography library, providing conversion methods between pyOpenSSL objects and cryptography objects for interoperability. Version information is available through module-level constants.
84

85
## Capabilities
86

87
### SSL/TLS Connections
88

89
Complete SSL/TLS client and server connection handling with support for modern protocols (TLS 1.2, 1.3), DTLS, session management, and advanced features like SNI, ALPN, and OCSP stapling.
90

91
```python { .api }
92
class Context:
93
    def __init__(self, method: int): ...
94
    def set_verify(self, mode: int, callback=None): ...
95
    def use_certificate_file(self, certfile, filetype=FILETYPE_PEM): ...
96
    def use_privatekey_file(self, keyfile, filetype=FILETYPE_PEM): ...
97

98
class Connection:
99
    def __init__(self, context: Context, socket=None): ...
100
    def connect(self, addr): ...
101
    def do_handshake(): ...
102
    def send(self, buf, flags=0) -> int: ...
103
    def recv(self, bufsiz, flags=None) -> bytes: ...
104
```
105

106
[SSL Connections](./ssl-connections.md)
107

108
### X.509 Certificate Management
109

110
Comprehensive X.509 certificate lifecycle management including creation, signing, verification, and parsing with support for certificate extensions, distinguished names, and certificate stores.
111

112
```python { .api }
113
class X509:
114
    def __init__(): ...
115
    def get_subject() -> X509Name: ...
116
    def set_subject(subject: X509Name): ...
117
    def sign(pkey: PKey, digest: str): ...
118
    def has_expired() -> bool: ...
119

120
def load_certificate(type: int, buffer: bytes) -> X509: ...
121
def dump_certificate(type: int, cert: X509) -> bytes: ...
122
```
123

124
[Certificate Management](./certificate-management.md)
125

126
### Cryptographic Keys
127

128
Asymmetric key operations supporting RSA, DSA, EC, Ed25519, and Ed448 keys with generation, loading, serialization, and conversion capabilities.
129

130
```python { .api }
131
class PKey:
132
    def __init__(): ...
133
    def generate_key(type: int, bits: int): ...
134
    def check() -> bool: ...
135
    def to_cryptography_key(): ...
136

137
def load_privatekey(type: int, buffer: str | bytes, passphrase=None) -> PKey: ...
138
def dump_privatekey(type: int, pkey: PKey, cipher=None, passphrase=None) -> bytes: ...
139
```
140

141
[Cryptographic Keys](./cryptographic-keys.md)
142

143
### Certificate Verification
144

145
Certificate trust store management and verification operations with support for certificate chains, CRL checking, and custom verification policies.
146

147
```python { .api }
148
class X509Store:
149
    def __init__(): ...
150
    def add_cert(cert: X509): ...
151
    def set_flags(flags: int): ...
152

153
class X509StoreContext:
154
    def __init__(store: X509Store, certificate: X509, chain=None): ...
155
    def verify_certificate(): ...
156
```
157

158
[Certificate Verification](./certificate-verification.md)
159

160
### Random Number Generation (Deprecated)
161

162
Legacy random number generation utilities for entropy seeding. These functions are deprecated as modern OpenSSL handles seeding automatically.
163

164
```python { .api }
165
@deprecated
166
def add(buffer: bytes, entropy: int) -> None: ...
167
@deprecated
168
def status() -> int: ...
169
```
170

171
[Random Number Generation](./rand-module.md)
172

173
### Version and Debug Information
174

175
Access to package version information and OpenSSL build details for debugging and compatibility checking.
176

177
```python { .api }
178
__version__: str  # Package version
179
__title__: str  # Package name  
180
__author__: str  # Package authors
181
__uri__: str  # Package homepage
182

183
# OpenSSL version information (from SSL module)
184
OPENSSL_VERSION: bytes  # OpenSSL version string
185
OPENSSL_VERSION_NUMBER: int  # OpenSSL version number
186
```