Registry / auth-security / pysodium

pysodium

JSON →
library0.7.18pypypi✓ verified 89d ago

pysodium is a Python wrapper for the `libsodium` cryptography library, providing high-level cryptographic primitives for tasks like encryption, decryption, signatures, and key derivation. The library aims to offer a simple interface, often aligning with the PyNaCl API, and handles buffer management for ease of use in Python. It is currently at version 0.7.18 and receives regular updates, with new features and security fixes introduced periodically.

pip install pysodium
INSTALL
IMPORT
SIG · PYSODIUM
P
pysodium
auth-securitypythonv0.7.18
Install
2.4s avg
Import
—
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.7.18 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.3MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pysodium
✓ import pysodium

This quickstart demonstrates basic symmetric (secret-key) encryption and decryption using `crypto_secretbox` and `crypto_secretbox_open`, and asymmetric (public-key) key pair generation using `crypto_box_keypair`.

import pysodium import os # --- Secret-key encryption (Symmetric) --- # Generate a random 32-byte secret key secret_key = pysodium.randombytes(pysodium.crypto_secretbox_KEYBYTES) # Generate a unique 24-byte nonce for each message (can be public) nonce = pysodium.randombytes(pysodium.crypto_secretbox_NONCEBYTES) message = b"This is a super secret message for Bob." # Encrypt the message ciphertext = pysodium.crypto_secretbox(message, nonce, secret_key) print(f"Original message: {message.decode()}") print(f"Ciphertext (hex): {ciphertext.hex()}") # Decrypt the message try: decrypted_message = pysodium.crypto_secretbox_open(ciphertext, nonce, secret_key) print(f"Decrypted message: {decrypted_message.decode()}") except pysodium.exceptions.BadSignatureError: print("Decryption failed: Message tampered or incorrect key/nonce.") # --- Public-key cryptography (Asymmetric) --- # Generate a key pair for Alice alice_public_key, alice_secret_key = pysodium.crypto_box_keypair() # Generate a key pair for Bob bob_public_key, bob_secret_key = pysodium.crypto_box_keypair() print(f"\nAlice's Public Key: {alice_public_key.hex()}") print(f"Bob's Public Key: {bob_public_key.hex()}")
Debug
Known issues
breakingVersion 0.7.17 fixed a security vulnerability where `crypto_secretstream_xchacha20poly1305_MESSAGEBYTES_MAX`, `crypto_aead_aegis128l_MESSAGEBYTES_MAX`, and `crypto_aead_aegis256_MESSAGEBYTES_MAX` were set to insecurely large values. All users should upgrade to 0.7.17 or later to mitigate potential security risks related to message size limits.
fix
Upgrade to pysodium >= 0.7.17. Ensure your application's message handling respects the corrected maximum message sizes.
affects: <0.7.17
gotchapysodium is a wrapper for the `libsodium` C library. You *must* have `libsodium` installed on your system for `pysodium` to work. The `pip install pysodium` command only installs the Python bindings, not the underlying C library.
fix
Install `libsodium` system-wide using your operating system's package manager (e.g., `apt install libsodium-dev` on Debian/Ubuntu, `brew install libsodium` on macOS, or build from source on Windows).
affects: All versions
gotchaPrior to v0.7.15, some `keygen()` functions in `pysodium` incorrectly returned the size (e.g., 32 for a 32-byte key) instead of a success/fail indicator (0 or 1). Code that checked these return values for success might have exhibited incorrect behavior if they expected a boolean-like result.
fix
Upgrade to pysodium >= 0.7.15. Review any code that explicitly checks the return value of `keygen()` functions to ensure it aligns with the corrected behavior (which typically means these functions now directly return the key material or raise an error on failure).
affects: <0.7.15
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pysodium'
The pysodium Python package has not been installed in your current environment.
fix
Run `pip install pysodium` to install the package.
OSError: libsodium.so: cannot open shared object file: No such file or directory
The underlying `libsodium` C library, which `pysodium` wraps, is not installed or cannot be found in your system's library paths.
fix
Install the `libsodium` development package for your operating system (e.g., `sudo apt-get install libsodium-dev` on Debian/Ubuntu, `brew install libsodium` on macOS). For Windows, you'll need to download and install the pre-compiled `libsodium` binaries or compile from source, ensuring the `libsodium.dll` is discoverable by Python (e.g., in PATH).
ValueError: Decryption failed
This error, often specifically `pysodium.exceptions.BadSignatureError`, indicates that the ciphertext has been tampered with, or the key/nonce used for decryption does not match those used for encryption. This is a deliberate security feature of authenticated encryption.
fix
Ensure the `key`, `nonce`, and `ciphertext` are exactly the same as those used during encryption. Verify that no data corruption or malicious modification has occurred during transmission or storage. If using public-key cryptography, ensure the correct sender's public key and receiver's secret key are used.
Upgrade
Version history
0.7.18latest on PyPI · released Aug 7, 2024
Audit
Dependencies
libsodiumrequiredpysodium is a Python wrapper that requires a pre-installed C library, libsodium, to function. It does not bundle libsodium.
Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources
pysodium — pip install pysodium · libregistry