Difference between revisions of "Protocol Encryption"

From wiki.vg
Jump to navigation Jump to search
(emphasize need for correct content-type; add extra possible error i got while writing a client; remove "HTTP/1.1" as server supports other http versions)
(59 intermediate revisions by 30 users not shown)
Line 1: Line 1:
As of 12w17a, Minecraft implements SSL-like encryption.
+
As of 12w17a, Minecraft uses encrypted connections for online-mode servers.
  
 
== Overview ==
 
== Overview ==
  
#Client connects to server
+
# '''C'''→'''S''': [[Protocol#Handshake|Handshake]] State=2
#'''C->S''' 0x02 handshake
+
# '''C'''→'''S''': [[Protocol#Login Start|Login Start]]
#'''S->C''' 0xFD encryption request - server sends its server id string, public key, and 4 random bytes
+
# '''S'''→'''C''': [[Protocol#Encryption Request|Encryption Request]]
#Client generates symmetric key (shared secret)
+
# ''Client authentication''
#Client authenticates via [[Session|authserver.mojang.com]].
+
# '''C''''''S''': [[Protocol#Encryption Response|Encryption Response]]
#Client encrypts these 4 bytes with the servers public key.
+
# ''Server authentication, both enable encryption''
#'''C->S''' 0xFC encryption response - client encrypts shared secret with server's public key and sends along with encrypted 4 bytes
+
# '''S''''''C''': [[Protocol#Login Success|Login Success]]
#Server checks that the encrypted bytes match
+
 
#Server decrypts shared secret with its private key
+
See [[Protocol FAQ]] for a full list of packets exchanged after encryption.
#Server checks player authenticity via session.minecraft.net
 
#'''S->C''' 0xFC encryption response - empty payload meaning two zero length byte arrays and two zero shorts
 
#Server enables AES/CFB8 stream encryption
 
#Client enables AES/CFB8 stream encryption
 
#'''C->S''' 0xCD - Payload of 0 (byte)
 
#'''S->C''' 0x01 login
 
#see [[Protocol FAQ]] to get information about what happens next.
 
  
 
==Server ID String==
 
==Server ID String==
 +
'''Update (1.7.x):''' The server ID is now sent as an empty string. Hashes also utilize the public key, so they will still be correct.
  
 +
'''Pre-1.7.x:'''
 
The server ID string is a randomly-generated string of characters with a maximum length of 20 code points (the client disconnects with an exception if the length is longer than 20).
 
The server ID string is a randomly-generated string of characters with a maximum length of 20 code points (the client disconnects with an exception if the length is longer than 20).
  
Line 30: Line 25:
 
== Key Exchange ==
 
== Key Exchange ==
  
The server generates a 1024-bit RSA keypair on startup. The key, when packed into a 0xFD packet, is in ASN.1 format as defined by x.509.
+
The server generates a 1024-bit RSA keypair on startup. The public key sent in the Encryption Request packet is encoded in [https://en.wikipedia.org/wiki/ASN.1 ASN.1] [https://en.wikipedia.org/wiki/X.690#DER_encoding DER] format. This is a general-purpose binary format common in cryptography, conceptually similar to [[NBT]]. The schema is the same as the <code>SubjectPublicKeyInfo</code> structure defined by [https://en.wikipedia.org/wiki/X.509 X.509] (not a full-blown X.509 certificate!):
The ASN.1 structure looks as follows
 
  
 
  SubjectPublicKeyInfo ::= SEQUENCE {
 
  SubjectPublicKeyInfo ::= SEQUENCE {
Line 38: Line 32:
 
     parameters        ANY OPTIONAL
 
     parameters        ANY OPTIONAL
 
   }
 
   }
   subjectPublicKey  BITSTRING
+
   subjectPublicKey  BIT STRING
 
  }
 
  }
 
   
 
   
Line 46: Line 40:
 
  }
 
  }
  
If you're struggling to import this using a crypto library, you can convert it to common PEM by base64-encoding and wrapping in '-----BEGIN PUBLIC KEY-----' and '-----END PUBLIC KEY-----'.
+
(See the [[#Additional Links]] section of this article for further information.)
 +
 
 +
If you're struggling to import this using a crypto library, try to find a function that loads a DER encoded public key. If you can't find one, you can convert it to the more common PEM encoding by base64-encoding the raw bytes and wrapping the base64 text in '-----BEGIN PUBLIC KEY-----' and '-----END PUBLIC KEY-----'. See this example of a PEM encoded key: https://git.io/v7Ol9
 +
 
 +
It is also possible for a modified or custom server to use a longer RSA key, without breaking official clients.
  
 
== Symmetric Encryption ==
 
== Symmetric Encryption ==
  
On receipt of a 0xFD from the server, the client will generate a 16-byte shared secret, to be used with the AES/CFB8 stream cipher. It then encrypts it with the server's public key (PKCS#1 v1.5 padded), and also encrypts the token received in the 0xFD packet in the same way, then sends both to the server in a 0xFC packet.
+
On receipt of a Encryption Request from the server, the client will generate a random 16-byte shared secret, to be used with the AES/CFB8 stream cipher. It then encrypts it with the server's public key (PKCS#1 v1.5 padded), and also encrypts the verify token received in the Encryption Request packet in the same way, then sends both to the server in a Encryption Response packet. Both byte arrays in the Encryption Response packet will be 128 bytes long because of the padding. This is the only time the client uses the server's public key.
  
The server decrypts the shared secret and token using its private key, and checks if the token is the same. It then sends a 0xFC to the client with an empty payload, and enables AES/CFB8 encryption. For the Initial Vector (IV) and AES setup, both sides use the secret key. Similarly, the client will also enable encryption upon receipt of the empty 0xFC. From this point forward, everything is encrypted.
+
[[File:Icon_exclaim.gif|:!:]] In your crypto library, ensure that you set up your "feedback/segment size" to 8 bits or 1 byte, as indicated in the name AES/CFB'''8'''. Any other feedback size will result in encryption mismatch.
 +
 
 +
The server decrypts the shared secret and token using its private key, and checks if the token is the same. It then sends a Login Success, and enables AES/CFB8 encryption. For the Initial Vector (IV) and AES setup, both sides use the shared secret as both the IV and the key. Similarly, the client will also enable encryption upon sending Encryption Response. From this point forward, everything is encrypted. Note: the entire packet is encrypted, including the length fields and the packet's data.
 +
 
 +
The Login Success packet is sent encrypted.
 +
 
 +
[[File:Icon_exclaim.gif|:!:]] Note that the AES cipher is updated continuously, not finished and restarted every packet.
  
 
== Authentication ==
 
== Authentication ==
  
Both server and client need to make a request to session.minecraft.net if the server is in online-mode.
+
Both server and client need to make a request to sessionserver.mojang.com if the server is in online-mode.
  
 
=== Client ===
 
=== Client ===
Line 63: Line 67:
  
 
  sha1 := Sha1()
 
  sha1 := Sha1()
  sha1.update(ASCII encoding of the server id string from 0xFD)  
+
  sha1.update(ASCII encoding of the server id string from Encryption Request)  
 
  sha1.update(shared secret)  
 
  sha1.update(shared secret)  
  sha1.update(server's encoded public key from 0xFD)  
+
  sha1.update(server's encoded public key from Encryption Request)  
 
  hash := sha1.hexdigest()  # String of hex characters
 
  hash := sha1.hexdigest()  # String of hex characters
  
[[File:Icon_exclaim.gif|:!:]] Note that the Sha1.hexdigest() method used by minecraft removes leading zeros and uses the two's-complement of negative numbers prefixed with a minus sign:
+
[[File:Icon_exclaim.gif|:!:]] Note that the Sha1.hexdigest() method used by minecraft is non standard. It doesn't match the digest method found in most programming languages and libraries. It works by treating the sha1 output bytes as one large integer in two's complement and then printing the integer in base 16, placing a minus sign if the interpreted number is negative. Some examples of the minecraft digest are found below:
  
 
  sha1(Notch) :  4ed1f46bbe04bc756bcb17c0c7ce3e4632f06a48
 
  sha1(Notch) :  4ed1f46bbe04bc756bcb17c0c7ce3e4632f06a48
Line 74: Line 78:
 
  sha1(simon) :  88e16a1019277b15d58faf0541e11910eb756f6
 
  sha1(simon) :  88e16a1019277b15d58faf0541e11910eb756f6
  
The resulting hash is then sent via an HTTP GET request to
+
The resulting hash is then sent via an HTTP POST request to
  <nowiki>http://session.minecraft.net/game/joinserver.jsp?user=</nowiki>''username''&sessionId=''[[Authentication#Session_ID|user_session]]''&serverId=''hash''
+
  <nowiki>https://sessionserver.mojang.com/session/minecraft/join</nowiki>
If it returns '''OK''' then continue, otherwise stop
+
With the following sent as post data. You ''must'' have the Content-Type header set to application/json or you will get a 415 Unsupported Media Type or 403 Forbidden response.
 +
<syntaxhighlight lang="javascript">
 +
  {
 +
    "accessToken": "<accessToken>",
 +
    "selectedProfile": "<player's uuid without dashes>",
 +
    "serverId": "<serverHash>"
 +
  }
 +
</syntaxhighlight>
 +
 
 +
The fields <accessToken> and the player's uuid were received by the client during [[Authentication#Authenticate|authentication]].
 +
 
 +
If everything goes well, the client will receive a "204 No Content" response.
 +
 
 +
The server will respond with "403 Forbidden" if the player's Xbox profile has multiplayer disabled, with the following response:
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "error": "InsufficientPrivilegesException",
 +
    "path": "/session/minecraft/join"
 +
}
 +
</syntaxhighlight>
 +
 
 +
Similarly, if the player was banned from Multiplayer then the server will respond with the following error:
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "error": "UserBannedException",
 +
    "path": "/session/minecraft/join"
 +
}
 +
</syntaxhighlight>
 +
 
 +
If you forget to include a body with your request and just send an empty POST request, or if you use a malformed Content-Type header, you'll get this non-descriptive error:
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "error": "Forbidden",
 +
    "path": "/session/minecraft/join"
 +
}
 +
</syntaxhighlight>
  
 
=== Server ===
 
=== Server ===
  
After decrypting the shared secret in the second 0xFC, the server generates the login hash as above and sends it to
+
After decrypting the shared secret in the second Encryption Response, the server generates the login hash as above and sends a HTTP GET to
  <nowiki>http://session.minecraft.net/game/checkserver.jsp?user=</nowiki>''username''&serverId=''hash''
+
  <nowiki>https://sessionserver.mojang.com/session/minecraft/hasJoined?username=</nowiki>''username''&serverId=''hash''&ip=''ip''
  
If the response is '''YES''' then the client is authenticated and allowed to join. Otherwise the client will/should be [[Protocol#Disconnect.2FKick_.280xFF.29|kicked]] (unencrypted) with "Failed to verify username!"
+
The username is case insensitive and must match the client's username (which was received in the Login Start packet). Note that this is the in-game nickname of the selected profile, not the Mojang account name (which is never sent to the server).
 +
Servers should use the name sent in the "name" field.
 +
 
 +
The ip field is optional and when present should be the IP address of the connecting player; it is the one that originally initiated the session request. The notchian server includes this only when <code>prevent-proxy-connections</code> is set to true in server.properties.
 +
 
 +
The response is a JSON object containing the user's UUID and skin blob
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "id": "<profile identifier>",
 +
    "name": "<player name>",
 +
    "properties": [
 +
        {
 +
            "name": "textures",
 +
            "value": "<base64 string>",
 +
            "signature": "<base64 string; signed data using Yggdrasil's private key>"
 +
        }
 +
    ]
 +
}
 +
</syntaxhighlight>
 +
 
 +
The "id" and "name" fields are then sent back to the client using a Login Success packet. The profile id in the json response has format
 +
"11111111222233334444555555555555" which needs to be changed into format "11111111-2222-3333-4444-555555555555" before sending it back to the client.
  
 
=== Sample Code ===
 
=== Sample Code ===
  
Examples of generating Java-style hex digests:
+
Examples of generating Minecraft-style hex digests:
  
* C#: https://gist.github.com/404223052379e82f91e6
+
* C++: https://git.io/JfTkx
* node.js: https://gist.github.com/4425843
+
* C#: https://git.io/fhjp6
* Go: https://gist.github.com/toqueteos/5372776
+
* Go: http://git.io/-5ORag
 +
* Java: http://git.io/vzbmS
 +
* node.js: http://git.io/v2ue_A
 +
* PHP: https://git.io/fxcFY
 +
* Python: https://git.io/vQFUL
 +
* Rust: https://git.io/fj6P0
  
== Example ==
+
== Additional Links ==
 +
[https://msdn.microsoft.com/en-us/library/windows/desktop/bb648640(v=vs.85).aspx DER Encoding of ASN.1 Types]
  
A parsed transcript of a successful protocol encryption handshake follows:
+
[http://luca.ntop.org/Teaching/Appunti/asn1.html A Layman's Guide to a Subset of ASN.1, BER, and DER]
  
127.0.0.1:43733 connected, there is now 1 client connected
+
[https://gist.github.com/Lazersmoke/9947ada8acdd74a8b2e37d77cf1e0fdc Serializing an RSA Key Manually]
====PROTOCOL ANALYSIS====
 
127.0.0.1:43733 ==> Server - Packet of type 0x02
 
====50 BYTES====
 
0x02 0x3D 0x00 0x0B 0x00 0x44 0x00 0x72
 
0x00 0x61 0x00 0x69 0x00 0x6E 0x00 0x65
 
0x00 0x64 0x00 0x73 0x00 0x6F 0x00 0x75
 
0x00 0x6C 0x00 0x09 0x00 0x6C 0x00 0x6F
 
0x00 0x63 0x00 0x61 0x00 0x6C 0x00 0x68
 
0x00 0x6F 0x00 0x73 0x00 0x74 0x00 0x00
 
0x2D 0x85
 
====PAYLOAD====
 
#1 - Signed Byte: 61
 
#2 - Unicode String (11 graphemes, 11 code points): "Drainedsoul"
 
#3 - Unicode String (9 graphemes, 9 code points): "localhost"
 
#4 - 32-bit Signed Integer: 11653
 
====PROTOCOL ANALYSIS====
 
Server ==> 127.0.0.1:43733 - Packet of type 0xFD
 
====205 BYTES====
 
0xFD 0x00 0x10 0x00 0x4E 0x00 0x77 0x00
 
0x5D 0x00 0x31 0x00 0x51 0x00 0x61 0x00
 
0x43 0x00 0x3C 0x00 0x6F 0x00 0x3A 0x00
 
0x6C 0x00 0x2E 0x00 0x5C 0x00 0x65 0x00
 
0x53 0x00 0x39 0x00 0xA2 0x30 0x81 0x9F
 
0x30 0x0D 0x06 0x09 0x2A 0x86 0x48 0x86
 
0xF7 0x0D 0x01 0x01 0x01 0x05 0x00 0x03
 
0x81 0x8D 0x00 0x30 0x81 0x89 0x02 0x81
 
0x81 0x00 0x9D 0x09 0x76 0x71 0x45 0x24
 
0x18 0x53 0x5F 0x32 0x5A 0xD5 0xBB 0x26
 
0x43 0x2C 0x97 0xBB 0xB3 0xF4 0x03 0x96
 
0xEA 0xF1 0xAD 0xA6 0xC9 0x41 0x7B 0x01
 
0x8F 0x66 0xED 0x92 0x4B 0xB7 0x17 0x2C
 
0x65 0x5C 0xD2 0x42 0x35 0x0C 0x8A 0x8C
 
0xC3 0xE1 0x5C 0x76 0x0E 0x43 0x97 0x17
 
0xEE 0x9E 0xEF 0x4F 0x4E 0x2D 0xFC 0x2D
 
0xE6 0x92 0x0B 0x7E 0xA0 0x56 0xB5 0xB7
 
0x18 0x59 0x57 0x74 0x28 0x5C 0xA1 0x88
 
0xC4 0xE6 0x60 0xDF 0x64 0x3A 0x2C 0x0E
 
0x5C 0x7D 0xB9 0x7C 0xF9 0xFB 0xA2 0x21
 
0xC5 0x0B 0x36 0x7D 0xDE 0x8A 0xC9 0xC5
 
0x09 0xA0 0x2F 0xA0 0x25 0x8A 0x26 0xDB
 
0x0B 0x82 0xC8 0x60 0xCB 0x58 0x02 0xEC
 
0xBB 0xFE 0xBC 0x35 0x3F 0x40 0x9C 0x96
 
0xF4 0x5F 0x02 0x03 0x01 0x00 0x01 0x00
 
0x04 0xED 0x85 0x14 0xD6
 
====PAYLOAD====
 
#1 - Unicode String (16 graphemes, 16 code points): "Nw]1QaC<o:l.\eS9"
 
#2 - Array of bytes (162 bytes):
 
0x30 0x81 0x9F 0x30 0x0D 0x06 0x09 0x2A
 
0x86 0x48 0x86 0xF7 0x0D 0x01 0x01 0x01
 
0x05 0x00 0x03 0x81 0x8D 0x00 0x30 0x81
 
0x89 0x02 0x81 0x81 0x00 0x9D 0x09 0x76
 
0x71 0x45 0x24 0x18 0x53 0x5F 0x32 0x5A
 
0xD5 0xBB 0x26 0x43 0x2C 0x97 0xBB 0xB3
 
0xF4 0x03 0x96 0xEA 0xF1 0xAD 0xA6 0xC9
 
0x41 0x7B 0x01 0x8F 0x66 0xED 0x92 0x4B
 
0xB7 0x17 0x2C 0x65 0x5C 0xD2 0x42 0x35
 
0x0C 0x8A 0x8C 0xC3 0xE1 0x5C 0x76 0x0E
 
0x43 0x97 0x17 0xEE 0x9E 0xEF 0x4F 0x4E
 
0x2D 0xFC 0x2D 0xE6 0x92 0x0B 0x7E 0xA0
 
0x56 0xB5 0xB7 0x18 0x59 0x57 0x74 0x28
 
0x5C 0xA1 0x88 0xC4 0xE6 0x60 0xDF 0x64
 
0x3A 0x2C 0x0E 0x5C 0x7D 0xB9 0x7C 0xF9
 
0xFB 0xA2 0x21 0xC5 0x0B 0x36 0x7D 0xDE
 
0x8A 0xC9 0xC5 0x09 0xA0 0x2F 0xA0 0x25
 
0x8A 0x26 0xDB 0x0B 0x82 0xC8 0x60 0xCB
 
0x58 0x02 0xEC 0xBB 0xFE 0xBC 0x35 0x3F
 
0x40 0x9C 0x96 0xF4 0x5F 0x02 0x03 0x01
 
0x00 0x01
 
#3 - Array of bytes (4 bytes):
 
0xED 0x85 0x14 0xD6
 
====PROTOCOL ANALYSIS====
 
127.0.0.1:43733 ==> Server - Packet of type 0xFC
 
====261 BYTES====
 
0xFC 0x00 0x80 0x9B 0xD1 0xD7 0xA8 0xDB
 
0x54 0x49 0x8F 0x41 0xD5 0xA3 0x74 0x18
 
0xBD 0x8D 0x09 0xEA 0x45 0xFC 0x0F 0x3F
 
0x9B 0xE4 0xF9 0xAC 0xC5 0x7B 0xF6 0x16
 
0xBB 0xFA 0x36 0x51 0xF9 0x19 0xAB 0x72
 
0x2B 0xBA 0x46 0x6C 0x8D 0xB0 0x2D 0x53
 
0x5F 0xA5 0xD4 0x17 0x46 0x0E 0xD7 0xC1
 
0xAA 0x5D 0xC7 0x73 0x51 0xDA 0x3F 0xD7
 
0x5E 0xF6 0x96 0xF9 0x10 0xB2 0x1C 0x0D
 
0xAA 0x1E 0x61 0x37 0xFB 0x3C 0x66 0x77
 
0x20 0xCB 0xF7 0x3C 0x55 0xE5 0x9E 0xC1
 
0x28 0x63 0xD1 0xD7 0xF6 0xEE 0x1E 0x2C
 
0x20 0x72 0x98 0x7E 0xF2 0x7D 0xDF 0xFE
 
0x5A 0x25 0x3C 0x22 0xC0 0xCF 0x86 0xB3
 
0x02 0x97 0xB1 0x80 0x97 0xA1 0x92 0xDA
 
0xD2 0x44 0xB1 0xDA 0x0F 0x1C 0x30 0x96
 
0x98 0x0B 0xB7 0x00 0x80 0x78 0x85 0x42
 
0xF7 0xF8 0x2F 0x00 0xDB 0xBF 0x2E 0x22
 
0x33 0x10 0x6C 0x19 0xE3 0x16 0x8F 0x36
 
0x16 0xE3 0xD9 0x86 0x67 0x52 0x04 0x57
 
0xB6 0x4F 0x57 0x8C 0xB4 0x02 0x18 0x6D
 
0x16 0xC6 0xB5 0x95 0xBC 0xE6 0xEA 0x76
 
0x10 0x7A 0xB9 0xE3 0xBD 0x3C 0x50 0xEA
 
0x42 0xDF 0x47 0x05 0x3F 0xCF 0xD5 0x70
 
0xF4 0xAB 0xB5 0x07 0x90 0xA2 0x84 0x12
 
0x79 0x65 0x03 0x2A 0xB6 0x6B 0x0A 0xA8
 
0x90 0x8B 0xFE 0xCC 0x4E 0x04 0x35 0xA2
 
0xDD 0x08 0xBF 0xDD 0x29 0xAF 0x50 0xFD
 
0x2B 0x73 0xE1 0x6A 0xED 0xE8 0xE2 0x27
 
0x8F 0x0B 0xD5 0x0D 0xBC 0x9B 0x47 0x16
 
0x92 0x7B 0xD2 0xE6 0xD7 0xF1 0x3A 0xAE
 
0x3D 0x14 0xA9 0xC3 0xF2 0x96 0x8A 0x54
 
0x24 0x29 0xA3 0x53 0x55
 
====PAYLOAD====
 
#1 - Array of bytes (128 bytes):
 
0x9B 0xD1 0xD7 0xA8 0xDB 0x54 0x49 0x8F
 
0x41 0xD5 0xA3 0x74 0x18 0xBD 0x8D 0x09
 
0xEA 0x45 0xFC 0x0F 0x3F 0x9B 0xE4 0xF9
 
0xAC 0xC5 0x7B 0xF6 0x16 0xBB 0xFA 0x36
 
0x51 0xF9 0x19 0xAB 0x72 0x2B 0xBA 0x46
 
0x6C 0x8D 0xB0 0x2D 0x53 0x5F 0xA5 0xD4
 
0x17 0x46 0x0E 0xD7 0xC1 0xAA 0x5D 0xC7
 
0x73 0x51 0xDA 0x3F 0xD7 0x5E 0xF6 0x96
 
0xF9 0x10 0xB2 0x1C 0x0D 0xAA 0x1E 0x61
 
0x37 0xFB 0x3C 0x66 0x77 0x20 0xCB 0xF7
 
0x3C 0x55 0xE5 0x9E 0xC1 0x28 0x63 0xD1
 
0xD7 0xF6 0xEE 0x1E 0x2C 0x20 0x72 0x98
 
0x7E 0xF2 0x7D 0xDF 0xFE 0x5A 0x25 0x3C
 
0x22 0xC0 0xCF 0x86 0xB3 0x02 0x97 0xB1
 
0x80 0x97 0xA1 0x92 0xDA 0xD2 0x44 0xB1
 
0xDA 0x0F 0x1C 0x30 0x96 0x98 0x0B 0xB7
 
#2 - Array of bytes (128 bytes):
 
0x78 0x85 0x42 0xF7 0xF8 0x2F 0x00 0xDB
 
0xBF 0x2E 0x22 0x33 0x10 0x6C 0x19 0xE3
 
0x16 0x8F 0x36 0x16 0xE3 0xD9 0x86 0x67
 
0x52 0x04 0x57 0xB6 0x4F 0x57 0x8C 0xB4
 
0x02 0x18 0x6D 0x16 0xC6 0xB5 0x95 0xBC
 
0xE6 0xEA 0x76 0x10 0x7A 0xB9 0xE3 0xBD
 
0x3C 0x50 0xEA 0x42 0xDF 0x47 0x05 0x3F
 
0xCF 0xD5 0x70 0xF4 0xAB 0xB5 0x07 0x90
 
0xA2 0x84 0x12 0x79 0x65 0x03 0x2A 0xB6
 
0x6B 0x0A 0xA8 0x90 0x8B 0xFE 0xCC 0x4E
 
0x04 0x35 0xA2 0xDD 0x08 0xBF 0xDD 0x29
 
0xAF 0x50 0xFD 0x2B 0x73 0xE1 0x6A 0xED
 
0xE8 0xE2 0x27 0x8F 0x0B 0xD5 0x0D 0xBC
 
0x9B 0x47 0x16 0x92 0x7B 0xD2 0xE6 0xD7
 
0xF1 0x3A 0xAE 0x3D 0x14 0xA9 0xC3 0xF2
 
0x96 0x8A 0x54 0x24 0x29 0xA3 0x53 0x55
 
====PROTOCOL ANALYSIS====
 
HTTP request ==> <nowiki>http://session.minecraft.net/game/checkserver.jsp?user=Draineds</nowiki>
 
oul&serverId=-219245c9f4bce438ee84e84b28514ced1cd2846b
 
====PROTOCOL ANALYSIS====
 
HTTP response <== <nowiki>http://session.minecraft.net/game/checkserver.jsp?user=Drained</nowiki>
 
soul&serverId=-219245c9f4bce438ee84e84b28514ced1cd2846b - Status: 200 - Time ela
 
psed: 279902765ns - Response body (3 graphemes, 3 code points):
 
YES
 
====PROTOCOL ANALYSIS====
 
Server ==> 127.0.0.1:43733 - Packet of type 0xFC
 
====5 BYTES====
 
0xFC 0x00 0x00 0x00 0x00
 
====PAYLOAD====
 
#1 - Array of bytes (0 bytes):
 
 
#2 - Array of bytes (0 bytes):
 
 
====ENCRYPTION ENABLED====
 
Encryption enabled with key:
 
0x6C 0xBC 0x2E 0x17 0x45 0xBD 0x65 0xDF
 
0xA0 0x12 0x85 0x8F 0x00 0x87 0xAA 0x74
 
Encryption enabled with IV:
 
0x6C 0xBC 0x2E 0x17 0x45 0xBD 0x65 0xDF
 
0xA0 0x12 0x85 0x8F 0x00 0x87 0xAA 0x74
 
127.0.0.1 : 43733 logged in as Drainedsoul
 
====PROTOCOL ANALYSIS====
 
127.0.0.1:43733 ==> Server - Packet of type 0xCD
 
====2 BYTES====
 
0xCD 0x00
 
  
== Additional Links ==
 
 
[https://gist.github.com/3900517 Encrypt shared secret using OpenSSL]
 
[https://gist.github.com/3900517 Encrypt shared secret using OpenSSL]
  
Line 278: Line 173:
 
[http://pastebin.com/MjvR0T98 De/Encrypt data via AES using Crypto++]
 
[http://pastebin.com/MjvR0T98 De/Encrypt data via AES using Crypto++]
  
[https://github.com/SirCmpwn/Craft.Net/blob/master/Craft.Net/AesStream.cs C# AES/CFB support with bouncy castle on Mono]
+
[https://github.com/SirCmpwn/Craft.Net/blob/master/source/Craft.Net.Networking/AesStream.cs C# AES/CFB support with bouncy castle on Mono]
  
  
 
[[Category:Protocol Details]]
 
[[Category:Protocol Details]]
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]

Revision as of 20:01, 2 April 2024

As of 12w17a, Minecraft uses encrypted connections for online-mode servers.

Overview

  1. CS: Handshake State=2
  2. CS: Login Start
  3. SC: Encryption Request
  4. Client authentication
  5. CS: Encryption Response
  6. Server authentication, both enable encryption
  7. SC: Login Success

See Protocol FAQ for a full list of packets exchanged after encryption.

Server ID String

Update (1.7.x): The server ID is now sent as an empty string. Hashes also utilize the public key, so they will still be correct.

Pre-1.7.x: The server ID string is a randomly-generated string of characters with a maximum length of 20 code points (the client disconnects with an exception if the length is longer than 20).

The client appears to arrive at incorrect hashes if the server ID string contains certain unprintable characters, so for consistent results only characters with code points in the range U+0021-U+007E (inclusive) should be sent. This range corresponds to all of ASCII with the exception of the space character (U+0020) and all control characters (U+0000-U+001F, U+007F).

The client appears to arrive at incorrect hashes if the server ID string is too short. 15 to 20 (inclusive) length strings have been observed from the Notchian server and confirmed to work as of 1.5.2.

Key Exchange

The server generates a 1024-bit RSA keypair on startup. The public key sent in the Encryption Request packet is encoded in ASN.1 DER format. This is a general-purpose binary format common in cryptography, conceptually similar to NBT. The schema is the same as the SubjectPublicKeyInfo structure defined by X.509 (not a full-blown X.509 certificate!):

SubjectPublicKeyInfo ::= SEQUENCE {
  algorithm SEQUENCE {
    algorithm         OBJECT IDENTIFIER
    parameters        ANY OPTIONAL
  }
  subjectPublicKey  BIT STRING
}

SubjectPublicKey ::= SEQUENCE {
  modulus           INTEGER
  publicExponent    INTEGER
}

(See the #Additional Links section of this article for further information.)

If you're struggling to import this using a crypto library, try to find a function that loads a DER encoded public key. If you can't find one, you can convert it to the more common PEM encoding by base64-encoding the raw bytes and wrapping the base64 text in '-----BEGIN PUBLIC KEY-----' and '-----END PUBLIC KEY-----'. See this example of a PEM encoded key: https://git.io/v7Ol9

It is also possible for a modified or custom server to use a longer RSA key, without breaking official clients.

Symmetric Encryption

On receipt of a Encryption Request from the server, the client will generate a random 16-byte shared secret, to be used with the AES/CFB8 stream cipher. It then encrypts it with the server's public key (PKCS#1 v1.5 padded), and also encrypts the verify token received in the Encryption Request packet in the same way, then sends both to the server in a Encryption Response packet. Both byte arrays in the Encryption Response packet will be 128 bytes long because of the padding. This is the only time the client uses the server's public key.

:!: In your crypto library, ensure that you set up your "feedback/segment size" to 8 bits or 1 byte, as indicated in the name AES/CFB8. Any other feedback size will result in encryption mismatch.

The server decrypts the shared secret and token using its private key, and checks if the token is the same. It then sends a Login Success, and enables AES/CFB8 encryption. For the Initial Vector (IV) and AES setup, both sides use the shared secret as both the IV and the key. Similarly, the client will also enable encryption upon sending Encryption Response. From this point forward, everything is encrypted. Note: the entire packet is encrypted, including the length fields and the packet's data.

The Login Success packet is sent encrypted.

:!: Note that the AES cipher is updated continuously, not finished and restarted every packet.

Authentication

Both server and client need to make a request to sessionserver.mojang.com if the server is in online-mode.

Client

After generating the shared secret, the client generates the following hash:

sha1 := Sha1()
sha1.update(ASCII encoding of the server id string from Encryption Request) 
sha1.update(shared secret) 
sha1.update(server's encoded public key from Encryption Request) 
hash := sha1.hexdigest()  # String of hex characters

:!: Note that the Sha1.hexdigest() method used by minecraft is non standard. It doesn't match the digest method found in most programming languages and libraries. It works by treating the sha1 output bytes as one large integer in two's complement and then printing the integer in base 16, placing a minus sign if the interpreted number is negative. Some examples of the minecraft digest are found below:

sha1(Notch) :  4ed1f46bbe04bc756bcb17c0c7ce3e4632f06a48
sha1(jeb_)  : -7c9d5b0044c130109a5d7b5fb5c317c02b4e28c1
sha1(simon) :  88e16a1019277b15d58faf0541e11910eb756f6

The resulting hash is then sent via an HTTP POST request to

https://sessionserver.mojang.com/session/minecraft/join

With the following sent as post data. You must have the Content-Type header set to application/json or you will get a 415 Unsupported Media Type or 403 Forbidden response.

  {
    "accessToken": "<accessToken>",
    "selectedProfile": "<player's uuid without dashes>",
    "serverId": "<serverHash>"
  }

The fields <accessToken> and the player's uuid were received by the client during authentication.

If everything goes well, the client will receive a "204 No Content" response.

The server will respond with "403 Forbidden" if the player's Xbox profile has multiplayer disabled, with the following response:

{
    "error": "InsufficientPrivilegesException",
    "path": "/session/minecraft/join"
}

Similarly, if the player was banned from Multiplayer then the server will respond with the following error:

{
    "error": "UserBannedException",
    "path": "/session/minecraft/join"
}

If you forget to include a body with your request and just send an empty POST request, or if you use a malformed Content-Type header, you'll get this non-descriptive error:

{
    "error": "Forbidden",
    "path": "/session/minecraft/join"
}

Server

After decrypting the shared secret in the second Encryption Response, the server generates the login hash as above and sends a HTTP GET to

https://sessionserver.mojang.com/session/minecraft/hasJoined?username=username&serverId=hash&ip=ip

The username is case insensitive and must match the client's username (which was received in the Login Start packet). Note that this is the in-game nickname of the selected profile, not the Mojang account name (which is never sent to the server). Servers should use the name sent in the "name" field.

The ip field is optional and when present should be the IP address of the connecting player; it is the one that originally initiated the session request. The notchian server includes this only when prevent-proxy-connections is set to true in server.properties.

The response is a JSON object containing the user's UUID and skin blob

{
    "id": "<profile identifier>",
    "name": "<player name>",
    "properties": [ 
        {
            "name": "textures",
            "value": "<base64 string>",
            "signature": "<base64 string; signed data using Yggdrasil's private key>"
        }
    ]
}

The "id" and "name" fields are then sent back to the client using a Login Success packet. The profile id in the json response has format "11111111222233334444555555555555" which needs to be changed into format "11111111-2222-3333-4444-555555555555" before sending it back to the client.

Sample Code

Examples of generating Minecraft-style hex digests:

Additional Links

DER Encoding of ASN.1 Types

A Layman's Guide to a Subset of ASN.1, BER, and DER

Serializing an RSA Key Manually

Encrypt shared secret using OpenSSL

Generate RSA-Keys and building the ASN.1v8 structure of the x.509 certificate using Crypto++

Decrypt shared secret using Crypto++

De/Encrypt data via AES using Crypto++

C# AES/CFB support with bouncy castle on Mono