Registry / auth-security / libnacl

libnacl

JSON →
library2.1.0pypypi✓ verified 85d ago

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.

pip install libnacl
INSTALL
IMPORT
SIG · LIBNACL
L
libnacl
auth-securitypythonv2.1.0
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.1.0 · 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.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

SecretKey
from libnacl.public import SecretKey
Box
from libnacl.public import Box
SealedBox
from libnacl.sealed import SealedBox
crypto_secretbox
import libnacl libnacl.crypto_secretbox(...)
salsa_key
import libnacl.utils libnacl.utils.salsa_key()

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.

import libnacl.public # Define a message to send (must be bytes) msg = b'You\'ve got two empty halves of coconut and you\'re bangin\' \'em together.' # Generate the key pairs for Alice and Bob bob = libnacl.public.SecretKey() alice = libnacl.public.SecretKey() # Create Box objects representing the combination of sender's secret key and receiver's public key bob_box = libnacl.public.Box(bob.sk, alice.pk) alice_box = libnacl.public.Box(alice.sk, bob.pk) # Bob encrypts a message for Alice bob_ctxt = bob_box.encrypt(msg) # Alice decrypts the message from Bob bclear = alice_box.decrypt(bob_ctxt) print(f"Original message: {msg}") print(f"Decrypted message from Bob: {bclear}") # Alice encrypts a message for Bob alice_ctxt = alice_box.encrypt(msg) # Bob decrypts the message from Alice aclear = bob_box.decrypt(alice_ctxt) print(f"Decrypted message from Alice: {aclear}") assert msg == bclear assert msg == aclear
Debug
Known issues
breakingWhen 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.
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).
affects: <2.x.x, potentially all versions with direct low-level API usage
gotchaNonce 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.
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.
affects: All versions
gotcha`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.
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).
affects: All versions
Errors
Common errors & fixes
OSError: Could not locate nacl lib, searched for libsodium.
The underlying `libsodium` C library is not installed on the system or `libnacl` cannot find it in standard library paths.
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.
'nacl' __virtual__ returned False: libnacl import error, perhaps missing python libnacl package or should update.
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.
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`.
libnacl.exceptions.BadSignatureError: Signature was forged or otherwise corrupt.
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.
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.
Upgrade
Version history
2.1.0latest on PyPI · released Aug 6, 2023
Audit
Dependencies
libsodiumrequiredlibnacl is a ctypes wrapper requiring the underlying libsodium C library to be installed on the system.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
libnacl — pip install libnacl · libregistry