{"id":8524,"library":"pysodium","title":"pysodium","description":"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.","status":"active","version":"0.7.18","language":"en","source_language":"en","source_url":"https://github.com/stef/pysodium","tags":["cryptography","libsodium","security","encryption","signatures","nacl"],"install":[{"cmd":"pip install pysodium","lang":"bash","label":"Install pysodium"}],"dependencies":[{"reason":"pysodium is a Python wrapper that requires a pre-installed C library, libsodium, to function. It does not bundle libsodium.","package":"libsodium","optional":false}],"imports":[{"symbol":"pysodium","correct":"import pysodium"}],"quickstart":{"code":"import pysodium\nimport os\n\n# --- Secret-key encryption (Symmetric) ---\n\n# Generate a random 32-byte secret key\nsecret_key = pysodium.randombytes(pysodium.crypto_secretbox_KEYBYTES)\n\n# Generate a unique 24-byte nonce for each message (can be public)\nnonce = pysodium.randombytes(pysodium.crypto_secretbox_NONCEBYTES)\n\nmessage = b\"This is a super secret message for Bob.\"\n\n# Encrypt the message\nciphertext = pysodium.crypto_secretbox(message, nonce, secret_key)\nprint(f\"Original message: {message.decode()}\")\nprint(f\"Ciphertext (hex): {ciphertext.hex()}\")\n\n# Decrypt the message\ntry:\n    decrypted_message = pysodium.crypto_secretbox_open(ciphertext, nonce, secret_key)\n    print(f\"Decrypted message: {decrypted_message.decode()}\")\nexcept pysodium.exceptions.BadSignatureError:\n    print(\"Decryption failed: Message tampered or incorrect key/nonce.\")\n\n# --- Public-key cryptography (Asymmetric) ---\n\n# Generate a key pair for Alice\nalice_public_key, alice_secret_key = pysodium.crypto_box_keypair()\n\n# Generate a key pair for Bob\nbob_public_key, bob_secret_key = pysodium.crypto_box_keypair()\n\nprint(f\"\\nAlice's Public Key: {alice_public_key.hex()}\")\nprint(f\"Bob's Public Key: {bob_public_key.hex()}\")","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade to pysodium >= 0.7.17. Ensure your application's message handling respects the corrected maximum message sizes.","message":"Version 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.","severity":"breaking","affected_versions":"<0.7.17"},{"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).","message":"pysodium 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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.7.15"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install pysodium` to install the package.","cause":"The pysodium Python package has not been installed in your current environment.","error":"ModuleNotFoundError: No module named 'pysodium'"},{"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).","cause":"The underlying `libsodium` C library, which `pysodium` wraps, is not installed or cannot be found in your system's library paths.","error":"OSError: libsodium.so: cannot open shared object file: No such file or directory"},{"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.","cause":"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.","error":"ValueError: Decryption failed"}]}