BSDecrypter-Colette/README-en.md

Analysis and Client Implementation for Project Colette V53

This document provides a detailed technical breakdown of the connection process to a Project Colette V53 server. It dissects the cryptographic handshake, packet structure, and message exchange logic as implemented in the main.py Python client.

[*] Core Concepts

The data exchange protocol is a custom protocol layered on top of standard TCP. The encryption is built using the NaCl cryptographic library (referenced in the C# code as TweetNaCl), which provides:

• Asymmetric Encryption: Curve25519 for key exchange via Elliptic-curve Diffie–Hellman (ECDH).
• Symmetric Encryption: XSalsa20-Poly1305 for stream encryption after the session is established.
• Hashing: Blake2b for nonce generation.

Each message (packet) in the protocol is prefixed with a 7-byte header:

• Message ID (2 bytes): The identifier for the message type.
• Payload Length (3 bytes): The length of the upcoming payload.
• Version (2 bytes): The version of the message.

[!] Step-by-Step Breakdown of the Connection Process

The process from the initial connection to a fully established encrypted session involves the exchange of four key packets.

---

Step 1: ClientHello (ID: 10100)

• Direction: Client -> Server
• Encryption: None

This is the very first packet the client sends after establishing a TCP connection. Its sole purpose is to initiate a session on the server and signal readiness to begin the handshake. The payload of this packet is irrelevant to the cryptography and can be filled with zeros.

---

Step 2: LoginMessage (ID: 10101)

• Direction: Client -> Server
• Encryption: Asymmetric (Box)

This is the key packet from the client, where the core of the key exchange magic happens.

Client-Side Preparation (Before Sending):

1. Server's Key: The client uses the server's static server_public_key, which is known beforehand (extracted from the server's source code).
2. Client's Keys: The client generates a new, ephemeral (temporary) Curve25519 key pair—client_public_key and client_private_key. This pair will only be used for the current session.
3. Shared Secret (s): The client immediately computes the pre-master shared secret (shared_secret or s) using its new private key and the server's public key. This is a standard ECDH operation. In PyNaCl, this is done with Box.beforenm(server_public_key, client_private_key). This secret s will be needed to decrypt the server's response.
4. Client Nonce (RNonce): The client generates 24 random bytes, the client_nonce. The server refers to this as the RNonce (Receiver's Nonce). It is a critical part of the handshake.

Packet Structure and Transmission:

The 10101 packet consists of two parts:

1. Client's Public Key (32 bytes): Sent in cleartext.
2. Encrypted Payload:
   • Data to Encrypt: The plaintext to be encrypted contains:
     1. A temporary session key (24 bytes, generated by the client but ignored by the server).
     2. The client_nonce (RNonce) (24 bytes).
     3. The actual login data (account ID, client version, etc.), serialized into a bytestream.
   • Nonce for Encryption: The nonce for this operation is calculated as a hash of the public keys: blake2b(client_public_key + server_public_key).
   • Encryption Process: The data above is encrypted using Box(client_private_key, server_public_key).encrypt(...).

---

Step 3: ServerHello (ID: 20100)

• Direction: Server -> Client
• Encryption: Asymmetric (Box)

This is the server's response, which completes the asymmetric phase of the handshake.

Client-Side Decryption Process:

1. Nonce Calculation: To decrypt this packet, the client must use the same nonce the server used. The server calculates it with the formula: blake2b(RNonce + client_public_key + server_public_key). The client already has all three components: it generated RNonce itself, and it knows both public keys.
2. Decryption Process: Decryption is performed using the previously computed shared secret s. Formula: Box.open_afternm(payload, nonce, shared_secret).

Contents of the Decrypted Packet:

Inside are two key elements for all future communication:

1. Final Session Key (session_key) (32 bytes): This is the symmetric key that will be used to encrypt all subsequent messages.
2. Server Nonce (SNonce) (24 bytes): This nonce will be the base for encrypting messages flowing from the server to the client.

---

Step 4: Transition to Symmetric Encryption & LoginOk (ID: 20104)

• Direction: Server -> Client
• Encryption: Symmetric (SecretBox)

After receiving ServerHello, the cryptographic session is fully established. All subsequent packets are encrypted symmetrically using SecretBox and the session_key.

Nonce Logic (NextNonce)

A key feature of the protocol is that the nonce is incremented by 2 before every encryption or decryption operation. The next_nonce function in the code precisely replicates this server-side logic.

LoginOk

This is the first packet the client receives that is symmetrically encrypted.

1. Get Nonce: The client takes the SNonce it received in the previous step.
2. Increment Nonce: It applies the next_nonce logic to it (increasing it by 2).
3. Decrypt: It decrypts the packet using SecretBox(session_key).decrypt(payload, nonce).

Successfully decrypting LoginOk confirms that the entire process has worked correctly, and the client is now in a fully encrypted session with the server. This packet contains the details of the newly created account (ID, token, etc.).