0
# oscrypto
1

2
A compilation-free, always up-to-date Python cryptographic library that works on Windows, macOS, Linux and BSD. oscrypto leverages the operating system's native crypto libraries to provide TLS sockets, asymmetric and symmetric encryption, key generation, signing and verification, and key derivation functions without requiring a compiler.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import oscrypto
14
```
15

16
Common imports for specific functionality:
17

18
```python
19
from oscrypto import asymmetric, symmetric, tls
20
from oscrypto.asymmetric import PrivateKey, PublicKey, Certificate
21
from oscrypto.tls import TLSSocket
22
from oscrypto.kdf import pbkdf2
23
```
24

25
## Basic Usage
26

27
```python
28
import oscrypto
29
from oscrypto import asymmetric, tls
30

31
# Check which backend is being used
32
backend = oscrypto.backend()
33
print(f"Using {backend} backend")
34

35
# Generate an RSA key pair
36
public_key, private_key = asymmetric.generate_pair('rsa', bit_size=2048)
37

38
# Create a self-signed certificate
39
certificate = asymmetric.load_certificate(cert_data)
40

41
# Establish a TLS connection
42
socket = tls.TLSSocket('example.com', 443)
43
socket.write(b'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n')
44
response = socket.read(1024)
45
socket.close()
46

47
# Symmetric encryption
48
from oscrypto.symmetric import aes_cbc_pkcs7_encrypt, aes_cbc_pkcs7_decrypt
49

50
key = b'sixteen byte key'  # 16 bytes for AES-128
51
plaintext = b'This is a secret message'
52
ciphertext = aes_cbc_pkcs7_encrypt(key, plaintext)
53
decrypted = aes_cbc_pkcs7_decrypt(key, ciphertext)
54
```
55

56
## Architecture
57

58
oscrypto automatically selects the appropriate cryptographic backend based on the operating system:
59

60
- **Windows**: Uses CNG (Vista+) or legacy CryptoAPI (XP) with Secure Channel for TLS
61
- **macOS**: Uses Security.framework with Secure Transport for TLS, CommonCrypto for PBKDF2
62
- **Linux/BSD**: Uses OpenSSL or LibreSSL for all operations
63

64
The library provides a unified API that abstracts platform differences while ensuring all operations use OS-native, automatically-updated crypto implementations.
65

66
## Capabilities
67

68
### Backend Configuration
69

70
Core system configuration for selecting cryptographic backends and FFI libraries. This allows forcing specific implementations when needed for testing or compatibility.
71

72
```python { .api }
73
def backend() -> str: ...
74
def ffi() -> str: ...
75
def use_openssl(libcrypto_path: str, libssl_path: str, trust_list_path: str = None) -> None: ...
76
def use_winlegacy() -> None: ...
77
def use_ctypes() -> None: ...
78
```
79

80
[Backend Configuration](./backend.md)
81

82
### Asymmetric Cryptography
83

84
Comprehensive support for RSA, DSA, and ECDSA operations including key generation, loading, signing, verification, encryption, and decryption. Handles multiple key formats and certificate operations.
85

86
```python { .api }
87
def generate_pair(algorithm: str, bit_size: int = None, curve: str = None) -> Tuple[PublicKey, PrivateKey]: ...
88
def load_private_key(source: Union[str, bytes], password: bytes = None) -> PrivateKey: ...
89
def load_certificate(source: Union[str, bytes]) -> Certificate: ...
90
def rsa_pkcs1v15_encrypt(certificate_or_public_key: Union[Certificate, PublicKey], data: bytes) -> bytes: ...
91
def rsa_pkcs1v15_sign(private_key: PrivateKey, data: bytes, hash_algorithm: str) -> bytes: ...
92
```
93

94
[Asymmetric Cryptography](./asymmetric.md)
95

96
### Symmetric Cryptography
97

98
Symmetric encryption and decryption using AES, DES, 3DES, RC2, and RC4 algorithms with various modes and padding schemes. All operations use OS-native implementations.
99

100
```python { .api }
101
def aes_cbc_pkcs7_encrypt(key: bytes, data: bytes, iv: bytes = None) -> bytes: ...
102
def aes_cbc_pkcs7_decrypt(key: bytes, data: bytes, iv: bytes = None) -> bytes: ...
103
def des_cbc_pkcs5_encrypt(key: bytes, data: bytes, iv: bytes = None) -> bytes: ...
104
def rc4_encrypt(key: bytes, data: bytes) -> bytes: ...
105
```
106

107
[Symmetric Cryptography](./symmetric.md)
108

109
### TLS Support
110

111
Modern TLS socket implementation with certificate verification using OS trust stores, SNI support, session reuse, and strong cipher suites. Provides secure network communications.
112

113
```python { .api }
114
class TLSSocket:
115
    def __init__(self, hostname: str, port: int, session: TLSSession = None): ...
116
    def read(self, max_length: int) -> bytes: ...
117
    def write(self, data: bytes) -> None: ...
118
    def close() -> None: ...
119

120
class TLSSession:
121
    def __init__(self, protocol: str = None, manual_validation: bool = False): ...
122
```
123

124
[TLS Support](./tls.md)
125

126
### Key Derivation Functions
127

128
Password-based key derivation using PBKDF1, PBKDF2, and PKCS#12 KDF. Includes automatic iteration calculation for target computation times.
129

130
```python { .api }
131
def pbkdf2(hash_algorithm: str, password: bytes, salt: bytes, iterations: int, key_length: int) -> bytes: ...
132
def pbkdf2_iteration_calculator(hash_algorithm: str, key_length: int, target_ms: int = 100, quiet: bool = False) -> int: ...
133
def pkcs12_kdf(hash_algorithm: str, password: bytes, salt: bytes, iterations: int, key_length: int, id_: int) -> bytes: ...
134
```
135

136
[Key Derivation Functions](./kdf.md)
137

138
### Trust Store Management
139

140
Access and export OS trust store certificates for use with OpenSSL-based code. Provides CA certificate bundles in PEM format.
141

142
```python { .api }
143
def get_list() -> List[Certificate]: ...
144
def get_path() -> str: ...
145
def clear_cache() -> None: ...
146
```
147

148
[Trust Store Management](./trust-store.md)
149

150
### Utility Functions
151

152
Cryptographic utilities including secure random number generation and constant-time comparison for security-critical operations.
153

154
```python { .api }
155
def rand_bytes(length: int) -> bytes: ...
156
def constant_compare(a: bytes, b: bytes) -> bool: ...
157
```
158

159
[Utility Functions](./utility.md)
160

161
### Key Management
162

163
Parsing and handling of keys and certificates from various formats including DER, PEM, PKCS#8, and PKCS#12.
164

165
```python { .api }
166
def parse_certificate(data: bytes) -> Certificate: ...
167
def parse_private(data: bytes) -> PrivateKey: ...
168
def parse_public(data: bytes) -> PublicKey: ...
169
def parse_pkcs12(data: bytes, password: bytes = None) -> Tuple[Certificate, PrivateKey, List[Certificate]]: ...
170
```
171

172
[Key Management](./keys.md)
173

174
## Types
175

176
```python { .api }
177
class Certificate:
178
    """X.509 certificate wrapper with validation and inspection methods."""
179
    
180
class PrivateKey:
181
    """Private key wrapper supporting RSA, DSA, and ECDSA with signing and decryption methods."""
182
    
183
class PublicKey:
184
    """Public key wrapper supporting RSA, DSA, and ECDSA with verification and encryption methods."""
185

186
class TLSSocket:
187
    """TLS socket wrapper providing secure network communication."""
188
    
189
class TLSSession:
190
    """TLS session manager for connection reuse and configuration."""
191
```
192

193
## Exceptions
194

195
```python { .api }
196
class LibraryNotFoundError(Exception):
197
    """Raised when trying to find a shared library."""
198

199
class SignatureError(Exception):
200
    """Raised when validating a signature fails."""
201

202
class AsymmetricKeyError(Exception):
203
    """Raised when a key is invalid or unsupported."""
204

205
class IncompleteAsymmetricKeyError(AsymmetricKeyError):
206
    """Raised when a key is missing necessary information."""
207

208
class CACertsError(Exception):
209
    """Raised when exporting CA certs from the OS trust store fails."""
210

211
class TLSError(Exception):
212
    """Base exception for TLS functionality."""
213

214
class TLSConnectionError(TLSError):
215
    """TLS connection error."""
216

217
class TLSDisconnectError(TLSConnectionError):
218
    """TLS disconnect error."""
219

220
class TLSGracefulDisconnectError(TLSDisconnectError):
221
    """TLS graceful disconnect."""
222

223
class TLSVerificationError(TLSError):
224
    """Server certificate verification error during TLS handshake."""
225
```