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