<filewiki_vars>
title=Details
menu=$title
</filewiki_vars>


# 5. Messages Details

## 5.1 Connection Registration

The commands described here are used to register a client connection
with an DarkChannel server. With client we mean "connector" and with
server we mean "listener" in the following sections.

A DarkChannel node, be it a channel server or a client, MAY have a
listener as well as one or more connectors instantiated. This allows
every DarkChannel node to connect to one another.

Every DarkChannel listener and connector MUST support the messages
WELCOME and HELLO to be able to properly setup a DarkChannel
connection between nodes. The other messages MAY be available,
depending on the listener's or connector's state machine.

### 5.1.1 WELCOME

 * Command: __WELCOME__
 * Parameters: __Product-Name:__ __Service-Name__
 * Blobs: None

The WELCOME message is used by a DarkChannel server to greet a new
client when the connection gets accepted. It's the only message which
gets sent unencrypted and unsigned. It's only purpose is to let the
client know that it's a DarkChannel server listening at the
other end of the connection.

It's parameters MUST be ignored by the receiving client.

Parameters:

 * __Product-Name:__ Always set to "DarkChannel"
 * __Service-Name:__ Either "Channel Server" or "Client"

### 5.1.2 HELLO

 * Command: __HELLO__
 * Parameters: __Product-Name:__ __Service-Name:__
               __Protocol-Version:__  __System-Type__
 * Blobs:
   * __Public-Key__
   * __Signature__

The HELLO message is used by a DarkChannel client to introduce itself
to a freshly connected DarkChannel server after the connection got
accepted and the server sent it's WELCOME message. It's purpose is to
let the server know about the client's capabilities, eg. it's product
name, it's service name, it's protocol version and it's system type.
Last but not least it passes the client's public key to the server.

The HELLO message is used by a server to respond on a HELLO message
from the client. The server informs the client on it's product name,
it's service name, the chosen protocol version and it's system type.
Last but not least it passes the server's public key to the client.

When the HELLO handshake is finished, client and server are able to
sign, verify, encrypt and decrypt data for the other party. Both are
able to recognize each other's identity using the received public key.

Parameters:

 * __Product-Name:__ Always set to "DarkChannel"
 * __Service-Name:__ Either "Channel Server" or "Client"
 * __Protocol-Version:__ Always set to "v1"
 * __System-Type:__ Always set to "Linux/Perl" for the current
   reference implementation

Blobs:

 * __Public_Key:__ The message sender's public key
 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any.

## 5.2 Channel Operations

The commands described here are used to list, join and part channels.

### 5.2.1 LIST

 * Command: __LIST__
 * Parameters: [ __Channel-Pattern__ ]
 * Blobs:
   * [ __Channel-List__ ]
   * __Signature__

The LIST message MAY be sent by the client to list the available
channels on a channel server. It MAY contain a optional channel
pattern to search for.

When a channel server receives a LIST message it MUST send a LIST
message to the requesting client listing the available channels in the
first data blob of the message.

Parameters:

 * __Channel-Pattern:__ The optional channel pattern to search for.
   If no channel pattern is given, all available channels get listed.

Blobs:

 * __Channel-List:__ Optional blob containing all the available channels
   on the channel server.
 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any.

### 5.2.2 JOIN

 * Command: __JOIN__
 * Parameters: __Channel__
 * Blobs:
   * [ __Public-Key__ ]
   * __Signature__

The JOIN message MAY be sent by the client to join a channel on a
channel server. A JOIN message sent by a client does not contain any
public keys.

When a channel server receives a JOIN message it MUST send a JOIN message to the
joining client and the member clients on that channel. The message MUST contain
all the public key material of the clients new to the receiving client.

Parameters:

 * __Channel:__ The channel to join

Blobs:

 * __Public-Keys:__ Optional blob containing all the new public keys
   of channel members unknown to the client. The client MUST import
   these public keys to be able to communicate with these clients.
 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any.

### 5.2.3 PART

 * Command: __PART__
 * Parameters: __Channel__
 * Blobs:
   * __Signature__

The PART message MAY be sent by the client to part a channel on a
channel server.

When a channel server receives a PART message it MUST send a PART message to the
parting client and the member clients on that channel.

Parameters:

 * __Channel:__ The channel to part

Blobs:

 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any

## 5.3 Sending Messages

The main purpose of the DarkChannel protocol is to provide the public
keys for clients to communicate with each other. The RELAY message is
the only message available which actually performs delivery of a text
message from one client to another - the rest just make it possible
and try to ensure it happens in a reliable, structured, secure and
private manner.

### 5.3.1 RELAY

 * Command: __RELAY__
 * Parameters: [ __Channel__ | __KeyId__ ]
 * Blobs:
   * __Message__
   * __Signature__

The RELAY message MAY be sent by the client to a channel of clients or
to the key identifier of a single client on a channel server.

When a channel server receives a RELAY message it MUST send a RELAY
message to all the channel member clients of the specified channel or
to the client with the specified key identifier.

The sender MUST encrypt the message to all the recipients. It MUST
sign the message with a expiry date no longer than a day. The message
MUST NOT be encrypted for the channel server who receives the message.

Parameters:

 * __Channel:__ The channel to relay the message to
 * __KeyId:__ The client to relay the message to

Blobs:

 * __Message:__ The encryped message for the recipients
 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any

## 5.4 Miscellaneous Messages

### 5.4.1 PING

 * Command: __PING__
 * Parameters: __Timestamp__
 * Blobs:
   * __Signature__

The PING message MAY be sent by the client to a channel server.

When a channel server receives a PING request message it MUST send a
PONG reply message to the requesting client. The parameter of the PONG
message MUST be the same as the parameter of the PING message
received.

Parameters:

 * __Timestamp:__ The timestamp of the sender

Blobs:

 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any

### 5.4.2 PONG

 * Command: __PONG__
 * Parameters: __Timestamp__
 * Blobs:
   * __Signature__

When a channel server receives a PING request message it MUST send a
PONG reply message to the requesting client. The parameter of the PONG
message MUST be the same as the parameter of the PING message
received.

Parameters:

 * __Timestamp:__ The timestamp of the associated PING request message

Blobs:

 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any

## 5.5 Server Queries and Commands

### 5.5.1 CHANNELSERVER

 * Command: __CHANNELSERVER__
 * Parameters: __DUMP__ [ __SESSION__ | __CHANNEL__ | __CRYPTO__ | __CONF__ ]
 * Blobs:
   * __Signature__

When a channel server receives a CHANNELSERVER request message it MUST
dump the requested data to dump to the channel server's log file on the
server, if the requesting client is allowed to do so.

A channel server SHOULD require operator priviledges to accept a
CHANNELSERVER request message from a client.

Blobs:

 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any

### 5.5.2 REGISTER

 * Command: __REGISTER__
 * Parameters: __Nick-Name__ __Role__
 * Blobs:
   * __Public-Key__
   * __Signature__

When a channel server receives a REGISTER request message it SHOULD
check the received public key for compliance with it's nick name
policies.  If the the key complies these policies, the channel server
MUST check it's name space reservation for a collision.

If there is no collision, the nick name MAY be assigned to the
requesting client. To do so, the channel server MUST sign the received
public key with it's own key material. The channel server MUST send a
register reply message containing the signed public key to the
requesting client.

A channel server MAY require special priviledges to accept a REGISTER
request message from a client. Most channel server will want to allow
everyone to register nick names.

A channel server MAY restrict the number of register request or the
number of possible nick name registrations depending on it's nick name
policies.

Parameters:

 * __Nick-Name:__ The nick name to register with the channel server
 * __Role:__ The role of the nick name.

Curently known roles are __'nickname'__ and __'operator'__.

Blobs:

 * __Public-Key:__ The nick name key material's public key of
     the requestor
 * __Signature:__ The detached signature of the message without
   the last blob containing the signature and without the last
   blob separator if any
