Difference between revisions of "Protocol Encryption"

From wiki.vg
Jump to navigation Jump to search
(→‎Sample Code: add node.js example code)
 
(48 intermediate revisions by 18 users not shown)
Line 1: Line 1:
As of 12w17a, minecraft implements SSL-like encryption.
+
As of 12w17a, Minecraft implements SSL-like encryption.
  
 
== Overview ==
 
== Overview ==
 +
  C->S : Handshake State=2
 +
  C->S : Login Start
 +
  S->C : Encryption Key Request
 +
  (Client Auth)
 +
  C->S : Encryption Key Response
 +
  (Server Auth, Both enable encryption)
 +
  S->C : Login Success
 +
#see [[Protocol FAQ]] to get information about what happens next.
 +
 +
==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).
  
#Client connects to server
+
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.
#'''C->S''' 0x02 handshake
 
#'''S->C''' 0xFD encryption request - server sends its server id string, public key, and 4 random bytes
 
#Client generates symmetric key (shared secret)
 
#Client authenticates via session.minecraft.net
 
#Client encrypts these 4 bytes with the servers public key.
 
#'''C->S''' 0xFC encryption response - client encrypts shared secret with server's public key and sends along with encrypted 4 bytes
 
#Server checks that the encrypted bytes match
 
#Server decrypts shared secret with its private key
 
#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 stream encryption
 
#Client enables AES stream encryption
 
#'''C->S''' 0xCD - Payload of 0 (byte)
 
#'''S->C''' 0x01 login
 
#see [[Protocol FAQ]] to get information about what happens next.
 
  
 
== 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 key, when packed into a Encryption Request packet, is in ASN.1 format as defined by x.509.
 
The ASN.1 structure looks as follows
 
The ASN.1 structure looks as follows
  
Line 42: Line 43:
 
== 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 sends it to the server along the token recieved in 0xFD encrypted with server's public key with a 0xFC.
+
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 Login Success, and enables AES/CFB8 encryption. For the Initial Vector (IV) and AES setup, both sides use the shared secret key. Similarly, the client will also enable encryption upon sending Encryption Response. From this point forward, everything is encrypted.
 +
 
 +
The Login Success packet is sent encrypted.
  
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|:!:]] 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 55: Line 60:
  
 
  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
  
Line 66: Line 71:
 
  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=''[[Session#Login|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, Content-Type: application/json
 +
<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 "HTTP/1.1 204 No Content" response.
  
 
=== Server ===
 
=== Server ===
  
After decrypting the shared secret in 0xFD, the sever 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''
 +
 
 +
The username is case sensitive 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).
 +
 
 +
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>
  
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 "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#: http://git.io/kO6Ejg
* node.js: https://gist.github.com/4425843
+
* node.js: http://git.io/v2ue_A
 +
* Go: http://git.io/-5ORag
 +
* Java: http://git.io/vzbmS
  
 
== Additional Links ==
 
== Additional Links ==
 +
[https://msdn.microsoft.com/en-us/library/windows/desktop/bb648640(v=vs.85).aspx DER Encoding of ASN.1 Types]
 +
 +
[http://luca.ntop.org/Teaching/Appunti/asn1.html A Layman's Guide to a Subset of ASN.1, BER, and DER]
 +
 +
[https://gist.github.com/Lazersmoke/9947ada8acdd74a8b2e37d77cf1e0fdc Serializing an RSA Key Manually]
 +
 
[https://gist.github.com/3900517 Encrypt shared secret using OpenSSL]
 
[https://gist.github.com/3900517 Encrypt shared secret using OpenSSL]
  
Line 92: Line 134:
  
 
[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/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 00:37, 21 January 2017

As of 12w17a, Minecraft implements SSL-like encryption.

Overview

  C->S : Handshake State=2
  C->S : Login Start
  S->C : Encryption Key Request
  (Client Auth)
  C->S : Encryption Key Response
  (Server Auth, Both enable encryption)
  S->C : Login Success
  1. see Protocol FAQ to get information about what happens next.

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 key, when packed into a Encryption Request packet, is in ASN.1 format as defined by x.509. The ASN.1 structure looks as follows

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

SubjectPublicKey ::= SEQUENCE {
  modulus           INTEGER
  publicExponent    INTEGER
}

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-----'.

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.

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 key. Similarly, the client will also enable encryption upon sending Encryption Response. From this point forward, everything is encrypted.

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 removes leading zeros and uses the two's-complement of negative numbers prefixed with a minus sign:

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, Content-Type: application/json

  {
    "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 "HTTP/1.1 204 No Content" response.

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

The username is case sensitive 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).

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