Difference between revisions of "Session"

From wiki.vg
Jump to navigation Jump to search
(Improved description of Yggdrasil authentication + moved some sections around)
Line 1: Line 1:
 
The minecraft client and server communicate with minecraft.net to validate player sessions. This page describes some of the operations.
 
The minecraft client and server communicate with minecraft.net to validate player sessions. This page describes some of the operations.
  
−
== Login ==
+
== Authentication ==
  
−
To log the player in, the official launcher sends an HTTPS POST (GET appears to suffice as well) request to:
+
Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the [[#Outdated authentication system|previous authentication system]].
−
<pre>https://login.minecraft.net</pre>
+
 
−
with the postdata:
+
=== Request format ===
−
  ?user=<username>&password=<password>&version=<launcher version>
 
−
and a "application/x-www-form-urlencoded" Content-Type header.
 
  
−
After migrating to Mojang accounts, email address is used instead of username, but the procedure stays the same.
+
All requests to Yggdrasil are made to the following server:
  
−
The current launcher version is "13" (for new launcher it's "14"), sending a value lower than 12 will cause the server to return "Old version", however you can send any large number and it will return as expected. If the login succeeded, it will return 5 ':' delimited values.
+
   https://authserver.mojang.com
−
   1343825972000:deprecated:SirCmpwn:7ae9007b9909de05ea58e94199a33b30c310c69c:dba0c48e1c584963b9e93a038a66bb98
 
−
#'''current version''' of the game files (not the launcher itself). This is a unix timestamp which the launcher compares to the ~/.minecraft/bin/version file.
 
−
#Previously contained a '''download ticket''' for requesting new versions of minecraft.jar from the server. Now contains only "deprecated".
 
−
#'''case-correct username'''. For mojang accounts, the user's actual username is returned here instead of the email used to log in.
 
−
#'''sessionId''' - a unique ID for your current session.
 
−
#'''UID''' - currently unused, introduced near August 8th, 2012. Grum says this is the unique ID for the user, potentially for changing Minecraft names in future.
 
  
−
If the request is missing a parameter, the server will return "Bad response". If the login information is incorrect, the server will return "Bad login". If the login information is correct but the account isn't premium, the server will return "User not premium". If your minecraft.net account has been migrated to a Mojang account but you're logging in with your minecraft.net username the server will return "Acount migrated, use e-mail".
+
Further, they are expected to fulfill the following rules:
  
−
== Login 1.6 ==
+
* Are <code>POST</code> requests
 +
* Have the <code>Content-Type</code> header set to <code>application/json</code>
 +
* Contain a [http://json.org JSON]-encoded dictionary as payload
  
−
In minecraft 1.6 there is a new launcher, which uses a different method of authenticating users:
+
If a request was successful the server will respond with:
  
−
first the status of the mojang network is checked by looking at http://status.mojang.com/check
+
* Status code <code>200</code>
−
then updates are downloaded, then the client authenticates by doing:
+
* A [http://json.org JSON]-encoded dictionary according to the specifications below
  
−
  POST https://authserver.mojang.com/authenticate
+
If however a request fails, the server will respond with:
−
with (json encoded)
 
−
    {
 
−
    "agent":{"name":"Minecraft","version":1},
 
−
    "username":"account@mailserver.com",
 
−
    "password":"xxxxxxx",
 
−
    "clientToken":"dddddddd-aaaa-bbbb-cccc-111111111111"
 
−
    }
 
  
−
The authserver responds with:
+
* An appropriate, non-200 [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP status code]
 +
* A [http://json.org JSON]-encoded dictionary following this format:
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "error": "Short description of the error",
 +
  "errorMessage": "Longer description which can be shown to the user",
 +
  "cause": "Cause of the error"        // optional
 +
}
 +
</syntaxhighlight>
  
−
    {
 
−
    "accessToken":"99999999999999999999999999999999",
 
−
    "clientToken":"dddddddd-aaaa-bbbb-cccc-111111111111",
 
−
    "availableProfiles":[ {"id":"55555555555555555555555555555555","name":"MOJANGNAME"} ],
 
−
    "selectedProfile":{"id":"55555555555555555555555555555555","name":"MOJANGNAME"}
 
−
    }
 
  
−
then the client checks on mcoapi with:
+
=== Session ID ===
 +
Whenever a Mojang service requires a session ID, you can simply combine a valid <code>accessToken</code> with a profile identifier as follows:
  
−
   GET https://mcoapi.minecraft.net/mco/available
+
   accessToken:profileID
−
with this cookie
 
−
  Cookie: sid=token:99999999999999999999999999999999:55555555555555555555555555555555;user=MOJANGNAME;version=1.6.2
 
  
 +
=== Authenticate ===
 +
This method is used whenever a user tries to log in using his password.
  
−
When connecting to a server, the client first establishes an encrypted session with the server, then does:
+
==== Endpoint ====
 +
  /authenticate
  
 +
==== Payload ====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "agent": {
 +
    "name": "Minecraft",                // So far this is the only encountered value
 +
    "version": 1                        // This number might be increased
 +
                                        // by the vanilla client in the future
 +
  },
 +
  "username": "mojang account name",    // Can be an email address or player name for
 +
                                        // unmigrated accounts
 +
  "password": "mojang account password",
 +
  "clientToken": "client identifier"    // optional
 +
}
 +
</syntaxhighlight>
  
−
  GET http://session.minecraft.net/game/joinserver.jsp?
+
The <code>clientToken</code> should be a randomly generated identifier and must identical for each request.
−
    user=MOJANGNAME&
+
In case it is omitted the server will generate a random token based on Java's [http://docs.oracle.com/javase/7/docs/api/java/util/UUID.html#toString() UUID.toString()] which should then be stored by the client.
−
    sessionId=token%3A99999999999999999999999999999999%3A55555555555555555555555555555555&
 
−
    serverId=-6666666666666666666666666666666666666666
 
  
 +
==== Response ====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "accessToken": "random access token",  // hexadecimal
 +
  "clientToken": "client identifier",    // identical to the one received
 +
  "availableProfiles": [
 +
    {
 +
      "id": "profile identifier",        // hexadecimal
 +
      "name": "player name"
 +
    }
 +
  ],
 +
  "selectedProfile": {
 +
    "id": "profile identifier",
 +
    "name": "player name"
 +
  }
 +
}
 +
</syntaxhighlight>
 +
'''Note:''' If a user wishes to stay logged in on his computer you are strongly advised to store the received <code>accessToken</code> instead of the password itself.
  
−
the server verifies if the user did call joinserver by doing:
+
Currently each account will only have one single profile, multiple profiles per account are however planned in the future.
  
−
  GET http://session.minecraft.net/game/checkserver.jsp?
 
−
    user=MOJANGNAME&
 
−
    serverId=-6666666666666666666666666666666666666666
 
  
 
== Updating ==
 
== Updating ==
Line 86: Line 104:
 
Further resources are stored in /MinecraftResources. Loading /MinecraftResources provides an XML formatted list of resources, some of which are downloaded by Minecraft and not the launcher.
 
Further resources are stored in /MinecraftResources. Loading /MinecraftResources provides an XML formatted list of resources, some of which are downloaded by Minecraft and not the launcher.
  
−
== Updating 1.6 ==
+
=== Updating 1.6 ===
  
 
With the new launcher updating happens by downloading information from  https://s3.amazonaws.com/Minecraft.Download/versions/versions.json and https://s3.amazonaws.com/Minecraft.Download/versions/1.6.2/1.6.2.json
 
With the new launcher updating happens by downloading information from  https://s3.amazonaws.com/Minecraft.Download/versions/versions.json and https://s3.amazonaws.com/Minecraft.Download/versions/1.6.2/1.6.2.json
  
−
== Keep-alive ==
 
−
 
−
Every 6000 ticks, the client sends an HTTPS request to
 
−
<pre>https://login.minecraft.net/session?name=<username>&session=<session id></pre>
 
−
The client discards the server's response.
 
  
 
== Snoop ==
 
== Snoop ==
Line 422: Line 435:
 
# Client generates a symmetric key.
 
# Client generates a symmetric key.
 
# Client sends a HTTP request to  
 
# Client sends a HTTP request to  
−
#:<pre>http://session.minecraft.net/game/joinserver.jsp?user=<username>&sessionId=<session id>&serverId=<server hash></pre>
+
#:<pre>http://session.minecraft.net/game/joinserver.jsp?user=<player name>&sessionId=<session id>&serverId=<server hash></pre>
−
#:Note: Case-corrected username is used here, not the Mojang account username.
+
#:Note: See the [[#Session ID|Session ID]] section on how the <code>&lt;session id&gt;</code> is generated.
 
#:If the response is '''OK''' then continue, otherwise stop
 
#:If the response is '''OK''' then continue, otherwise stop
 
# Client sends [[Protocol#0xFC|0xFC encryption response]] - client encrypts shared secret and verification token with the server's public key
 
# Client sends [[Protocol#0xFC|0xFC encryption response]] - client encrypts shared secret and verification token with the server's public key
Line 448: Line 461:
 
# Server sends [[Protocol#0x01|0x01 login]]
 
# Server sends [[Protocol#0x01|0x01 login]]
 
# ... send map chunks, etc...
 
# ... send map chunks, etc...
 +
 +
 +
== Outdated authentication system ==
 +
This system was used by Minecraft versions prior to 1.6 and might be discontinued at any moment without warning.
 +
 +
=== Login ===
 +
 +
To log the player in, the official launcher sends an HTTPS POST (GET appears to suffice as well) request to:
 +
<pre>https://login.minecraft.net</pre>
 +
with the postdata:
 +
  ?user=<username>&password=<password>&version=<launcher version>
 +
and a "application/x-www-form-urlencoded" Content-Type header.
 +
 +
After migrating to Mojang accounts, email address is used instead of username, but the procedure stays the same.
 +
 +
The current launcher version is "13" (for new launcher it's "14"), sending a value lower than 12 will cause the server to return "Old version", however you can send any large number and it will return as expected. If the login succeeded, it will return 5 ':' delimited values.
 +
  1343825972000:deprecated:SirCmpwn:7ae9007b9909de05ea58e94199a33b30c310c69c:dba0c48e1c584963b9e93a038a66bb98
 +
#'''current version''' of the game files (not the launcher itself). This is a unix timestamp which the launcher compares to the ~/.minecraft/bin/version file.
 +
#Previously contained a '''download ticket''' for requesting new versions of minecraft.jar from the server. Now contains only "deprecated".
 +
#'''case-correct username'''. For mojang accounts, the user's actual username is returned here instead of the email used to log in.
 +
#'''sessionId''' - a unique ID for your current session.
 +
#'''UID''' - currently unused, introduced near August 8th, 2012. Grum says this is the unique ID for the user, potentially for changing Minecraft names in future.
 +
 +
If the request is missing a parameter, the server will return "Bad response". If the login information is incorrect, the server will return "Bad login". If the login information is correct but the account isn't premium, the server will return "User not premium". If your minecraft.net account has been migrated to a Mojang account but you're logging in with your minecraft.net username the server will return "Acount migrated, use e-mail".
 +
 +
=== Keep-alive ===
 +
 +
Every 6000 ticks, the client sends an HTTPS request to
 +
<pre>https://login.minecraft.net/session?name=<username>&session=<session id></pre>
 +
The client discards the server's response.
  
  
 
[[Category:Protocol Details]]
 
[[Category:Protocol Details]]
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]

Revision as of 12:56, 15 July 2013

The minecraft client and server communicate with minecraft.net to validate player sessions. This page describes some of the operations.

Authentication

Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the previous authentication system.

Request format

All requests to Yggdrasil are made to the following server: 

 https://authserver.mojang.com

Further, they are expected to fulfill the following rules:

  • Are POST requests
  • Have the Content-Type header set to application/json
  • Contain a JSON-encoded dictionary as payload

If a request was successful the server will respond with:

  • Status code 200
  • A JSON-encoded dictionary according to the specifications below

If however a request fails, the server will respond with: 

{
  "error": "Short description of the error",
  "errorMessage": "Longer description which can be shown to the user",
  "cause": "Cause of the error"        // optional
}


Session ID

Whenever a Mojang service requires a session ID, you can simply combine a valid accessToken with a profile identifier as follows: 

 accessToken:profileID

Authenticate

This method is used whenever a user tries to log in using his password.

Endpoint

 /authenticate

Payload

{
  "agent": {
    "name": "Minecraft",                 // So far this is the only encountered value
    "version": 1                         // This number might be increased
                                         // by the vanilla client in the future
  },
  "username": "mojang account name",     // Can be an email address or player name for
                                         // unmigrated accounts
  "password": "mojang account password",
  "clientToken": "client identifier"     // optional
}

The clientToken should be a randomly generated identifier and must identical for each request. In case it is omitted the server will generate a random token based on Java's UUID.toString() which should then be stored by the client.

Response

{
  "accessToken": "random access token",  // hexadecimal
  "clientToken": "client identifier",    // identical to the one received
  "availableProfiles": [
    {
      "id": "profile identifier",        // hexadecimal
      "name": "player name"
    }
  ],
  "selectedProfile": {
    "id": "profile identifier",
    "name": "player name"
  }
 }

Note: If a user wishes to stay logged in on his computer you are strongly advised to store the received accessToken instead of the password itself.

Currently each account will only have one single profile, multiple profiles per account are however planned in the future.


Updating

To update, the launcher downloads files from 

http://s3.amazonaws.com/MinecraftDownload/

It takes the unix timestamp from the login request and stores it in ~/.minecraft/bin/version
The following files are downloaded from /MinecraftDownload/ in this exact order:

  • lwjgl.jar
  • jinput.jar
  • lwjgl_util.jar
  • minecraft.jar

And then the natives.jar appropriate for the following operating systems: windows, linux, macosx, and solaris

  • <os-from-list-above>_natives.jar.lzma

When downloading minecraft.jar, GET variables are set as follows: ?user=foo&ticket=deprecated, although they seem unnecessary to successfully downloading the file.
Furthermore, the downloaded files are all verified via MD5 which is sent via ETag by the server on the page for each file.

Further resources are stored in /MinecraftResources. Loading /MinecraftResources provides an XML formatted list of resources, some of which are downloaded by Minecraft and not the launcher.

Updating 1.6

With the new launcher updating happens by downloading information from https://s3.amazonaws.com/Minecraft.Download/versions/versions.json and https://s3.amazonaws.com/Minecraft.Download/versions/1.6.2/1.6.2.json


Snoop

Every 15 minutes, minecraft sends a HTTP POST request giving stats. This can be disabled in server.properties

Field Client Server Example Notes
applet Yes No true
avg_rec_packet_count No Yes 0
avg_rec_packet_size No Yes 0
avg_sent_packet_count No Yes 6
avg_sent_packet_size No Yes 44
avg_tick_ms No Yes 3
client_brand Yes No vanilla via ClientBrandRetriever.getClientModName()
cpu_cores Yes Yes 2 via Runtime.getRuntime().availableProcessors()
dedicated No Yes true
display_frequency Yes No 60 via org.lwjgl.opengl.Display.getDisplayMode().getFrequency()
display_type Yes No windowed windowed or fullscreen
fps Yes No 60
gl_caps[key] Yes No varies by key via org.lwjgl.opengl.GLContext.getCapabilities().GL_ARB_key
gl_max_texture_size Yes No 8192
gui_state No Yes disabled enabled or disabled
gui_supported No Yes headless via java.awt.GraphicsEnvironment.isHeadless() (headless or supported)
java_version Yes Yes 1.6.0_24 via System.getProperty("java.version")
jvm_arg[n] Yes Yes -Xms2800M via java.lang.management.ManagementFactory.getRuntimeMXBean().getInputArguments() (-X args only)
jvm_args Yes Yes 2 see above
memory_free Yes Yes 2429082024 via Runtime.getRuntime().freeMemory()
memory_max Yes Yes 2813722624 via Runtime.getRuntime().maxMemory()
memory_total Yes Yes 2813722624 via Runtime.getRuntime().totalMemory()
opengl_vendor Yes No NVIDIA Corporation via GL11.glGetString(GL_VENDOR)
opengl_version Yes No 3.3.0 NVIDIA 302.17 via GL11.glGetString(GL_VERSION)
os_architecture Yes Yes amd64 via System.getProperty("os.arch")
os_name Yes Yes Linux via System.getProperty("os.name")
os_version Yes Yes 3.2.0-3-amd64 via System.getProperty("os.version")
players_current No Yes 0
players_max No Yes 20
players_seen No Yes 4 counts files in world/players
server_brand No Yes vanilla via getServerModName() (hardcoded to "vanilla", overwritten by bukkit et al)
singleplayer No Yes false whether or not the server is running to support a singleplayer session
snooper_count Yes Yes 0 how many times the snooper has reported so far
snooper_token Yes Yes dfe921ac-0293-4e42-8d99-1316cdd626d8 via java.util.UUID.randomUUID().toString() (unique per program launch)
texpack_name Yes No Default
texpack_resolution Yes No 16
uses_auth No Yes true corresponds to online-mode in server.properties
version Yes Yes 1.4.2
vsync_enabled Yes No true
whitelist_count No Yes 0
whitelist_enabled No Yes false
world[n][chunks_loaded] No Yes 978
world[n][difficulty] No Yes 1
world[n][dimension] No Yes 0
world[n][generator_name] No Yes default
world[n][generator_version] No Yes 1
world[n][hardcore] No Yes false
world[n][height] No Yes 256
world[n][mode] No Yes SURVIVAL
worlds No Yes 3

Joining a Server

See Protocol Encryption for details on encrypting connections.

Client operation

  1. Client connects to server
  2. Client sends a 0x02 handshake containing the current player name
  3. Client receives an 0xFD encryption request with the server's public key and four verification bytes.
  4. Client generates a symmetric key.
  5. Client sends a HTTP request to 
    http://session.minecraft.net/game/joinserver.jsp?user=<player name>&sessionId=<session id>&serverId=<server hash>
    Note: See the Session ID section on how the <session id> is generated.
    If the response is OK then continue, otherwise stop
  6. Client sends 0xFC encryption response - client encrypts shared secret and verification token with the server's public key
  7. Server checks validity and sends 0xFC encryption response with two empty arrays
  8. Both sides enable AES/CFB2 encryption using the shared secret generated by the client
  9. Client sends 0xCD client status with a payload of 0 (ready to spawn)
  10. Server sends 0x01 login
  11. ... receive map chunks, etc...

Server operation

  1. Server generates a 1024-bit RSA keypair.
  2. ...
  3. Server answers TCP connection request and receives a 0x02 handshake from the client.
  4. Server sends 0xFD encryption request with its public key and a verification token.
  5. Server receives 0xFC encryption response from client and decrypts the shared secret.
  6. Server verifies the validity of the verification token. If this isn't verified, it kicks the client.
  7. Server sends a HTTP request to 
    http://session.minecraft.net/game/checkserver.jsp?user=<username>&serverId=<server hash>
    If it returns YES then the client is authenticated and allowed to join. Otherwise the client will/should be kicked with “Failed to verify username!”
  8. Server sends a 0xFC encryption response packet with two empty arrays.
  9. Both sides enable AES/CFB2 encryption.
  10. Server receives 0xCD client status with a payload of , indicating "ready to spawn"
  11. Server sends 0x01 login
  12. ... send map chunks, etc...


Outdated authentication system

This system was used by Minecraft versions prior to 1.6 and might be discontinued at any moment without warning.

Login

To log the player in, the official launcher sends an HTTPS POST (GET appears to suffice as well) request to: 

https://login.minecraft.net

with the postdata: 

 ?user=<username>&password=<password>&version=<launcher version>

and a "application/x-www-form-urlencoded" Content-Type header.

After migrating to Mojang accounts, email address is used instead of username, but the procedure stays the same.

The current launcher version is "13" (for new launcher it's "14"), sending a value lower than 12 will cause the server to return "Old version", however you can send any large number and it will return as expected. If the login succeeded, it will return 5 ':' delimited values. 

 1343825972000:deprecated:SirCmpwn:7ae9007b9909de05ea58e94199a33b30c310c69c:dba0c48e1c584963b9e93a038a66bb98
  1. current version of the game files (not the launcher itself). This is a unix timestamp which the launcher compares to the ~/.minecraft/bin/version file.
  2. Previously contained a download ticket for requesting new versions of minecraft.jar from the server. Now contains only "deprecated".
  3. case-correct username. For mojang accounts, the user's actual username is returned here instead of the email used to log in.
  4. sessionId - a unique ID for your current session.
  5. UID - currently unused, introduced near August 8th, 2012. Grum says this is the unique ID for the user, potentially for changing Minecraft names in future.

If the request is missing a parameter, the server will return "Bad response". If the login information is incorrect, the server will return "Bad login". If the login information is correct but the account isn't premium, the server will return "User not premium". If your minecraft.net account has been migrated to a Mojang account but you're logging in with your minecraft.net username the server will return "Acount migrated, use e-mail".

Keep-alive

Every 6000 ticks, the client sends an HTTPS request to 

https://login.minecraft.net/session?name=<username>&session=<session id>

The client discards the server's response.

Retrieved from "https://wiki.vg/index.php?title=Session&oldid=4165"