penum-gateway

A minimal, production-grade exit gateway node for the Penum decentralized transport privacy protocol.

What This Repository Is

This repository implements a single penum-gateway node. It is a functional component of the Penum protocol designed to perform:

• Fixed-size packet reception: Every inbound request must be exactly 1024 bytes.
• Final-layer decryption: Authenticates and decrypts the final encryption layer using ChaCha20-Poly1305.
• Exit policy enforcement: Validates destination addresses against allowed ports.
• Outbound connection: Establishes TCP connection to destination and forwards plaintext payload.
• Response handling: Reads response, pads to 1024 bytes, encrypts, and returns upstream.

Note: This repository is NOT a client (it cannot create packets), NOT a relay node (it is the final hop), and NOT a full network coordinator.

What This Gateway Knows (and Does Not Know)

The gateway necessarily sees:

• Immediate Sender: The IP address of the previous relay node.
• Final Destination: The IP address and port of the destination server (extracted from decrypted header).
• Payload Content: The plaintext data being sent to the destination.

The gateway is cryptographically prevented from seeing:

• Original Client: The gateway only knows the immediate upstream relay, not the client's IP.
• Entry Relay: The gateway does not know which entry relay was used.
• Middle Relays: The gateway only knows the previous hop, not the full path.

Exit Policy

The gateway enforces a static exit policy defined in config.rs. By default, only ports 80 and 443 are allowed. Requests to other ports are rejected silently.

Execution Flow

1. Accept Connection: TCP listener accepts inbound connection from relay.
2. Handshake: Performs X25519 ephemeral key exchange and derives session key via HKDF.
3. Read Packet: Reads exactly 1024 bytes from inbound stream.
4. Decrypt: Decrypts final layer using session key.
5. Validate: Checks destination port against exit policy.
6. Forward: Opens TCP connection to destination and sends payload.
7. Receive: Reads response from destination (up to 988 bytes).
8. Pad & Encrypt: Pads response with random data to 1024 bytes, encrypts with same session key.
9. Return: Sends encrypted response back to relay.
10. Cleanup: All session state, including keys and buffers, is dropped immediately.

Packet Constraints

• Fixed Size: All packets are 1024 bytes. Rejection occurs if the size is incorrect.
• Random Padding: Unused space in response packets is filled with random data, not zeros.
• Single Request/Response: Each connection handles exactly one request and one response.

Status

Current status: Experimental / Research Implementation.

Implemented:

• TCP transport
• X25519 Handshake with HKDF-SHA256
• ChaCha20-Poly1305 AEAD
• Exit policy enforcement
• Fixed-size packet handling
• Random padding for responses

Intentionally out of scope:

• Client packet construction
• Multi-hop relay logic
• Session reuse
• Streaming responses

Security Properties

• Ephemeral Keys: New X25519 keypair for every connection.
• Forward Secrecy: Session keys cannot be recovered after connection closes.
• Fail-Silent: Errors result in silent connection closure, no error messages sent.
• No Logging: No traffic logs, payload inspection, or metadata collection.
• Stateless: No state preserved between connections.