ZMQ Authentication and Integrity

Simple Embedded Security course project for protecting ZeroMQ traffic with:

• CURVE for client/server authentication
• HMAC-SHA256 for message-level integrity
• REQ/REP for a small client/server test setup

The project shows that a trusted client can send a message, while tampered messages, untrusted clients, and plain non-CURVE clients are rejected.

Project Structure

src/            Python modules for keys, HMAC, protocol, client, and server
scripts/        Commands for key generation, manual run, and demo scenarios
tests/          Unit and integration tests
docs/           Research notes and evaluation
outputs/        Generated keys and demo artifacts

Setup

Run these commands from the zmq-auth-integrity folder.

Windows:

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

Linux/macOS:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Run Tests

Windows:

.venv\Scripts\python.exe -m pytest

Linux/macOS:

.venv/bin/python -m pytest

Expected result:

10 passed

Run The Demo

The demo runs all important scenarios:

1. valid authenticated client
2. tampered message
3. unauthorized CURVE client
4. plain client without CURVE

Windows:

.venv\Scripts\python.exe scripts\demo.py

Linux/macOS:

.venv/bin/python scripts/demo.py

Expected output:

PASS: valid authenticated client accepted
PASS: tampered message rejected
PASS: unauthorized client rejected
PASS: plain client rejected

Manual Client/Server Run

Generate CURVE keys:

.venv\Scripts\python.exe scripts\generate_keys.py

Start the secure server in terminal 1:

.venv\Scripts\python.exe scripts\run_server.py

Send a client message in terminal 2:

.venv\Scripts\python.exe scripts\run_client.py PING

Example response:

{'received': {'command': 'PING'}, 'status': 'ok'}

How It Works

The server and client both have ZMQ CURVE key pairs. The server only trusts client public keys placed in the trusted client directory.

Each message is a JSON envelope:

{
  "payload": {
    "command": "READ_TEMP",
    "device": "sensor-1"
  },
  "timestamp": 1781190000.0,
  "nonce": "unique-message-id",
  "hmac": "base64-hmac-sha256"
}

The HMAC is calculated over payload, timestamp, and nonce. If any protected field changes, verification fails.

Client                          Server
  |                               |
  | -- CURVE authenticated link ->|
  |                               |
  | -- JSON payload + HMAC ------>|
  |                               | verify HMAC
  |                               | check nonce
  |<-- signed JSON response ------|

Security Notes

• CURVE authenticates peers and protects the ZMQ transport.
• HMAC demonstrates explicit message-level integrity.
• The nonce store rejects duplicate message IDs during one server run.
• This is a course demo, not production key-management software.