Technical Documentation

Deep dive into SonarLink's architecture, security, and performance

Architecture Overview

SonarLink implements a secure, offline file transfer system using acoustic transmission as the transport layer.

Core Components

  • Encryption Engine: AES-256-CFB with HMAC-SHA256 authentication
  • Compression Layer: gzip (level 6) for size optimization
  • Audio Transmission: ggwave library with AUDIBLE_FAST protocol
  • Protocol Handler: Chunking, sequencing, and error detection

Tool Usage & Workflow

SonarLink provides a simple menu-driven interface with 5 main options:

  1. Send text messages: Quick text transmission via audio
  2. Send files: Choose encryption mode (none/AES/RSA) and transmit
  3. Receive: Listen for incoming transmissions and save files automatically
  4. Decrypt received file: Separate decryption step using password or RSA private key
  5. Exit: Close the application

Important: Decryption is a separate manual step, not automatic. The tool can also be used solely for file encryption/decryption without any acoustic transmission.

File Processing Pipeline

1. Original File
Raw file data (X bytes)
→
2. Encryption
+48 bytes overhead
(32-byte HMAC + 16-byte IV)
→
3. Gzip Compression
~60% of encrypted size
(text files)
→
4. Base64 Encoding
~133% of compressed size
→
5. Transmission
120-char chunks via audio

Encryption & Security

Three Encryption Modes

SonarLink offers flexible security options to match your use case:

  • No Encryption: Maximum speed for non-sensitive data
  • AES-256 Symmetric: Fast encryption with password-based key derivation
  • RSA Asymmetric: Public/private key encryption for advanced security scenarios

🔓 No Encryption

  • Fastest transmission speed
  • No password required
  • Best for: Public data, speed tests
  • Security: None - data transmitted in clear

🔐 AES-256 Encryption

Symmetric Encryption

  • 256-bit key size (military-grade)
  • CFB mode for stream cipher capability
  • Password-based key derivation (PBKDF2)
  • Unique IV per transmission
  • HMAC-SHA256 authentication (32 bytes)
  • Best for: Most use cases, single recipient

🔑 RSA Encryption

Asymmetric Encryption

  • Public/private key pairs
  • No shared password needed
  • Recipient generates key pair
  • Sender encrypts with public key
  • Only private key can decrypt
  • Best for: Multiple recipients, no pre-shared secrets

🗜️ Compression

gzip level 6

  • Balance between speed and ratio
  • ~60% compression for text files
  • Reduces transmission time
  • Applied before Base64 encoding
  • Works with all encryption modes

⚠️ Security Best Practices

Choosing Encryption Mode:

  • No Encryption: Only for non-sensitive, public data
  • AES-256: Best for most scenarios with strong passwords (16+ characters)
  • RSA: When you can't share passwords beforehand or need multiple recipients

General Guidelines:

  • Controlled Environment: Transmit in physically secure locations
  • Critical Data: Use double encryption for extremely sensitive files (encrypt before SonarLink)
  • Verification: Always verify transmission integrity (HMAC for AES mode)
  • Unique Passwords: Use different passwords for different transmissions (AES mode)

Audio Protocol Specifications

Sample Rate
48,000 Hz
Protocol
AUDIBLE_FAST (ID: 1)
Chunk Size
120 characters
Max Payload
~140 bytes per chunk
Inter-Chunk Delay
1.0 second
Frequency Range
Audible spectrum

Audio Transmission Characteristics

Advantages:

  • ✅ Covert transmission - difficult to detect visually
  • ✅ Plausible deniability - can be disguised as normal audio
  • ✅ Works through barriers (walls, doors)
  • ✅ No line-of-sight required
  • ✅ Censorship resistant

Considerations:

  • ⚠️ Requires quiet environment for reliability
  • ⚠️ Distance limited (<3 meters optimal)
  • ⚠️ Environmental noise affects success rate
  • ⚠️ Slower than QR code transmission

Optimal Audio Conditions

  • Environment: Quiet room with minimal background noise
  • Distance: Less than 1 meter between devices
  • Volume: 60-80% system volume
  • Hardware: Quality speakers and microphones
  • Battery: Ensure sufficient power for entire transmission

Performance Metrics

Transmission times are calculated based on text files with ~60% compression ratio. Already compressed files (JPG, ZIP, MP3) will have longer transmission times.

Audio Mode Transmission Times

File Size After Encryption After Compression Chunks Time (Audio) Recommended
100 B 148 bytes 88 bytes 1 9 seconds ✅ Excellent
1 KB 1,072 bytes 643 bytes 8 16 seconds ✅ Excellent
5 KB 5,168 bytes 3,100 bytes 35 43 seconds ✅ Excellent
10 KB 10,288 bytes 6,172 bytes 69 1 min 17 sec ✅ Good
20 KB 20,528 bytes 12,316 bytes 137 2 min 25 sec ✅ Good
50 KB 51,248 bytes 30,748 bytes 341 5 min 49 sec ⚠️ Okay
100 KB 102,448 bytes 61,468 bytes 682 11 min 30 sec 🔴 Slow
500 KB 512,048 bytes 307,228 bytes 3,406 56 min 54 sec ❌ Avoid

Understanding Transmission Times & Reliability

Current v1.0 Success Rate: ~39% in typical conditions. Success depends heavily on environmental factors.

  • Optimal conditions: Silent room, devices <1m apart, quality audio hardware → Higher success
  • Challenging conditions: Background noise, poor hardware, distance >1m → Lower success
  • Best practice: Perform 2-3 transmission attempts and verify integrity immediately

For higher reliability: Use shorter distances, better audio equipment, and quieter environments. Consider pre-compressing files and splitting large transfers manually.

System Requirements

Software Requirements

  • Python: 3.8 or higher
  • Operating Systems:
    • Linux (Ubuntu, Debian, Arch, etc.)
    • macOS 10.14+
    • Windows 10/11
  • Dependencies:
    • ggwave (audio transmission)
    • cryptography (encryption)
    • PyAudio or sounddevice (audio I/O)

Hardware Requirements

  • Audio Transmission:
    • Working microphone
    • Working speakers or audio output
    • Recommended: External speakers for better range
  • General:
    • Minimum 512 MB RAM
    • 300 MB disk space (including dependencies)

Quick Installation

# Clone the repository
git clone https://github.com/marianopeluso/sonarlink.git
cd sonarlink

# Install dependencies (requires ~200-300 MB)
pip install -r requirements.txt

# Run SonarLink
python sonarlink.py --help

Note: Dependencies include NumPy (~100 MB), cryptography (~15 MB), ggwave, and PyAudio. Total space required: ~300 MB including all libraries.