{"id":8354,"library":"nkeys","title":"nkeys (Python)","description":"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.","status":"active","version":"0.2.1","language":"en","source_language":"en","source_url":"https://github.com/nats-io/nkeys.py","tags":["NATS","cryptography","ed25519","key management","security","authentication"],"install":[{"cmd":"pip install nkeys","lang":"bash","label":"Install nkeys"}],"dependencies":[{"reason":"Provides the underlying Ed25519 cryptographic primitives. Replaced 'ed25519' dependency in v0.2.0 for Python 3.12+ compatibility.","package":"pynacl","optional":false},{"reason":"Minor dependency for package metadata introspection.","package":"zipp","optional":false}],"imports":[{"symbol":"nkeys","correct":"import nkeys"},{"note":"Required for generating raw Ed25519 keys before encoding them into NATS nkeys format.","symbol":"SigningKey","correct":"from nacl.signing import SigningKey"}],"quickstart":{"code":"import nkeys\nfrom nacl.signing import SigningKey\nimport os\n\n# 1. Generate a raw Ed25519 signing key using PyNaCl\nraw_signing_key = SigningKey.generate()\n\n# 2. Encode the raw key as a NATS user seed (e.g., SU...)\n# The `encode_seed` function combines the raw private key with the NATS prefix.\n# Use nkeys.PREFIX_BYTE_USER for a user key, nkeys.PREFIX_BYTE_ACCOUNT for an account, etc.\nuser_seed_bytes = nkeys.encode_seed(nkeys.PREFIX_BYTE_USER, raw_signing_key.encode())\n\nprint(f\"Generated User Seed (NKEY format): {user_seed_bytes.decode()}\")\n\n# 3. Create an NKEYS KeyPair object from the seed\nkey_pair = nkeys.from_seed(user_seed_bytes)\n\nprint(f\"Public Key (U...): {key_pair.public_key.decode()}\")\n# The private key and seed should be kept secret.\n# The raw private key is a 64-byte Ed25519 private key.\nprint(f\"Private Key (raw hex - keep secret!): {key_pair.private_key.hex()}\")\nprint(f\"Seed (S... NKEY format - keep secret!): {key_pair.seed.decode()}\")\n\n# 4. Example of signing data\ndata_to_sign = b\"Hello NATS! This is a test message.\"\nsignature = key_pair.sign(data_to_sign)\nprint(f\"Signature for data: {signature.hex()}\")\n\n# 5. Verification (a KeyPair created from the public key can verify signatures)\nverifier_key_pair = nkeys.from_public_key(key_pair.public_key)\ntry:\n    verifier_key_pair.verify(data_to_sign, signature)\n    print(\"Signature verified successfully.\")\nexcept Exception as e:\n    print(f\"Signature verification failed: {e}\")\n\n# 6. Secure handling: wipe sensitive key material from memory when no longer needed\nkey_pair.wipe()\nprint(\"Sensitive key material wiped from memory for security.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 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`.","severity":"breaking","affected_versions":">=0.2.0"},{"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).","message":"Installing `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.","severity":"gotcha","affected_versions":"All versions depending on `pynacl` (>=0.2.0)"},{"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.","message":"NATS 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade `nkeys` to version 0.2.0 or higher: `pip install --upgrade nkeys`. This version replaces `ed25519` with `pynacl`, resolving the compatibility issue.","cause":"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.","error":"AttributeError: module 'configparser' has no attribute 'SafeConfigParser'"},{"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.","cause":"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.","error":"Failed building wheel for pynacl (or 'error: command 'gcc' failed with exit status 1')"}]}