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 oscryptoVerified import paths — ran on the pinned version, not inferred.
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`.
Review the 'Modern Cryptography' section in the oscrypto documentation and consider `pyca/pynacl` for new projects requiring modern cryptographic primitives.
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.
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.
Update code that processes the output of `trust_list.get_list()` to unpack the 3-element tuples correctly.
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`.
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.
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.
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.
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++).