Registry / auth-security / nkeys
library0.2.1pypypi✓ verified 84d ago

The `nkeys` Python library, currently at version 0.2.1, provides a public-key signature system built upon Ed25519 cryptography, specifically designed for identity, authentication, and authorization within the NATS ecosystem. It offers utilities for generating, encoding, and managing NATS-compatible key pairs (Operators, Accounts, Users, Servers, Clusters). The library maintains a low-to-moderate release cadence, with recent updates focusing on dependency management and Python version compatibility.

pip install nkeys
INSTALL
IMPORT
SIG · NKEYS
N
nkeys
auth-securitypythonv0.2.1
Install
3.6s avg
Import
23ms
Disk
22MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.1 · 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.024s · 23.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.6s · import 0.021s · 24MB
22MB installed
● package 22MB
Code
Verified usage

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

nkeys
import nkeys
SigningKey
from nacl.signing import SigningKey
Required for generating raw Ed25519 keys before encoding them into NATS nkeys format.

This quickstart demonstrates how to generate a new NATS user key pair (seed, public, and private keys) using `nkeys` and `pynacl`, then sign and verify a message. It also highlights the importance of wiping sensitive key data.

import nkeys from nacl.signing import SigningKey import os # 1. Generate a raw Ed25519 signing key using PyNaCl raw_signing_key = SigningKey.generate() # 2. Encode the raw key as a NATS user seed (e.g., SU...) # The `encode_seed` function combines the raw private key with the NATS prefix. # Use nkeys.PREFIX_BYTE_USER for a user key, nkeys.PREFIX_BYTE_ACCOUNT for an account, etc. user_seed_bytes = nkeys.encode_seed(nkeys.PREFIX_BYTE_USER, raw_signing_key.encode()) print(f"Generated User Seed (NKEY format): {user_seed_bytes.decode()}") # 3. Create an NKEYS KeyPair object from the seed key_pair = nkeys.from_seed(user_seed_bytes) print(f"Public Key (U...): {key_pair.public_key.decode()}") # The private key and seed should be kept secret. # The raw private key is a 64-byte Ed25519 private key. print(f"Private Key (raw hex - keep secret!): {key_pair.private_key.hex()}") print(f"Seed (S... NKEY format - keep secret!): {key_pair.seed.decode()}") # 4. Example of signing data data_to_sign = b"Hello NATS! This is a test message." signature = key_pair.sign(data_to_sign) print(f"Signature for data: {signature.hex()}") # 5. Verification (a KeyPair created from the public key can verify signatures) verifier_key_pair = nkeys.from_public_key(key_pair.public_key) try: verifier_key_pair.verify(data_to_sign, signature) print("Signature verified successfully.") except Exception as e: print(f"Signature verification failed: {e}") # 6. Secure handling: wipe sensitive key material from memory when no longer needed key_pair.wipe() print("Sensitive key material wiped from memory for security.")
Debug
Known issues
breakingVersion 0.2.0 introduced a breaking change by replacing the `ed25519` dependency with `pynacl` to support Python 3.12 and newer versions. Projects relying on `nkeys` might need to update their environments to correctly build `pynacl`.
fix
Ensure `pynacl` and its underlying `libsodium` are correctly installed. For environments like Docker, this may involve adding build-time dependencies (e.g., `gcc`, `musl-dev`, `libffi-dev` on Alpine Linux, or development headers) or ensuring pre-built wheels are compatible with your platform.
affects: >=0.2.0
gotchaInstalling `pynacl` (a core dependency) can sometimes fail in constrained environments (e.g., Docker containers, specific OS builds) if system-level build tools or `libsodium` libraries are not present. This is because `pynacl` is a C extension.
fix
If `pip install nkeys` or `pip install pynacl` fails, check the error output for missing compilers (like `gcc`) or development headers (like `libffi-dev`, `libsodium-dev`). Install these system-level packages via your OS package manager (e.g., `apt-get install build-essential libffi-dev` on Debian/Ubuntu, `apk add gcc musl-dev libffi-dev` on Alpine).
affects: All versions depending on `pynacl` (>=0.2.0)
gotchaNATS NKeys utilize specific prefixes (e.g., 'S' for seed, 'U' for user, 'A' for account, 'O' for operator) encoded into the key string. Misunderstanding or incorrect handling of these prefixes can lead to invalid keys or authentication failures.
fix
Always use the provided `nkeys.PREFIX_BYTE_X` constants (e.g., `nkeys.PREFIX_BYTE_USER`, `nkeys.PREFIX_BYTE_ACCOUNT`) when encoding raw keys into NATS NKey format, for instance, with `nkeys.encode_seed()`. Ensure that the resulting NKey strings start with the expected prefix for their type.
affects: All
Errors
Common errors & fixes
AttributeError: module 'configparser' has no attribute 'SafeConfigParser'
This error typically occurs when the older `ed25519` dependency, which `nkeys` used prior to v0.2.0, attempts to install on Python 3.12 or newer. The `ed25519` library's `versioneer` component has a compatibility issue with `configparser` in newer Python versions.
fix
Upgrade `nkeys` to version 0.2.0 or higher: `pip install --upgrade nkeys`. This version replaces `ed25519` with `pynacl`, resolving the compatibility issue.
Failed building wheel for pynacl (or 'error: command 'gcc' failed with exit status 1')
The `pynacl` library, a dependency of `nkeys` (since v0.2.0), requires a C compiler (like GCC) and potentially development headers (e.g., `libffi-dev`) to compile its C extensions if a pre-built wheel is not available for your specific Python version and operating system.
fix
Install the necessary build tools and development libraries for your operating system. For Debian/Ubuntu: `sudo apt-get update && sudo apt-get install build-essential libffi-dev`. For Alpine Linux (in Docker): `apk add gcc musl-dev libffi-dev`. For other systems, consult `pynacl`'s documentation for prerequisites.
Upgrade
Version history
0.2.1latest on PyPI · released Sep 11, 2024
Audit
Dependencies
pynaclrequiredProvides the underlying Ed25519 cryptographic primitives. Replaced 'ed25519' dependency in v0.2.0 for Python 3.12+ compatibility.
zipprequiredMinor dependency for package metadata introspection.
Agent activity
45 hits · last 30 days
node
42
OpenAI (training)
1
Resources
nkeys — pip install nkeys · libregistry