CSIM Client-Server TCP Protocol version 0.3


Contents:
1) Definitions
2) General Information
3) Client-Server Packets
3.1) LOGIN Packet
3.2) SRV_LOGIN Packet
3.3) General Packet Description
3.4) ENCRYPTED_DATA Description
4) Client->Server Commands
4.0) REQ_QUERY
4.0.0) CREATE_ALIAS
4.0.1) USER_SEARCH
4.0.2) USER_HISTORY
4.0.3) USER_INFO
4.1) REQ_SEND_MESSAGE
4.2) REQ_ADD_USER
4.3) REQ_CHANGE_STATUS
4.4) REQ_LOGOFF

5) Server->Client Commands
5.0) SRV_CONTACT_LIST
5.1) SRV_RECEIVE_MESSAGE
5.2) SRV_QUERY_REPLY

**************************************************************
Definitions
**************************************************************

XX - One byte (8 bits)
REQ - Command sent from client to server
SRV - Command sent from server to client

**************************************************************
General Information
**************************************************************

1. Administrator'S ID is 00 00 00 00
Group ID are between 00 00 00 01 - 7F FF FF FF
User IDs are between 80 00 00 00 - FF FF FF FF

2. Login process consists of opening a connection with
the server and sending the LOGIN packet. The server
will reply with an SRV_LOGIN packet, followed by
SRV_CONTACT_LIST if the login was successful. It will
close the connection if the login fails.

3. The server will periodically send the SRV_CONTACT_LIST
command, whenever someone's online status changes.

4. Logoff process consists of sending the REQ_LOGOFF packet
and closing the connection with the server.

**************************************************************
Client-Server Packets
**************************************************************

1. LOGIN Packet (Unencrypted)

----------------------------------------------------------
Length | Content | Description
----------------------------------------------------------
4 bytes | XX XX XX XX | User ID
4 bytes | XX XX XX XX | Length of ENCR_C_PUBKEY
variable | ENCR_C_PUBKEY | Client's Public Key, encrypted
| | with Client's password. Some
| | random data will be added to
| | the key before encryption, to
| | make sure that the ENCR_C_PUBKEY
| | is different each time it is sent.

Server will reply with a SRV_LOGIN command, followed by a
SRV_CONTACT_LIST, if the login is succesful and will close
the TCP connection, if it fails.

2. SRV_LOGIN Packet (Unencrypted)
----------------------------------------------------------
Length | Content | Description
----------------------------------------------------------
4 bytes | XX XX XX XX | User ID
4 bytes | XX XX XX XX | Length of ENCR_S_PUBKEY
variable | ENCR_S_PUBKEY | Server's Public Key, encrypted
| | with Client's password. Some
| | random data will be added to
| | the key before encryption, to
| | make sure that the ENCR_S_PUBKEY
| | is different each time it is sent.

3. General Packet Description

----------------------------------------------------------
Length | Content | Description
----------------------------------------------------------
4 bytes | XX XX XX XX | Length of ENCRYPTED_DATA
variable | ENCRYPTED_DATA | Encrypted packet data

4. ENCRYPTED_DATA Description (after decryption):

----------------------------------------------------------
Length | Content | Description
----------------------------------------------------------
2 bytes | 00 01 | Protocol version
4 bytes | XX XX XX XX | Length of decrypted packet
| | (at least 16 bytes)
2 bytes | XX XX | COMMAND_TYPE
4 bytes | XX XX XX XX | Length of BINARY_DATA
| | (can be 0)
variable | BINARY_DATA | Binary data
| | (may be optional)
4 bytes | XX XX XX XX | Length of XML_DATA
| | (can be 0)
variable | XML_DATA | Data in XML format
| | (may be optional)

**************************************************************
Client->Server Commands
**************************************************************

REQ_QUERY
- Asks the server to perform execute a general query. The
server will reply with a SRV_QUERY_REPLY command.

COMMAND_TYPE 0x00 0x00

BINARY_DATA None

XML_DATA Type of the query to execute, along
with parameters.

Supported queries:
CREATE_ALIAS
Description: Asks the server to create a new alias.
Server reply: SRV_QUERY command will contain the
updated contact list

USER_SEARCH
Description: Send a search query to the server.
Server reply: SRV_QUERY command will contain the
search reply

USER_HISTORY
Description: Asks the server to send back the
complete user history.
Server reply: SRV_QUERY command will contain requested
user's history

USER_INFO
Description: Asks the server to send back
information about a specific user
or group.
Server reply: SRV_QUERY command will contain requested
user or group information


REQ_SEND_MESSAGE
- Sends a message through the server to a list of users and/or
groups.

COMMAND_TYPE 0x00 0x01

BINARY_DATA List of 4 byte-long User/Group IDs:
XX XX XX XX
XX XX XX XX
XX XX XX XX
XX XX XX XX
...

XML_DATA Message in XML format

REQ_ADD_USER
- Asks the server for a permission to add a user/group
to the contact list. The server will reply with
SRV_CONTACT_LIST command that will send the updated
contact list. (Note: The request to add the user
to the contact list may be denied, in which case
SRV_CONTACT_LIST command will send only the old
contact list)

COMMAND_TYPE 0x00 0x02

BINARY_DATA List of 4 byte-long User/Group IDs:
XX XX XX XX
XX XX XX XX
XX XX XX XX
XX XX XX XX
...

XML_DATA None

REQ_CHANGE_STATUS
- Notifies the server about the change in user's
online status.

COMMAND_TYPE 0x00 0x03

BINARY_DATA 2-byte status flag
0x00 0x01 - User is ONLINE
0x00 0x02 - User is AWAY

Note: 0x00 0x00 specifies OFFLINE
status, but it cannot be set
with REQ_CHANGE_STATUS command.
Use REQ_LOGOFF instead.

XML_DATA For AWAY status, optional
away XML message

REQ_LOGOFF
- Notifies the server that the client is logging
off. The connection can be closed right after
this packet is sent.

COMMAND_TYPE 0x00 0x04

BINARY_DATA None

XML_DATA None


**************************************************************
Server->Client Commands
**************************************************************

SRV_CONTACT_LIST
- Sends the most current contact list to the client.
This is the first packet that is sent right after
the login packet.

COMMAND_TYPE 0x00 0x00

BINARY_DATA None

XML_DATA Contact List in XML format


SRV_RECEIVE_MESSAGE
- Sends a user message to the client.

COMMAND_TYPE 0x00 0x01

BINARY_DATA XX XX XX XX - Sender's ID

XML_DATA Message in XML format


SRV_QUERY_REPLY
- Sends the result of a REQ_QUERY command to the client.

COMMAND_TYPE 0x00 0x02

BINARY_DATA None

XML_DATA Reply in XML format