x25519

Common errors

• AttributeError: module 'x25519' has no attribute 'X25519PrivateKey'

  cause Attempting to use `cryptography` library's object-oriented API with the `x25519` pure Python package.
  fix The `x25519` package uses functional calls (e.g., `x25519.scalar_base_mult`). If you intended to use the `cryptography` library, ensure it's installed (`pip install cryptography`) and import `from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey`.

• TypeError: 'bytes' object cannot be interpreted as an integer

  cause Incorrect input type for cryptographic functions. X25519 operations typically expect 32-byte `bytes` objects for keys.
  fix Ensure all key material (private keys, public keys) are precisely 32-byte `bytes` objects. Avoid passing strings or integers directly.

Warnings

• breaking The GitHub repository linked in the PyPI metadata for this library is non-existent (404 Not Found), indicating the project is likely unmaintained and should not be used for new development.
  Fix: Migrate to a actively maintained and audited cryptography library, such as `cryptography` (e.g., `cryptography.hazmat.primitives.asymmetric.x25519`).
• gotcha Pure Python cryptographic implementations, especially for operations like X25519, can be vulnerable to timing attacks due to variations in execution time based on input values. This can leak sensitive information.
  Fix: For security-critical applications, prefer native code implementations (like those in `cryptography` which wraps OpenSSL) that are designed for constant-time execution.
• gotcha This `x25519` PyPI package is a distinct, pure-Python implementation and is NOT the X25519 implementation provided by the `cryptography` library, which is the standard and recommended choice for robust cryptography in Python.
  Fix: If you intend to use the widely-accepted and audited X25519 implementation, install `cryptography` (`pip install cryptography`) and import from `cryptography.hazmat.primitives.asymmetric.x25519`.
• gotcha The raw shared secret derived from X25519 should generally not be used directly as an encryption key. It should be processed through a Key Derivation Function (KDF) like HKDF to produce a strong, fixed-length key suitable for symmetric encryption.
  Fix: After obtaining the `shared_secret`, apply a KDF (e.g., from `cryptography.hazmat.primitives.kdf.hkdf`) to derive a secure symmetric key.

Install

• pip install x25519 Install latest version

Imports

• scalar_base_mult
  wrong:

  from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey

  correct:

  import x25519
  public_key = x25519.scalar_base_mult(private_key)

  This library is a separate, pure-Python implementation, not part of the 'cryptography' project.
• scalar_mult
  wrong:

  private_key.exchange(peer_public_key)

  correct:

  import x25519
  shared_secret = x25519.scalar_mult(private_key, peer_public_key)

  The API for this `x25519` package uses functional calls, not object methods like the `cryptography` library.

Quickstart

This quickstart demonstrates how to generate X25519 private and public keys and then derive a shared secret using the `x25519` library's `scalar_base_mult` and `scalar_mult` functions. Ensure private keys are truly random bytes in a real-world scenario.

import x25519
from binascii import hexlify

# Generate a 32-byte private key (randomly in a real application)
private_key_a = b'\x01' * 32 # Example: should be randomly generated
private_key_b = b'\x02' * 32 # Example: should be randomly generated

# Derive public keys
public_key_a = x25519.scalar_base_mult(private_key_a)
public_key_b = x25519.scalar_base_mult(private_key_b)

print(f"Public Key A: {hexlify(public_key_a).decode()}")
print(f"Public Key B: {hexlify(public_key_b).decode()}")

# Compute shared secrets
shared_secret_ab = x25519.scalar_mult(private_key_a, public_key_b)
shared_secret_ba = x25519.scalar_mult(private_key_b, public_key_a)

print(f"Shared Secret A->B: {hexlify(shared_secret_ab).decode()}")
print(f"Shared Secret B->A: {hexlify(shared_secret_ba).decode()}")

assert shared_secret_ab == shared_secret_ba
print("Shared secrets match!")