-
Notifications
You must be signed in to change notification settings - Fork 0
The MasterMind Project Protocol
Mastermind Project Group I
Aurélien Garnier & Valérian Callot
Efrei Paris
November 15th, 2018
| Chapter | Title |
|---|---|
| I | Introduction |
| II | Definitions |
| II A | Client/Server Definition |
| II B | Token Definition |
| III | Status Codes |
| IV | Packet Definitions |
| IV A | Packet Definition |
| IV B | Status-Packet Definition |
| IV C | Text-Packet Definition |
| IV D | Token-Packet Definition |
| V | Initialization of a Game |
| VI | Game Procedure |
The MasterMind Project Protocol shall be referred to as M2P2 in this document.
The context and details of this project can be found in the annexed PDF report.
M2P2 is a communication protocol created for the communication between two Mastermind games.
One acts on the behalf of a user. This game instance will be referred to as the "Client".
The other game instance is ran continuously and without any user interaction, and will be referred to as the "Server".
A Client's "Identifier" is a unique and unchangeable code allowing a Client to be distinguished from another (because this is in reality not entirely possible or complicated, it is advised to use a Client's IP address (as defined in [RFC 791]) as Identifier, ignoring the port the Client's socket is bound to).
A "Token" is a byte array following the ZLIB Compressed Data Format Specification ([RFC 1950]) encoded as Base64 ([RFC 4648]).
This byte array is the concatenation of:
- The game mode chosen by the Client represented as a number, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 1 byte.
- The current score of the Client, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes.
- The current number of consecutive won games by the client, encoded as an unsigned big-endian (according to [RFC 1700])
- The number of available colors, encoded as an (according to [RFC 1700]) integer on 2 bytes.
- The maximum number of attempts, encoded as an integer on 2 bytes. unsigned big-endian unsigned big-endian
- The length of the code, encoded as an unsigned big-endian (according to (according to [RFC 1700]) integer on 2 bytes. [RFC 1700]) integer on 2 bytes.
- Each color of the code, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes.
- The number of attempts previously made by the Client, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes.
- Each color in each attempt, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes.
A Status Code is applied to each connection between a Client and a Server (i.e. one Client connected to the Server with multiple connections at the same time has independent Status Codes for each of his connections).
The different possible Status Codes are the following:
This Status Code is used to indicate that the connection corresponds to an active game, implying the Client has successfully authenticated and created a game beforehand.
This Status Code is used to indicate that the connection corresponds to a known Client on the Server, but no game has been started yet.
This Status Code is the default code in which each connection is created, and is used to indicate the Client has to answer to a question from the Server (usually, it indicates the Client has to send a Text-Packet with "OK" as Data to accept the Server's terms and conditions such as a GDPR consent notice).
This Status Code is used to indicate that the Client was not recognized by the Server, and is required to authenticate himself by sending a Text-Packet with a chosen username as Data.
This Status Code is used to indicate that the Client tried to authenticate himself with an invalid username. This code indicates the same state as 401 (Unauthorized), with the exception stated above.
This Status Code is used to indicate that another Client with the same Identifier is already connected to the Server with a Status Code of 200 (OK). Since the Identifier is required to be unique across Clients, the Server is expected to terminate the connection soon after this Status Code is reached.
This Status Code is reserved for internal or future use. No use case is given in this specification.
A. A "Packet" is a list of bytes starting with bytes 1E E7 and ending with bytes 7E E1. This pair of two bytes will be named "Boundaries" of the Packet, and each two bytes will be named "Header" of the Packet and "Footer" of the Packet respectively.
The Header of the Packet is directly followed by the total Length N of the Packet in bytes, including the Boundaries and the Length itself, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes. Therefore, N ≤ 65,535 i.e. a Packet can be composed at most of 65,535 bytes.
Will be referred to as "Data" of a Packet the list of bytes of the said Packet from the 5th byte up-to, but not including, the (N-2)th one, where N is the total Length of the said Packet, as defined in [IV. A. §1]. That is the Packet after removing its Boundaries and its Length.
B. A "Status-Packet" is a Packet in which its Data is Status Code encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes. This type of Packet is reserved for Server to Client communication.
C. A "Text-Packet" is a Packet in which its Data is arbitrary text encoded in UTF-8 ([RFC 3629]).
D. A "Token-Packet" is a Text-Packet in which its sole Data is a Token.
E. An "Attempt-Packet" of size M is a Packet in which its Data is a list of M colors encoded as unsigned big-endian (according to [RFC 1700]) integers on 2 bytes each. This type of Packet is reserved for Client to Server communication.
F. An "Answer-Packet" is a Packet in which its Data is a list of 2 unsigned integers encoded as big-endian (according to [RFC 1700]) integers on 2 bytes each. This type of Packet is reserved for Server to Client communication.
When a Client connects to the Server, the Status Code of the connection is considered to be 300 (Multiple Choices).
After this instant, any Status Code change will be instantly followed by a Status-Packet from the Server to the Client, exclusively containing the new Status Code.
When the Status Code is 300 (Multiple Choices), the Server waits for the Client to send a Text-Packet with Data "OK". Upon receiving such a Packet, certain actions are executed according to the following rules:
A. If another Client with the same Identifier is already connected with Status Code 200 (OK), the Status Code of this connection is set to 409 (Conflict) and the connection is then closed.
B. Otherwise, if the Server has already registered a username linked to the Client or if the Server does not require Client-side authentication, then:
1. If the Server has a pending game linked to this Client, then:
a. the Status Code is set to 200 (OK);
b. the Server sends a Text-Packet containing the Client's username if applicable, or else a user-readable Identifier;
c. a Token is generated from the pending game (the Token may contain a deliberately erroneous code which may even contain invalid colors, as long as it is of the same length as the correct one, e.g. to prevent the Client from cheating by accessing the code from this Token), and a Token-Packet with the generated Token as Data is sent from the Server to the Client;
d. the Client's active game is set to be the pending game (it is also allowed to put this step before [V. B. 1. b.] for Server-side implementations).
2. Otherwise, the Status Code is set to 204 (No Content), and the Server sends a Text-Packet containing the Client's username if applicable, or else a user-readable Identifier. Then, the Server waits for the Client to send a Token-Packet. Upon receiving such a Packet, the Status Code is set to 200 (OK), a game is created from the Token received (the Server may deliberately choose to use a different code than the one in the Token as long as it is of the same length, e.g. in case the code contains invalid colors, or to prevent the Client from cheating by forcing a specific code), and this game is set as the Client's active game.
During this state, if the Client sends a Text-Packet starting with "SB:" followed by two positive integers N and M separated by a space, then the Server answers with either of the following:
a. a Packet in which the Data is a list of N or less 9-tuples, in which:
- the first element is the length of the second element encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes;
- the second element is a username encoded in UTF-8 ([RFC 3629]);
- the three following elements are the score, the number of consecutive won games, and the total number of attempts of this scoreboard entry respectively, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes each.
- the three following elements are the number of available colors, the length of the code and the maximum attempts of this scoreboard entry respectively, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 2 bytes each.
- the ninth elements is the number of elapsed milliseconds between January 1st, 1970 and the instant when the last game of this scoreboard entry ended, encoded as an unsigned big-endian (according to [RFC 1700]) integer on 8 bytes.
b. a Packet of length 0, indicating the Server does not keep track of scores or does not have any entry at this position yet.
C. Otherwise, the Status Code is set to 401 (Unauthorized), and the Server waits for the Client to send a Text-Packet. Upon receiving such a Packet, in which the Data will be referred to as the "Requested Username", the Server executes certain actions according to the following rules:
1. If the Requested Username is considered valid by the Server (the definition of a valid username is left as a choice for the person who implements the M2P2 Specification but it is guaranteed to at least allow any list of between 3 and 16 lowercase letters from the English alphabet), then the rules under [V. B.] are applied, with the exception that the Text-Packet containing the Client's username are not sent by the Server.
2. Otherwise, the Status Code is set to 403 (Forbidden), and the Server waits for the Client to send a Text-Packet. Upon receiving such a Packet, in which the Data will be referred to as the "Requested Username", the Server executes certain actions according to the rules under [V. C.].
When a connection reaches Status Code 200 (OK), it is said to be in "Game State" until the Server considers the game ended or until the connection is closed by either side.
Whenever the connection is closed while in Game State, a Token is generated from the current game and is then stored, along with all the Attempt-Packets sent by the Client, and assigned to the Client on the Server.
When entering Game State with a pending game, the Server sends an Answer-Packet for each Attempt-Packet recorded along with the pending game.
While in Game State, the Server waits for the Client to send an Attempt-Packet of Size the length of the game's code. Upon receiving such a Packet, the Server answers with an Answer-Packet containing the number of perfect and partial pegs relative to the game's correct code, in this order.
The Game State ends when the Client sends an Attempt-Packet containing the exact game's code (i.e. when he wins), or after the maximum amount of attempts for this game is reached (i.e. when he loses).
When the Game State ends because of the latter, the Server sends a Token-Packet generated from the game (this time, it must contain the real code e.g. for the Client to display).
After the Game State ends, the pending game linked to the Client is reset and the rules under [V. B.] are applied.