API

This page describes version 1 of the API.

Copyright 2018-2020 Rivoreo

The SSHOUT API is designed to make uses of a SSH channel, used to implement independent clients.
Since this protocol is based on SSH protocol, it assume the user is already authenticated, and the channel is secure.

This API is in binary packet format. Each packet have its length in its head; fields in all packets are in network byte order.

Packet Header Format

Each packet have a header descripting its length and type; which is in following format:

uint32 length
uint8 type
uint8 data[]

The length field descripts the length of the whole packet, subtracting its own length; thus the length of data field should be length - 1. Packets can be no extra data at all, so the minimum value of length will be 1 for such packets.

Packet types

SSHOUT_API_HELLO 1
SSHOUT_API_GET_ONLINE_USER 2
SSHOUT_API_SEND_MESSAGE 3
SSHOUT_API_GET_MOTD 4
SSHOUT_API_PASS 128
SSHOUT_API_ONLINE_USERS_INFO 129
SSHOUT_API_RECEIVE_MESSAGE 130
SSHOUT_API_USER_STATE_CHANGE 131
SSHOUT_API_ERROR 132
SSHOUT_API_MOTD 133

Handshake

To start the protocol, handshake must be done to make sure the client is connected to a SSHOUT API server, before any other packets; the packets used to handshake are SSHOUT_API_HELLO and SSHOUT_API_PASS, they are, respectively, client to server handshake and server to client handshake.
The client at first send packet SSHOUT_API_HELLO to server; then the server response with packet SSHOUT_API_PASS.
The format of packet SSHOUT_API_HELLO is:

uint8 magic[6]
uint16 version

The magic field is a fixed length string which must be SSHOUT to identify the protocol; the version field is the API version number, currently 1.

The format of packet SSHOUT_API_PASS is:

uint8 magic[6]
uint16 version
uint8 user_name_length;
uint8 your_user_name[user_name_length]

The magic and version fields are in same meaning as in SSHOUT_API_HELLO. Field your_user_name is the user name associated to the public key that authenticated the client by SSH server; field user_name_length is the length of your_user_name.

User names

SSHOUT identify users based only on user names. Each user name must not longer than 32 bytes (USER_NAME_MAX_LENGTH).

Querying On-line users

Packet SSHOUT_API_GET_ONLINE_USER is used to query on-line user from client; then the server responses the request with packet SSHOUT_API_ONLINE_USERS_INFO.
Packet SSHOUT_API_GET_ONLINE_USER does not have any extra data, so it has no format.
The format of packet SSHOUT_API_ONLINE_USERS_INFO is:

uint16 your_id
uint16 count
{
    uint16 id
    uint8 user_name_length
    uint8 user_name[user_name_length]
    uint8 host_name_length
    uint8 host_name[host_name_length]
}[count]

Field your_id is the correponding id number of the user who queried this list.
Field count is number of on-line users.
IDs in this packet are only used to identify connections; it will be recycled after that connection ended.

Sending and receiving message

Send a message is done by using client to server packet SSHOUT_API_SEND_MESSAGE. When a message is received, server to client packet SSHOUT_API_RECEIVE_MESSAGE will be sent from the server.

The format of packet SSHOUT_API_SEND_MESSAGE is:

uint8 to_user_length
uint8 to_user[to_user_length]
uint8 message_type
uint32 message_length
uint8 message[message_length]

Field to_user_length is the string length of the send-to user name, which is in field to_user; the specical user name GLOBAL can be used to indicate a boradcast message.
Field message_type is the message type, see below for available message types.
Field message_length is the actuall length of message, which is message; the message field can contain anything according to message_type.

The format of packet SSHOUT_API_RECEIVE_MESSAGE is:

uint64 time
uint8 from_user_length
uint8 from_user[from_user_length]
uint8 to_user_length
uint8 to_user[to_user_length]
uint8 message_type
uint32 message_length
uint8 message[message_length]

There are 3 extra fields comparing to packet SSHOUT_API_SEND_MESSAGE.
Field time is epoch of UNIX time representing the message sent time of the message.
Field from_user_length is the string length of the send-from user name, field from_user.
All others fields have the same meaning as in packet SSHOUT_API_SEND_MESSAGE.

Message types

The following message types are used in the message_type field of packets SSHOUT_API_SEND_MESSAGE and SSHOUT_API_RECEIVE_MESSAGE:

SSHOUT_API_MESSAGE_TYPE_PLAIN 1
SSHOUT_API_MESSAGE_TYPE_RICH 2
SSHOUT_API_MESSAGE_TYPE_IMAGE 3

The internal format for the type SSHOUT_API_MESSAGE_TYPE_RICH is currently HTML 4.
The type SSHOUT_API_MESSAGE_TYPE_IMAGE indicate the message is a JPEG image.

Server to client status

Server may send status packets to client at any time after handshake.

The SSHOUT_API_USER_STATE_CHANGE packet have following format:

uint8 state
uint8 user_name_length
uint8 user_name[user_name_length]

Field state is the user's state; 0 is off-line, 1 is on-line.
Field user_name_length is the length of field user_name.
Field user_name is the user's name that state changed.

The SSHOUT_API_ERROR packet have following format:

uint32 error_code
uint32 error_message_length
uint8 error_message[error_message_length]

This packet is used to indicate errors in server.
See above for possible values of field error_code.
Field error_message is a human-readable, and possiblely localized error message from server.

Error codes for SSHOUT_API_ERROR

SSHOUT_API_ERROR_SERVER_CLOSED 1
SSHOUT_API_ERROR_LOCAL_PACKET_CORRUPT 2
SSHOUT_API_ERROR_LOCAL_PACKET_TOO_LARGE 3
SSHOUT_API_ERROR_OUT_OF_MEMORY 4
SSHOUT_API_ERROR_INTERNAL_ERROR 5
SSHOUT_API_ERROR_USER_NOT_FOUND 6
SSHOUT_API_ERROR_MOTD_NOT_AVAILABLE 7

Message of the day

Client to server packet SSHOUT_API_GET_MOTD, and server to client packet SSHOUT_API_MOTD.
Packet SSHOUT_API_MOTD will be sent to client right after handshake completes, if such MOTD is available on server; client may also request the latest MOTD by sending SSHOUT_API_GET_MOTD to server; however if MOTD is not available, server will reply packet SSHOUT_API_ERROR with error code SSHOUT_API_ERROR_MOTD_NOT_AVAILABLE.

Packet SSHOUT_API_GET_MOTD does not have any extra data.
The format of packet SSHOUT_API_MOTD is:

uint32 length
uint8 message[length]