oscrypto

1.3.0 verified Tue May 12 auth: no python install: draft

oscrypto is a compilation-free Python library that exposes cryptography primitives from the host operating system's crypto libraries, such as Windows CNG, macOS Security.framework, and OpenSSL/LibreSSL on Linux/BSD. It currently stands at version 1.3.0 and focuses on providing basic crypto functionality like TLS (SSL) sockets, key generation, encryption, decryption, signing, verification, and KDFs. The library relies on the OS for security patching, avoiding the need for recompilation with every new vulnerability.

pip install oscrypto

Common errors

error oscrypto.errors.LibraryNotFoundError: Error detecting the version of libcrypto ↓

cause This error often occurs when oscrypto (especially versions 1.3.0 and earlier) fails to correctly parse the version of a multi-digit OpenSSL release (e.g., 3.0.10), or when the expected libcrypto.so symlink is missing on certain Linux distributions like Alpine Linux.

fix

If using a Linux distribution like Alpine, ensure a symlink exists from the specific libcrypto.so.X.Y version to libcrypto.so (e.g., ln -s /usr/lib/libcrypto.so.1.1 /usr/lib/libcrypto.so). If the issue is with OpenSSL version detection, consider upgrading to a newer oscrypto version (if available on PyPI with a fix) or installing the latest development version from the oscrypto GitHub repository. Alternatively, some users have found success by pinning their OpenSSL version to less than 3.0.10 or by setting the environment variable OSCRYPTO_USE_CTYPES=true to force oscrypto to use ctypes instead of cffi.

error ModuleNotFoundError: No module named 'cffi' ↓

cause oscrypto prefers to use the cffi module for Foreign Function Interface (FFI) if it is installed. This error occurs when cffi is not found in the Python environment, preventing oscrypto from using its preferred FFI backend.

fix

Install the cffi package using pip: pip install cffi. If you wish to explicitly avoid cffi and use ctypes (which is built into Python's standard library), set the environment variable OSCRYPTO_USE_CTYPES=true before running your application.

error KeyError: '1.2.840.113549.1.7.1' (or similar OID) when calling oscrypto.asymmetric.load_private_key ↓

cause This KeyError typically arises when `oscrypto.asymmetric.load_private_key` attempts to parse ASN.1 encoded bytes that are malformed, not a valid private key structure, or a different cryptographic structure (like a PKCS#12 PDU). The underlying `asn1crypto` library might raise a KeyError when an unexpected OID is encountered during type determination.

fix

Ensure that the input source provided to oscrypto.asymmetric.load_private_key is a correctly formatted private key (e.g., PKCS#8 or OpenSSL PEM/DER format). Verify the integrity and encoding of your key file. A common cause for key loading issues is incorrect line endings (CRLF instead of LF) in the key file, especially when transferring between Windows and Unix/Linux systems. Convert line endings to LF if necessary (e.g., using dos2unix or a text editor like Notepad++).

Warnings

gotcha oscrypto explicitly states that many of its supported ciphers and hashes are for integration with legacy systems, and recommends modern cryptography libraries like `pyca/pynacl` or `scrypt` for new applications. Using `oscrypto` for modern crypto without proper cryptographic knowledge can lead to unsafe implementations. ↓

fix Review the 'Modern Cryptography' section in the oscrypto documentation and consider `pyca/pynacl` for new projects requiring modern cryptographic primitives.

breaking In version 1.0.0, the `oscrypto.backend()` function was changed to return 'mac' instead of 'osx' when running on a Mac and not explicitly configured to use OpenSSL. Code relying on the exact string 'osx' will break. ↓

fix Update code to check for 'mac' or handle both 'mac' and 'osx' if supporting older versions, or explicitly configure OpenSSL backend if 'osx' is strictly required for certain logic.

breaking In version 0.19.0, `trust_list.get_path()` no longer accepts the `map_vendor_oids` parameter and only includes CA certificates marked as trusted for TLS server authentication. This changed behavior may affect applications relying on the previous certificate list content. ↓

fix Review usage of `trust_list.get_path()` and adjust expectations or implementation if `map_vendor_oids` was previously used or if a broader set of CA certificates is required.

breaking Version 0.16.0 changed the return format of `trust_list.get_list()`. It now returns a list of 3-element tuples (certificate byte string, set of trust OIDs, set of reject OIDs) instead of a list of certificate byte strings. ↓

fix Update code that processes the output of `trust_list.get_list()` to unpack the 3-element tuples correctly.

gotcha oscrypto version 1.3.0 and earlier has a known bug that prevents it from detecting OpenSSL 3.0.10 or later, leading to `LibraryNotFoundError`. This affects users relying on newer OpenSSL versions. A fix exists on GitHub but is not yet released on PyPI. ↓

fix For now, either downgrade OpenSSL to a version earlier than 3.0.10 or install `oscrypto` directly from the GitHub repository to get the unreleased fix: `pip install git+https://github.com/wbond/oscrypto`.

gotcha The `dump_openssl_private_key()` function is provided for compatibility with legacy systems, but its use is strongly discouraged. OpenSSL formats for private keys do not stretch the passphrase, making them vulnerable to brute-force attacks compared to PKCS#8, which offers superior encryption. ↓

fix Prefer `PKCS#8` for private key serialization and storage whenever possible, avoiding `dump_openssl_private_key()` unless absolutely necessary for integration with systems that do not support PKCS#8.

Install compatibility draft last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 20.6M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 1.6s 0.10s 21M

3.10 slim (glibc) - - 0.10s 21M

3.11 alpine (musl) wheel - - 22.9M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 1.7s 0.21s 23M

3.11 slim (glibc) - - 0.20s 23M

3.12 alpine (musl) wheel - - 14.7M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.6s 0.19s 15M

3.12 slim (glibc) - - 0.20s 15M

3.13 alpine (musl) wheel - - 14.4M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.6s 0.20s 15M

3.13 slim (glibc) - - 0.19s 15M

3.9 alpine (musl) wheel - - 20.1M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 1.9s 0.12s 21M

3.9 slim (glibc) - - 0.12s 21M

Imports

generate_pair

from oscrypto.asymmetric import generate_pair

rsa_oaep_encrypt

from oscrypto.asymmetric import rsa_oaep_encrypt

aes_cbc_pkcs7_encrypt

from oscrypto.symmetric import aes_cbc_pkcs7_encrypt

TLSSocket
```
from oscrypto.tls import TLSSocket
```
rand_bytes
```
from oscrypto.util import rand_bytes
```

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to generate an RSA key pair, encrypt data using the public key with OAEP padding, and then decrypt it using the private key. This illustrates a fundamental asymmetric encryption workflow provided by `oscrypto.asymmetric`.

from oscrypto.asymmetric import generate_pair, rsa_oaep_encrypt, rsa_oaep_decrypt
from oscrypto.util import rand_bytes

# Generate an RSA key pair
public_key, private_key = generate_pair('rsa', bit_size=2048)

# Data to encrypt
original_data = b'This is a secret message.'

# Encrypt data using the public key
encrypted_data = rsa_oaep_encrypt(public_key, original_data)
print(f'Encrypted data length: {len(encrypted_data)} bytes')

# Decrypt data using the private key
decrypted_data = rsa_oaep_decrypt(private_key, encrypted_data)

print(f'Original data: {original_data.decode()}')
print(f'Decrypted data: {decrypted_data.decode()}')
assert original_data == decrypted_data