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:
- IPv4: "n.n.n.n:port"
- IPv6: "[x:x:x:x:x:x:x:x]:port" (According to the RFC 2732 guidelines).
2.3 New concepts
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.
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
- AUTH (Authentication)
- AXSD (Access denied)
- CHAN (Channel list)
- CHER (Channel join error)
- CHOK (Sent by server to notify a client that it joined a channel successfully.)
- CMSG (Send message to channel)
- CONN (Connection)
- DCNG
- FULL (Server full)
- INFO
- JOIN (Join channel)
- LIST (Request userlist)
- NAME (Server name)
- OPER (Operator list)
- PART (Leave channel)
- PASS (Password)
- PING
- PONG
- RCON (Passive connection)
- RDIR (Redirect)
- RPLY (Search reply)
- SRCH (Search)
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). |
| 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 |
| 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" |
| Syntax: |
CHER ID reason |
| Context: |
Sent by server to client to indicate that you cannot join a channel. |
| Example: |
CHER 09A1 Too many channels |
| Syntax: |
CHOK ID |
| Context: |
Received as a response to a JOIN- request. |
| Example: |
CHOK CHOK 0000 |
| 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 :) |
| 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 |
| 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 |
| 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 |
| 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
|
| 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 |
| 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
|
| 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 |
| 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
|
| Syntax: |
PART ID |
| Context: |
Sent by client to leave a channel |
| Example: |
PART 0000 |
| 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
|
| 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
|
| Syntax: |
PONG data |
| Context: |
Reply to the PING request by server. |
| Parameters: |
data
data gotten from the PING request
|
| 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
|
| 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
|
| 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
|
| 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
- >size - Greater or equal
- <size - Less or equal
- size - exact size match
- !size - any size, except specified size
- size1-size2 - anything between the two sizes (note: size1 < size2)
- 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
|