| 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] | |