SecureChannel - A Secure Communication Application

Course

ENCS4320 - Applied Cryptography Birzeit University

Team Members

• Student 1: Khaled Bani Odeh
• Student 2: Mohammad Abdallah

Project Overview

SecureChannel is a secure communication application implemented in Python.

The project allows two parties, a client and a server, to communicate securely over a TCP connection. Before sending application messages, both parties perform a secure handshake using X25519 key exchange and PSK-based authentication. After the handshake, all messages are encrypted and authenticated using ChaCha20-Poly1305 AEAD.

The main goal of this project is to implement modern cryptographic primitives from scratch and combine them into a secure protocol that provides confidentiality, integrity, authenticity, associated data authentication, and replay protection.

Implemented Features

• SHA-256 hash function
• HMAC-SHA256
• HKDF-SHA256
• ChaCha20 stream cipher
• Poly1305 MAC
• ChaCha20-Poly1305 AEAD
• X25519 key exchange
• PSK-authenticated handshake
• Session key derivation
• Secure message encryption and decryption
• Associated Data authentication
• Replay protection using sequence numbers
• Reordered message detection
• TCP client/server secure chat
• Bonus: file transfer using chunked AEAD

Repository Files

SecureChannel/
│
├── sha256.py
├── hmac_sha256.py
├── hkdf.py
├── chacha20.py
├── poly1305.py
├── chacha20_poly1305.py
├── x25519.py
├── handshake.py
├── secure_message.py
├── chat_common.py
├── server.py
├── client.py
├── file_transfer.py
│
├── test_sha256.py
├── test_hmac_sha256.py
├── test_hkdf.py
├── test_chacha20.py
├── test_poly1305.py
├── test_chacha20_poly1305.py
├── test_x25519.py
├── test_handshake.py
├── test_secure_message.py
├── test_file_transfer.py
│
└── README.md

Requirements

This project uses only standard Python libraries.

Recommended Python version:

Python 3.10 or newer

No external cryptographic libraries are required to run the main implementation.

How to Run the Tests

From the project directory, run all tests using:

python -m unittest discover -v

Or run a single test file:

python test_sha256.py
python test_hmac_sha256.py
python test_hkdf.py
python test_chacha20.py
python test_poly1305.py
python test_chacha20_poly1305.py
python test_x25519.py
python test_handshake.py
python test_secure_message.py
python test_file_transfer.py

How to Run the Secure Chat

Open two terminals in the project directory.

Terminal 1 - Start the Server

python server.py

The server will ask for a shared PSK.

Example:

Enter shared PSK: my-secret-password

Terminal 2 - Start the Client

python client.py

The client must enter the same PSK.

Example:

Enter shared PSK: my-secret-password

After the handshake succeeds, both sides can exchange secure encrypted messages.

To close the chat, type:

exit

Protocol Design Summary

SecureChannel has two main phases:

1. Handshake phase
2. Secure messaging phase

Phase 1: Handshake

During the handshake, the client and server do the following:

1. Each side generates an ephemeral X25519 private/public key pair.
2. The client sends its identity and ephemeral public key.
3. The server sends its identity and ephemeral public key.
4. Both sides build the same handshake transcript.
5. Both sides compute the same shared secret using X25519.
6. Both sides authenticate the transcript using HMAC-SHA256 with a pre-shared key.
7. If HMAC verification fails, the connection is aborted.
8. HKDF-SHA256 derives directional session keys and nonce bases.

Handshake Transcript

The transcript contains:

protocol version
client identity
server identity
client ephemeral public key
server ephemeral public key

Each variable-length field is encoded with a length prefix to avoid ambiguity.

The transcript is authenticated using:

HMAC-SHA256(PSK, transcript)

This prevents man-in-the-middle attacks because an attacker cannot modify the exchanged public keys or identities without invalidating the HMAC tag.

Key Schedule

After X25519 produces the shared secret, HKDF-SHA256 derives the session material.

HKDF-Extract:

PRK = HMAC-SHA256(PSK, shared_secret)

HKDF-Expand uses the transcript hash as context information.

The output keying material is split into:

client_to_server_key: 32 bytes
server_to_client_key: 32 bytes
client_nonce_base: 12 bytes
server_nonce_base: 12 bytes

Using separate keys for each direction prevents the client and server from using the same encryption key in both directions.

Phase 2: Secure Messaging

After the handshake, every message is protected using ChaCha20-Poly1305 AEAD.

Each secure message contains:

header
ciphertext
tag

The header is plaintext, but it is authenticated as Associated Data.

Message Header

The message header contains:

protocol version
message type
sender identity
sequence number

The header is not encrypted, but any modification to the header causes authentication failure because the header is used as AAD.

Nonce Construction

Each direction has its own 12-byte nonce base.

For each message, the nonce is built from:

nonce_base XOR sequence_number

The sequence number is strictly increasing, which makes each nonce unique for the same key.

Replay Protection

The receiver keeps track of the next expected sequence number.

A message is accepted only if:

received_sequence_number == expected_sequence_number

If an old message is replayed, or if messages arrive out of order, the receiver rejects the packet.

Tampering Protection

ChaCha20-Poly1305 authenticates:

AAD/header
ciphertext
length fields

The receiver rejects the message if:

• the header is changed
• the ciphertext is changed
• the authentication tag is changed
• the sequence number is replayed or reordered

Bonus: File Transfer with Chunked AEAD

The bonus feature supports file transfer by splitting a file into chunks.

Each file chunk is encrypted and authenticated separately using ChaCha20-Poly1305 AEAD.

Each file chunk header contains:

protocol version
message type = file chunk
sender identity
sequence number
filename
chunk index
total chunks
original file size

This allows the receiver to detect:

• modified file metadata
• modified ciphertext
• replayed chunks
• reordered chunks
• missing chunks
• file size mismatch

Security Notes

• Real PSKs should not be committed to GitHub.
• The PSK is entered locally when running the client and server.
• Ephemeral X25519 keys are generated for each session.
• Different directional keys are used for client-to-server and server-to-client traffic.
• Sequence numbers are used to prevent nonce reuse, replay, and reordering.
• AAD is used to authenticate plaintext headers.

Implemented Test Vectors

The repository includes tests and known test vectors for:

• SHA-256
• HMAC-SHA256
• HKDF-SHA256
• ChaCha20
• Poly1305
• ChaCha20-Poly1305 AEAD
• X25519

The tests also include protocol-level checks for:

• handshake authentication
• wrong PSK rejection
• modified transcript rejection
• secure message encryption/decryption
• replay protection
• reordered message rejection
• header tampering rejection
• bonus file transfer tampering checks

AI Usage Statement

AI tools were used as a learning and support tool during the project.

They were used for:

• understanding and organizing the project requirements
• improving code comments and readability
• organizing the repository structure
• preparing README wording
• explaining implementation steps
• debugging ideas and checking clarity

The team reviewed the implementation and is responsible for understanding, explaining, testing, and defending every part of the submitted project during the oral discussion.

Individual Contribution Statement

Student 1: Khaled Bani Odeh - ID: 1230571

• Worked on implementing and testing the cryptographic primitives.
• Worked on SHA-256, HMAC-SHA256, HKDF-SHA256, ChaCha20, Poly1305, ChaCha20-Poly1305 AEAD, and X25519.
• Helped design and implement the handshake logic, including transcript construction, HMAC authentication, and HKDF key derivation.
• Helped implement the secure messaging layer using AEAD, AAD, sequence numbers, and replay protection.
• Helped implement the TCP client/server secure chat.
• Helped implement the bonus file transfer mode using chunked AEAD.
• Added and reviewed test vectors and protocol tests.
• Helped prepare the README, project structure, and final documentation.

Student 2: Mohammad Abdallah - ID: 1230096

• Worked on implementing and testing the cryptographic primitives.
• Worked on SHA-256, HMAC-SHA256, HKDF-SHA256, ChaCha20, Poly1305, ChaCha20-Poly1305 AEAD, and X25519.
• Helped design and implement the handshake logic, including transcript construction, HMAC authentication, and HKDF key derivation.
• Helped implement the secure messaging layer using AEAD, AAD, sequence numbers, and replay protection.
• Helped implement the TCP client/server secure chat.
• Helped implement the bonus file transfer mode using chunked AEAD.
• Added and reviewed test vectors and protocol tests.
• Helped prepare the README, project structure, and final documentation.

References

• FIPS 180-4: Secure Hash Standard
• RFC 2104: HMAC
• RFC 5869: HKDF
• RFC 8439: ChaCha20, Poly1305, and ChaCha20-Poly1305 AEAD
• RFC 7748: X25519
• ENCS4320 Final Project Document

Important Note

This project is for educational purposes as part of ENCS4320 Applied Cryptography.