Pinto! Protocol

Warning

This page is currently very poorly written, and lacks a lot of details!

The Pinto! Messaging Protocol (PMSG) is the protocol used by Pinto!
The current version (as of writting this, 12.10.2023) has a protocol version number (PVN) of 3

General Information

• Default port is 2407
• The connection takes place on TCP and on UDP (only for calls, they are not documented tho)
• The protocol currently has AES-256 encryption (the key is shared by RSA)
• The protocol data is big endian

Pinto! Server Listing

The Pinto! server listing is a web server that receives "heartbeats" (or pings) from Pinto! servers to show them in one convinient place
All requests/responses are in JSON

Response template from "servers.php"

[
{
	"name":"<the name of the server>",
	"ip":"<the public ip of the server>",
	"port":<the port the server is listening on>,
	"users":<the amount of users currently online>,
	"maxUsers":<the maximum amount of users that can join>,
	"expire":"<the exact time in UTC that the server will time out from the server list, format: YYYY-MM-DD hh:mm:ss>",
	"tags":"<the tags of the server, separated by "," with no space, the ones recognized by the server list are "official", however you can put anything here>"
}
]

Request template to "heartbeat.php":

{
	"name": "<the name of the server>",
	"port": <the port the server is listening on>,
	"users": <the amount of users currently online>,
	"maxUsers": <the maximum amount of users>,
	"tags": "<the tags of the server>"
}

NOTE: The IP of the server is determined by the IP of the requester

Response template from "heartbeat.php":

{
	"status": "<the status or Error>",
	"error": "<the error, if the status is not Error then this key doesn't exist>"
}

Possible (official) responses from "heartbeat.php":

HTTP Status Code	Status	Error	Description
200	Created server	N/A	When a server entry has been created
200	Updated server	N/A	When the existing server entry has been updated
400	Error	Bad request	When the specified POST data is invalid/incomplete
403	Error	Unauthorized	When you try to use the tag "official" without being on the allow list
405	Error	Bad HTTP method	When you don't perform a POST request
500	Error	Unable to {OPERATION}	When the attempted operation fails

For more information, visit the server listing software source code

Handshaking

When the client connects to the server, the server sends: the RSA public key size (32-bit BE integer as 4 bytes) + RSA public key
It's the client's job to verify the RSA public key and then continue handshaking
The client then generates an AES instance using a 256-bit key in CBC mode with PKCS7/PKCS5 padding
Then the client encrypts the AES key using the RSA public key and sends: the encrypted AES key length + the encrypted AES key
After that, the packets start flowing

Structure of a packet

PMSG <IV:16> <EDS:4> <ED:EDS>

• PMSG: The packet header
• IV: The random IV used (16 bytes)
• EDS: The size of the encrypted data (32-bit BE integer as 4 bytes)
• ED: The encrypted data (EDS)

Structure of the encrypted data

<ID> <DATA>

• ID: The packet ID (32-bit BE integer as 4 bytes)
• DATA: The data of the packet sent (can be absent)