oscrypto

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