{"id":7363,"library":"libnacl","title":"Python Bindings for Libsodium (libnacl)","description":"libnacl provides Python bindings for the high-speed Networking and Cryptography library (NaCl), specifically leveraging libsodium via ctypes. It aims to offer direct access to libsodium's functions while maintaining extensive documentation and portability. The library supports both low-level cryptographic primitives and higher-level Pythonic encryption classes. It is currently at version 2.1.0 and is actively maintained.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/saltstack/libnacl","tags":["cryptography","nacl","libsodium","security","encryption","decryption","signatures","ctypes"],"install":[{"cmd":"pip install libnacl","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"libnacl is a ctypes wrapper requiring the underlying libsodium C library to be installed on the system.","package":"libsodium","optional":false}],"imports":[{"symbol":"SecretKey","correct":"from libnacl.public import SecretKey"},{"symbol":"Box","correct":"from libnacl.public import Box"},{"symbol":"SealedBox","correct":"from libnacl.sealed import SealedBox"},{"symbol":"crypto_secretbox","correct":"import libnacl\nlibnacl.crypto_secretbox(...)"},{"symbol":"salsa_key","correct":"import libnacl.utils\nlibnacl.utils.salsa_key()"}],"quickstart":{"code":"import libnacl.public\n\n# Define a message to send (must be bytes)\nmsg = b'You\\'ve got two empty halves of coconut and you\\'re bangin\\' \\'em together.'\n\n# Generate the key pairs for Alice and Bob\nbob = libnacl.public.SecretKey()\nalice = libnacl.public.SecretKey()\n\n# Create Box objects representing the combination of sender's secret key and receiver's public key\nbob_box = libnacl.public.Box(bob.sk, alice.pk)\nalice_box = libnacl.public.Box(alice.sk, bob.pk)\n\n# Bob encrypts a message for Alice\nbob_ctxt = bob_box.encrypt(msg)\n\n# Alice decrypts the message from Bob\nbclear = alice_box.decrypt(bob_ctxt)\n\nprint(f\"Original message: {msg}\")\nprint(f\"Decrypted message from Bob: {bclear}\")\n\n# Alice encrypts a message for Bob\nalice_ctxt = alice_box.encrypt(msg)\n\n# Bob decrypts the message from Alice\naclear = bob_box.decrypt(alice_ctxt)\n\nprint(f\"Decrypted message from Alice: {aclear}\")\n\nassert msg == bclear\nassert msg == aclear\n","lang":"python","description":"This quickstart demonstrates public-key encryption using `libnacl.public.Box` for secure communication between two parties, Alice and Bob. It shows how to generate key pairs, create communication 'boxes', and encrypt/decrypt messages."},"warnings":[{"fix":"Prefer higher-level `Box` or `SecretBox` classes which abstract away padding details. If using raw `crypto_secretbox`, ensure message conforms to `libsodium`'s padding requirements (e.g., pre-pending 32 null bytes if required by the specific libsodium version/implementation for MAC key).","message":"When using raw `crypto_secretbox` functions directly, specific padding requirements (e.g., zero-padding for the first 32 bytes) might be necessary due to underlying NaCl design for MAC key generation. While higher-level `libnacl` wrappers may handle this, direct low-level usage might break if not accounted for.","severity":"breaking","affected_versions":"<2.x.x, potentially all versions with direct low-level API usage"},{"fix":"Always ensure a unique nonce is used for each message encrypted with the same key pair. For high-level APIs like `Box.encrypt()`, a random nonce is generated by default. If manually generating, use `libnacl.utils.rand_nonce()` or a cryptographically secure random source and track nonce usage carefully.","message":"Nonce reuse with the same key pair is a critical security vulnerability that can compromise encrypted data. `libnacl` generates a random nonce if not explicitly provided to encryption functions, but manual nonce management requires extreme care.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the `libsodium` development headers and runtime library through your system's package manager (e.g., `sudo apt-get install libsodium-dev` on Debian/Ubuntu, `brew install libsodium` on macOS, or `vcpkg install libsodium` on Windows).","message":"`libnacl` is a Python ctypes wrapper, meaning it requires the `libsodium` C library to be installed on the host system. Installing `libnacl` via `pip` only installs the Python package, not the C library.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `libsodium` via your system's package manager. For Debian/Ubuntu, use `sudo apt-get install libsodium-dev`. Ensure the library is accessible in your system's `LD_LIBRARY_PATH` (Linux) or `PATH` (Windows) if installed in a non-standard location.","cause":"The underlying `libsodium` C library is not installed on the system or `libnacl` cannot find it in standard library paths.","error":"OSError: Could not locate nacl lib, searched for libsodium."},{"fix":"First, ensure `libsodium` is correctly installed on your system (see above fix). Then, try reinstalling `libnacl` in your Python environment: `pip uninstall libnacl && pip install libnacl`.","cause":"This error often occurs when `libnacl` is installed in the Python environment, but it fails to load the underlying `libsodium` C library, or there's a version mismatch/corruption.","error":"'nacl' __virtual__ returned False: libnacl import error, perhaps missing python libnacl package or should update."},{"fix":"Verify that the correct secret key, public key, and nonce (if applicable) are being used for decryption. Ensure the ciphertext has not been tampered with in transit. This error is a security feature, indicating a failed authenticity check.","cause":"This exception is raised when the integrity check of an encrypted message fails, indicating that the ciphertext or its associated authentication tag has been altered, or an incorrect key/nonce was used during decryption.","error":"libnacl.exceptions.BadSignatureError: Signature was forged or otherwise corrupt."}]}