ascii-chat
Binary v0.15.83-53-gb711d8720
Library lib/v0.3.2-701-gb711d8720
Video chat in your terminal
Loading...
Searching...
No Matches
ACIP
Network

ascii-chat's binary packet protocol and transport-facing message layer. More...

Files

file  client.c
 ACIP client-side protocol implementation.
file  server.c
 ACIP server-side protocol implementation.
file  acds.h
 ascii-chat Discovery Service (ACDS) Protocol Message Formats
file  acds_client.h
 ACIP client-side protocol library and ACDS client connection API.
file  acds_server.h
 ACIP server-side protocol library and ACDS server utilities.
file  client.h
 ACIP client-side protocol API.
file  server.h
 ACIP server-side protocol API.

Detailed Description

ascii-chat's binary packet protocol and transport-facing message layer.

This module documents the complete ascii-chat binary network protocol, including:

  • Universal packet header structure used by ALL packet types
  • Core protocol negotiation and cryptographic handshake
  • Session communication (messages, media, audio, control)
  • ACIP discovery service protocol (6000-6199 range)

ASCII-CHAT BINARY PROTOCOL ARCHITECTURE

Complete Protocol Overview

  • Transport: TCP (client-server) or custom transports (WebRTC, WebSocket)
  • Packet Format: Binary, little-endian with fixed headers
  • Magic Number: 0xA5C11C4A1 (validates all packet types)
  • Authentication: Ed25519 digital signatures (handshake) or Diffie-Hellman
  • Encryption: XSalsa20-Poly1305 AEAD (after handshake)
  • Integrity: CRC32 checksum per packet payload
  • Client Identification: 32-bit client ID (0 = server, >0 = client)

Universal Packet Structure

ALL packets in ascii-chat (regardless of type) use the same 22-byte header:

Offset Size Field Description
------ ---- ----- -----------
0 8 magic Magic number 0xA5C11C4A1 (spells "ASCIICHAT" in hex)
8 2 type Packet type enum (packet_type_t) - see full range below
10 4 length Payload length in bytes (0 = header-only, max ~2MB)
14 4 crc32 CRC32 checksum of payload (0 if length == 0)
18 4 client_id Client identifier (0=server, 1-9=clients)
22 N payload Payload data (N = length)
------
Total: 22 + payload_length bytes
packet_type_t
packet_type_t
Network protocol packet type enumeration.
Definition packet.h:301

Complete Packet Type System

The ascii-chat binary protocol uses multiple packet type ranges for different purposes:

Type 1: Protocol Version Negotiation

  • PACKET_TYPE_PROTOCOL_VERSION = 1 (version and capabilities exchange)

Types 1000-1203: Cryptographic Handshake & Rekeying

  • 1000-1099: Client hello and crypto capability exchange
  • 1100-1109: Handshake exchange (key exchange, authentication)
  • 1200-1203: Session encryption and rekeying
  • Note: All handshake packets are ALWAYS sent unencrypted (plaintext)

Types 2000-2004: Session Messages

  • 2000: Terminal size updates (width/height changes)
  • 2001: Audio message data
  • 2002: Text message data
  • 2003: Error packets with error codes and messages
  • 2004: Remote logging (bidirectional log forwarding)

Types 3000-3003: Media Frames

  • 3000: ASCII art frames (pre-rendered terminal representation)
  • 3001: Raw RGB image frames
  • 3002: H.265/HEVC encoded video frames
  • 3003: H.264/AVC encoded video frames

Types 4000-4001: Audio Packets

  • 4000: Batched raw audio samples
  • 4001: Batched Opus-encoded audio (pre-compressed)

Types 5000-5008: Control & State

  • 5000: Client capabilities (color, features, etc.)
  • 5001: Keepalive ping packet
  • 5002: Keepalive pong response
  • 5003: Client join notification
  • 5004: Client leave notification
  • 5005: Stream start request
  • 5006: Stream stop request
  • 5007: Clear console command
  • 5008: Server state broadcast to clients

Types 6000-6199: ACIP Discovery Service Protocol

  • 6000-6008: Session management (create, join, leave, lookup)
  • 6009-6010: WebRTC signaling (SDP, ICE candidates)
  • 6020-6023: String reservation (reserve, renew, release)
  • 6050-6051: Ring consensus protocol (future host election)
  • 6060-6068: Host negotiation & migration (dynamic host failover)
  • 6070-6071: Bandwidth testing
  • 6075: Broadcast acknowledgment
  • 6100-6104: Ring consensus statistics and election
  • 6190-6199: Discovery keepalive ping and error responses

Encryption & Handshake Flow

Unencrypted Phase (connection establishment):

  1. Client sends CRYPTO_CLIENT_HELLO (type 1000)
  2. Server sends CRYPTO_CAPABILITIES (type 1100)
  3. Exchange keys via CRYPTO_KEY_EXCHANGE_INIT/RESP (1102, 1103)
  4. Authentication via CRYPTO_AUTH_CHALLENGE/RESPONSE (1104, 1105)
  5. Server sends CRYPTO_HANDSHAKE_COMPLETE (type 1108)

Encrypted Phase (after handshake):

  • All non-handshake packets are encrypted with XSalsa20-Poly1305
  • Handshake packets are NEVER encrypted (protocol compliance)
  • Rekeying packets (types 1201-1203) use old keys, then switch to new keys

ACIP (ASCII-Chat IP) Discovery Service

ACIP is the discovery protocol layer that runs on top of the core binary protocol. It enables P2P session discovery without a central server (decentralized mode).

ACIP Use Cases:

  • Creating sessions with unique string identifiers (e.g., "blue-mountain-tiger")
  • Looking up and joining sessions by string
  • WebRTC offer/answer exchange for peer negotiation
  • Dynamic host election when original host disconnects
  • Participant notification when others join/leave

ACIP Transport:

  • Default TCP port: 27225 (configurable for ACDS - ASCII-Chat Discovery Service)
  • Uses same packet_header_t structure as all other packets
  • Supports Ed25519 identity signatures for authentication
  • Optional password protection per session

Integration with Other Modules

Version Information

  • Protocol Version: 1.0
  • Release Date: January 2026
  • Status: Production
  • Packet Format Stability: Version-locked to 1.0 (no breaking changes)
Note
The packet_header_t structure is identical for ALL 200+ packet types. The only difference is the 'type' field and payload structure.
CRC32 is computed over payload bytes ONLY (not including the 22-byte header).
This file documents protocol architecture. Detailed packet definitions are in network/packet.h (packet_type_t enum). Detailed ACIP message structures are in network/acip/acds.h.
Author
Zachary Fogg me@zf.nosp@m.o.gg
Date
January 2026
Version
1.0 (Complete Binary Protocol Documentation)