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