oscrypto

Common errors

• 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.

• 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.

• 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

• pip install oscrypto Install stable version

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

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