uxsp 0.1.0

Universal Exchange Security Protocol — Hybrid Post-Quantum Secure Messaging

UXSP — Universal Exchange Security Protocol

UXSP is a high-security, domain-agnostic messaging protocol designed for the Post-Quantum (PQ) era. It ensures that your data remains private even if an attacker captures it today and attempts to decrypt it later with a powerful quantum computer (Store-Now-Decrypt-Later attack).

---

📋 Prerequisites (System Level)

UXSP relies on the Open Quantum Safe (liboqs) C library for its quantum-resistant primitives. You must install this on your system before the Python package can work.

OS	Installation Command
Ubuntu/Debian	sudo apt install liboqs
Fedora	sudo dnf install liboqs
macOS (Homebrew)	brew install liboqs
Windows	Build from source via liboqs GitHub

---

📦 Installation

UXSP is designed to be lightweight. You only install what you need.

# 1. Base Installation (includes Memory Storage)
pip install uxsp

# 2. Optional: Add Redis support for distributed replay protection
pip install "uxsp[redis]"

# 3. Optional: Add Postgres support for durable audit logging
pip install "uxsp[postgres]"

---

🚀 Crystal Clear Quick Start

This guide demonstrates a complete secure exchange between two peers (Alice and Bob).

1. Identity Setup (Private & Public Keys)

Every participant needs an Identity. This generates both classical (X25519/Ed25519) and PQ (ML-KEM/ML-DSA) keypairs.

from uxsp.core.identity import Identity

# Create Alice's identity
# "NODE-A" is a 'Role' string—you can define any role that fits your project.
alice = Identity.create("Alice", "NODE-A")

# Securely save the identity to a file. 
# The private keys are encrypted with AES-256-GCM using your password.
alice.save("alice.uxsp", password="my_secret_password")

# Export the PublicCard. This is what you share with Bob.
# It contains ONLY public keys and is safe to send over the network.
alice_card = alice.public_card()

2. Establishing the Secure Session (The Handshake)

Alice and Bob must perform a 3-step handshake to verify each other's identity and agree on a shared encryption key.

from uxsp.core.handshake import Handshake

# --- STEP 1: Alice Initiates ---
# Alice uses her private Identity and Bob's PublicCard to start.
hs_init = Handshake.initiate(alice, bob_card)
hello_msg = hs_init.hello_message  # Send this dictionary to Bob

# --- STEP 2: Bob Responds ---
# Bob receives the 'hello_msg' and Alice's 'alice_card'.
# He verifies Alice's signature and establishes his side of the session.
hs_resp = Handshake.respond(bob, hello_msg, alice_card)
ack_msg = hs_resp.ack_message  # Send this back to Alice
bob_session = hs_resp.session   # Bob's session is now ACTIVE

# --- STEP 3: Alice Completes ---
# Alice receives the 'ack_msg' and verifies Bob's signature.
# If verification passes, her session becomes ACTIVE.
alice_session = hs_init.complete(ack_msg, bob_card)

3. Secure Communication

Once the session is active, you can send encrypted data. UXSP manages Sequence Numbers automatically to prevent attackers from reordering or replaying your messages.

# --- Alice Sends ---
message = b"Secret data: 42"
payload = alice_session.encrypt(message) # Returns a dict with ciphertext

# --- Bob Receives ---
# Bob decrypts the payload. If the message was replayed or arrived 
# out of order, UXSP will raise a 'SessionReorderError'.
plaintext = bob_session.decrypt(payload)
print(plaintext.decode()) # Output: Secret data: 42

---

🛠️ Core Components

• uxsp.core.identity: Identity management and encrypted local storage.
• uxsp.core.handshake: The 3-step hybrid mutual authentication engine.
• uxsp.core.session: Stateful encryption with sequence enforcement.
• uxsp.storage: High-performance backends for Replay Protection.

🧪 Testing

Run the full suite to verify your system's liboqs compatibility:

pytest tests/