DirectConnect TNG

A call for a new protocol

Draft, version 0.4 December 3rd, 2003
By Jan Vidar Krey <janvidar at extatic dot org>

1.0 Introduction

FIXME: See the old specification on why we need a new protocol.

1.1 A proposed solution

I propose creating a totally new system around on the DC model with the concept of clients and hubs. The goal is that existing clients should be able to adapt this new protocol without massive rewrites due to completely different designs.

The protocol is more generic and extensible for use in other applications like Instant Messaging, IP telephony, video streaming etc.

1.2 Status of this document

This document is a draft.

1.3 Thanks to

Special thanks to Sandos, BlackClaw and Sedulus and all the users of the DC Devel mailinglist and hub.

2.0 Language and standards

2.1 Messaging

This is a text based protocol, much like FTP, SMTP, HTTP, etc. The protocol itself is using standard US ASCII and supports internationalized strings with UTF-8.

All commands are four bytes in length (fourcc) for easy parsing and low bandwidth.

Commands are transmitted as lines separated by the common Internet standard; CRLF (carriage return and linefeed), which means it should be easy to debug without special tools and easy to script implementations. Some special characters are escaped using C-style escaping or double quotes.

The connecting party (client) will always talk first when connected (this to make automated scans difficult).

All error/info strings from special commands should not exceed 50 bytes.

2.2 Address notation

The server (hub) does not listen to a standard or recommended port. All network nodes should therefore be addressed with both their IP and port. IPv4, IPv6 addressing is allowed for clients. Note: IPv4 and IPv6 does in most cases not mix.

The addresses should be on this format:

2.3 New concepts

2.3.1 GUID

A new concept GUID, which is short for "Globally Unique ID". Each node (client and server) has a unique ID.
All references in the protocol use this ID instead of nicknames or IP. You can join multiple hubs with multiple nicknames, and still be interpreted as one user.

The GUID is calculated as an MD5 (128 bit) hash of the Ethernet MAC address being use plus a timestamp to ensure unicity.
This GUID is usually represented as a 32 byte text string hexadecimal style.
The GUID is created the first time the client is run, and it will be stored and used for each session later. The user will be identified by this ID across different hubs and names. All login systems (registered users, etc) will use the GUID to identify a user.

2.3.2 Channels

Another concept is "channels", similar to to IRC-channels or "a chat room", which basically is a group of users who will receive chat messages.

Unlike IRC, the server operators are operators in all channels. The channels can not be generated ad-hoc, which means that the server admin controls the channels.

2.4 New server functionality

Server linking is handled transparently by the server, thus there is no need to do send special search commands to allow this.
The server may drop link messages for whatever reason (network, cpu, memory, etc).

The server has enhanced flow control mechanisms. For example a hub can send a "PING" requesting a "PONG" from each client to determine wether the host is responding within a reasonable amount of time or not. If it doesn't it should be disconnected.
Also the hub can disconnect clients if they are message "flooding", or if their send queue is filling up. The search commands can optinally by the hub be sent to linked hubs, but they may just aswell be discarded if the hub is reaching some bandwidth, memory or CPU usage limit.

3.0 Command Reference

3.1 Overview

3.2 Details

AUTH Authentication

Syntax: AUTH
Context: Sent by server to prompt client for a username/GUID. Only valid during the login phase. The client should respond by sending the INFO-command.
Errors: Auth is sent once more if an error occurs (nickname taken etc).

AXSD

Syntax: AXSD reason
Context: Sent by server to client normally during login to say "Access denied".
Parameters:
reason
Text string describing the reason why the connection is being refused.
Example: AXSD Your IP is banned
See also: RDIR

CHAN

Syntax: CHAN ID name
Context: Sent by server during login
Parameters:
ID
4 byte ID of a chat room
name
name of chat room (UTF-8)
Example: CHAN 0000 "Public Chat Room"

CHER

Syntax: CHER ID reason
Context: Sent by server to client to indicate that you cannot join a channel.
Example: CHER 09A1 Too many channels

CHOK

Syntax: CHOK ID
Context: Received as a response to a JOIN- request.
Example: CHOK CHOK 0000

CMSG

Syntax: CMSG ID message
Context: Sent at any time after login
Errors: If an error occurs, the message is not relayed.
Example: CMSG 0000 Hello world :)

CONN

Syntax: CONN GUID address protocol
Context: Sent by a client to the server. This is a request for the client with the specified GUID to connect to the specified address using the specified protocol
Parameters:
GUID
Globally unique ID for the user you want to connect to
address
Standard address notation for your client.
protocol
A p2p protocol handler to use (examples: DCTNG/1.0, HTTP/1.1 etc)
See also: RCON

DCNG

Syntax: DCNG version
Context: Command sent from the client to the server to initialize the protocol directly after connection.
Parameters:
version
a string representing the protocol version requested by the client
Errors: If protocol is not supported by server it will disconnect.
Example: DCNG 1.0

FULL

Syntax: FULL
Context: Server to client, during initial handshake to indicate that the hub is full. The hub may also send a RDIR (redirect) before disconnecting the client
See also: RDIR

INFO

Syntax: INFO GUID nick bytes slots hubs mode flags description
Context: Sent by the client to the server describing the client connected. This message is normally relayed to all other connected clients. Can be sent at any time after login, and must be sent after the receiving the AUTH command during login.
Parameters:
GUID
The globally unique ID

nick
The nickname to use for this user

bytes
Number of shared bytes (64bit integer)

slots
The number of possible simultaneous downloads from this host (slots)

hubs
The number of hubs this host is connected to

mode
The network operation mode of the client. A one byte character: '0'=Active mode, '1'=Passive mode, '2'=Proxy mode

desc
User specified description

See also: AUTH  LIST  OPER 

JOIN

Syntax: JOIN ID
Context: Sent by client at any time after login to join a channel.
Errors: If you are not able to join channel the command CHER is returned
Example: JOIN 0A21

LIST

Syntax: LIST
Context: The client can obtain a list of clients. The server will reply with a series of INFO-commands from the server side, followed by the OPER-command.
See also: INFO  OPER 

NAME

Syntax: NAME name
Context: Sent by server to client to specify the server name.
Parameters:
string
name of the hub. This string should not exceed 50 bytes.

Example: NAME My little hub

OPER

Syntax: OPER GUID[,GUID[,...]]
Context: Sent by the server to client and notifies about server operators. This will be sent during login and if the operator list changes (for example if an operator logs in).
Parameters:
GUID[,GUID[,...]]
A list of GUIDs for users that are operators on the hub

PART

Syntax: PART ID
Context: Sent by client to leave a channel
Example: PART 0000

PASS

Syntax: PASS data
Context: This command is sent by the server and is a password request. The password should be MD5 hashed with this nonce (which is random data) to prevent playback attacks and password cracking. The password is hashed and sent back with the PASS-command. Th
Parameters:
data
This command is sent by the server and is a password request. The password should be MD5 hashed with this nonce (which is random data) to prevent playback attacks and password cracking. The password is hashed and sent back with the PASS-command. The

PING

Syntax: PING data
Context: Sent by the server to determine if a client is responding within a reasonable amount of time. The client must reply with the PONG command.
Parameters:
data
Data to be returned by PONG

Errors: If server doesn't get an answer, the connection is disconnected.
See also: PONG 

PONG

Syntax: PONG data
Context: Reply to the PING request by server.
Parameters:
data
data gotten from the PING request

RCON

Syntax: RCON GUID GUID
Context: Request a CONN-request by another client.
Parameters:
GUID
Globally unique ID for the user you want to connect to

GUID
Your GUID

See also: CONN 

RDIR

Syntax: RDIR address
Context: Sent by server to client to redirect a client to another hub. This can be sent at any time by the server. The server should disconnect the connection after sending this command.
Parameters:
address
Address to redirect to (IPv4, IPv6 or DNS name with port)

Example: RDIR my.alternate.server.example.com:9121
See also: FULL 

RPLY

Syntax: RPLY GUID ID data
Context: Sent as a search reply for a passive search by a client via the server to the client who initiated the search.
Parameters:
ID
Search track ID

SRCH

Syntax: SRCH Destination ID mimetype[,mimetype[,mimetype]] size pattern
Context: Sent by client to server to perform a search. The message is relayed to all other clients. This message can only be sent after a successful login
Parameters:
Destination
The destination of the search result, can be two things: "Hub:GUID" for passive searches or standard address notation for active searches (replied by UDP).
ID
A 4 character alphanumeric ID which should be used by clients to track results and which search request it is a reply to.
mimetype
Comma separated list of mimetypes (RFC 2045, 2046).
Currently wildcards are added to the mimes similar to HTTP encoding types. Which means you can do a search for "*/*" which means everything, or "video/*" which means any video type.
size
  1. >size - Greater or equal
  2. <size - Less or equal
  3. size - exact size match
  4. !size - any size, except specified size
  5. size1-size2 - anything between the two sizes (note: size1 < size2)
  6. size,size[,size] - A list of exact sizes to match, maximum entries)
pattern
The search pattern is the rest of the string, so no characters (except CRLF) needs to be escaped.

The first four characters (prefix) followed by a colon, specifies what kind of search should be performed.

Here is a list of supported prefixes:
FILE Search for match in filename only
PATH Search for match in filename with full path
SHA1 Search for file with exact SHA1 match

See also: RPLY