9.3 KiB

Raw Blame History Unescape Escape

AGENTS.md - uTun Development Guide

This file contains essential information for AI coding agents working in the uTun codebase.

📋 Quick Reference

Repository: uTun - Secure VPN tunnel with ETCP protocol
Language: C (C99)
Build System: GNU Autotools (autoconf/automake)
Cryptography: TinyCrypt (AES-CCM, ECC)

🔧 Build Commands

Full Build

./autogen.sh        # Generate configure script (if needed)
./configure         # Configure build
make               # Build everything
make install       # Install (requires sudo)

Partial Builds

cd lib && make      # Build only the library
cd src && make      # Build only the main program
cd tests && make    # Build only tests

Clean Build

make clean          # Clean object files
make distclean      # Clean everything including configure files

🧪 Test Commands

Run All Tests

make check          # Run all tests via automake

Run Specific Test

cd tests/ && ./test_etcp_crypto        # ETCP crypto test
cd tests/ && ./test_etcp_simple        # Simple ETCP test
cd tests/ && ./test_ecc_encrypt        # ECC encryption test

Run Single Test with Debug Info

cd tests/
gcc -I../src -I../lib -I../tinycrypt/lib/include \
    -o my_test test_file.c ../src/*.c ../lib/*.c ../tinycrypt/lib/source/*.c
./my_test

💻 Code Style Guidelines

Naming Conventions

Functions: snake_case - etcp_connection_create(), sc_encrypt()
Types: struct snake_case or typedef: struct secure_channel, sc_context_t
Macros: UPPER_CASE - SC_PRIVKEY_SIZE, DEBUG_ERROR()
Constants: UPPER_CASE - SC_OK, SC_ERR_CRYPTO
Global Variables: Avoid where possible, use static for file scope

Formatting

Indentation: 4 spaces, no tabs

Braces: Same line for functions, new line for control structures:

int function(void) {
    if (condition) {
        do_something();
    }
}

Comments: Primary language is Russian for business logic, English for API docs
Line Length: Aim for 80-100 characters

Include Order

// 1. System headers
#include <stdlib.h>
#include <string.h>

// 2. Library headers
#include "../lib/ll_queue.h"

// 3. Local headers
#include "etcp.h"

Error Handling

Use custom error codes defined in headers (e.g., SC_ERR_INVALID_ARG)
Return negative values for errors, 0 for success

Use DEBUG macros for logging:

DEBUG_ERROR(DEBUG_CATEGORY_ETCP, "Failed to initialize: %s", err);
DEBUG_INFO(DEBUG_CATEGORY_CONNECTION, "Socket created on port %d", port);

🔐 Cryptography Guidelines

Using Secure Channel (secure_channel.h)

// 1. Initialize context
struct SC_MYKEYS my_keys;
// ... fill keys ...
sc_context_t ctx;
sc_init_ctx(&ctx, &my_keys);

// 2. Set peer public key (for key exchange)
sc_set_peer_public_key(&ctx, peer_public_key, 0); // 0 = binary format

// 3. Ready for encrypt/decrypt
sc_encrypt(&ctx, plaintext, plaintext_len, ciphertext, &ciphertext_len);
sc_decrypt(&ctx, ciphertext, ciphertext_len, plaintext, &plaintext_len);

Important Notes

Nonce size: Must be exactly 13 bytes for CCM mode (SC_NONCE_SIZE = 13)
Session key: 16 bytes for AES-128 (SC_SESSION_KEY_SIZE = 16)
Tag size: 8 bytes for authentication (SC_TAG_SIZE = 8)
Error codes: Check return values, negative = error

🏗️ Architecture

Directory Structure

├── lib/                    # Core libraries (uasync, ll_queue, memory pools)
├── src/                    # Main source code
│   ├── utun.c             # Main program entry
│   ├── etcp*.c            # ETCP protocol implementation
│   ├── secure_channel.c   # Cryptography
│   └── tun_if.c          # TUN/TAP interface
├── tests/                 # Test programs
├── doc/                   # Technical Specifications
├── tinycrypt/             # TinyCrypt crypto library
└── net_emulator/          # Network emulator

Key Components

UASYNC: Asynchronous event loop for sockets and timers
LL_QUEUE: Lock-free lockstep queue for packet handling
Memory Pool: Fast allocation for network packets
ETCP: Extended TCP protocol with crypto and reliability
Secure Channel: AES-CCM encryption with ECC key exchange

🐛 Debugging Tips

Enable Debug Output

// In source files, define debug before including headers
#define DEBUG_CATEGORY_YOUR_MODULE 1

Common Build Issues

Missing headers: Check include paths in Makefile.am
Undefined references: Ensure source files are listed in Makefile.am
Link errors: Check function declarations match definitions

Testing Crypto

cd tests/
./test_etcp_crypto      # Should show all tests passing
cd tests/
./working_crypto_test   # Standalone crypto test

📦 Dependencies

Build Dependencies

autoconf, automake, libtool
gcc with C99 support
pthread library
OpenSSL/crypto library (for SHA256)

Runtime Dependencies

TUN/TAP interface support (Linux kernel module)
libcrypto (usually installed by default)
Proper network configuration for testing

📝 Git Conventions

Commit Messages: Use imperative mood, concise (50-72 chars)
Language: Mix of English (technical) and Russian (business logic)
Branching: Use feature branches, merge to master via pull request
Tags: Version tags follow vX.Y.Z format

Example commits:

Fix: Added uasync_t typedef for compilation
Crypto: Fixed CCM nonce size to 13 bytes, all crypto tests passing

🚀 Quick Start for New Features

Add new source file to src/Makefile.am under utun_SOURCES
Add test file to tests/Makefile.am under check_PROGRAMS
Use existing patterns from similar modules
Run make check after changes
Commit with descriptive message in appropriate language

"cp" or "кп" in prompt = do commit and push

Важные дополнения:

Самое важное: при поиске ошибок делай перед правками комит/backup. Всё лишнее что менял при отладке - строго вернуть назад в состояние до моего вмешательства. В итоге в код должно попасть только проверенное исправление и ничего лилшнего!
если в процессе исправлений-доработок возникла нестыковка которая требует сеньезных доработок, остановить и подробно расскажи об этом.
sed для редактирования исходников - запрещено пользоваться!
Проверяй на дублирование кода - не сделано ли это уже в другом месте.
Не делай функций-посредников: лучше сразу вызывать target функцию без вложенных вызовов.
Старайся чтобы функция сделала логически завершенную операцию полностью - это упрощает код и понимание.
нельзя ничего восстанавливать из репозитория не прашивая
Когда пишешь код всегда загружай в контекст и мысленно разберись как работают все функции/струтуры, назначение переменных которые используешь.
Для отладки не printf а DEBUG_*
перед сборкой всегда make clean
прежде чем вносить правки хорошо разберись как должно работать, просмотри все нужные функции полностью, нужно целостное понимание.
при написании кода мысленно анализируй логику работы, думай как сделать проще и удобнее. Проверяй дубликаты и что уже есть, продумай логику до тех пор пока не будет полного понимания

Действия при поиске бага:

создать комит или бэкап всего что меняешь
когда причина бага найдена и устранена - верни всё остальное что менял в исходное состояние
проверь что тесты проходят и всё работает. make clean перед сбркоя обязательно.
если баг не устранён - продолжай поиск или если время заканчивается - верни всё в исходное состояние

тех задания для реализации в каталоге /doc. /doc/etcp_protocol.txt - основной протокол (похож на TCP+QUIC, поддеиживает шифрования, load balancing multi-link, работу а неустойчивых каналах, утилизацию полосы и недопущение перегрузки каналов связи)

реализация в /src/etcp*.c/h

Last updated: 2025-01-20 - After full crypto implementation and testing

9.3 KiB Raw Blame History Unescape Escape