Secure E2EE WebSocket

End-to-End Encrypted WebSocket server & client using Starlette, PyNaCl (Ed25519/X25519), and hardware-bound identity.

Features

• End-to-End encryption using X25519 + NaCl Box
• Message signature with Ed25519
• Hardware-bound identity using machine ID (Linux) or IOPlatformUUID (macOS)
• WebSocket-based transport using Starlette ASGI server
• Local client-server simulation

Architecture

Protocol

Cryptographic Flow

The secure protocol ensures:

• Message confidentiality through X25519 encryption
• Message integrity and authenticity through Ed25519 signatures
• Client identification through hardware binding

Security Notes

This is a local prototype and should not be used in production without:

• Persistent secure key storage
• Certificate pinning or trusted key exchange
• Forward secrecy and key rotation
• Server/client authentication and replay protection

Project Structure

secure-e2ee-websocket/
├── client.py           # WebSocket client
├── server.py           # WebSocket server
├── crypto/
│   ├── hardware.py     # Unique HW ID hash
│   ├── persistent.py   # Persistent Keys
│   └── keys.py         # Keypair generator
├── README.md
└── pyproject.toml      # uv compatible env

Quick Start

Install dependencies:

uv venv
uv pip install starlette uvicorn pynacl websockets

Run server:

uvicorn server:app

Run client (in separate terminal):

python client.py

Expected Output

When running the client, you should see:

[*] Fetching server public key...
[*] Received server public key
[*] Sent encrypted ping
[*] Received response type: <class 'bytes'>
[*] Server replied: pong from server

Server output:

[*] Connection accepted
[*] Received data: {"hardware_id": "6e8bf93eb7d17715...
[*] Signature verified successfully
[*] Client said: ping from client
[*] HW ID: 6e8bf93eb7d17715...
[*] Sending encrypted response, 40 bytes
[*] Sent encrypted pong
[*] Connection closed gracefully

License

MIT