Multiplayer authentication API - Revision history

Xiretza: /* Response */

2024-10-18T22:17:44Z

Response

← Older revision		Revision as of 22:17, 18 October 2024
Line 70:		Line 70:
	\| <code>server_key</code> \|\| string \|\| Base-64 encoded user-server-key		\| <code>server_key</code> \|\| string \|\| Base-64 encoded user-server-key
	\|-		\|-
	\| <code>server_key_timestamp</code> \|\| string \|\| Timestamp when <code>server_key</code> was issued, in <code>~~YYMMDDhhmmss~~</code> format		\| <code>server_key_timestamp</code> \|\| string \|\| Timestamp when <code>server_key</code> was issued, in <code>yymmddHHMMSS</code> format
	\|}		\|}

Xiretza at 22:13, 18 October 2024

2024-10-18T22:13:44Z

← Older revision		Revision as of 22:13, 18 October 2024
Line 9:		Line 9:
	== API endpoints ==		== API endpoints ==

	=== <code>/generate-server-padlock-2</code> ===		=== <code>POST /generate-server-padlock-2</code> ===

	This endpoint is called by the game server once on startup to obtain a public identifier and a shared secret.		This endpoint is called by the game server once on startup to obtain a public identifier and a shared secret.
Line 35:		Line 35:
	\|}		\|}

	=== <code>/generate-user-server-key-2</code> ===		=== <code>POST /generate-user-server-key-2</code> ===

	This endpoint is called by a client when attempting to join a game server.		This endpoint is called by a client when attempting to join a game server.

Xiretza: Xiretza moved page User:Xiretza/Sandbox/Multiplayer authentication API to Multiplayer authentication API

2024-10-18T22:12:06Z

Xiretza moved page User:Xiretza/Sandbox/Multiplayer authentication API to Multiplayer authentication API

← Older revision		Revision as of 22:12, 18 October 2024
(No difference)

Xiretza at 22:11, 18 October 2024

2024-10-18T22:11:05Z

← Older revision		Revision as of 22:11, 18 October 2024
Line 20:		Line 20:
	! Key !! Description		! Key !! Description
	\|-		\|-
	\| <code>api_version</code> \|\| ~~always set~~ to <code>6</code> ~~by clients~~		\| <code>api_version</code> \|\| Set to <code>6</code> in all observed requests
	\|}		\|}

Line 46:		Line 46:
	! Key !! Description		! Key !! Description
	\|-		\|-
	\| <code>api_version</code> \|\| ~~always set~~ to <code>6</code> ~~by clients~~		\| <code>api_version</code> \|\| Set to <code>6</code> in all observed requests
	\|}		\|}

Xiretza at 22:10, 18 October 2024

2024-10-18T22:10:10Z

← Older revision		Revision as of 22:10, 18 October 2024
Line 95:		Line 95:

	The game server should additionally verify that the <code>server_key_timestamp</code> is not too far in the past (so leaked user-server-keys cannot be reused indefinitely), but it is currently unknown whether this is done, and if so, what the expiry time is.		The game server should additionally verify that the <code>server_key_timestamp</code> is not too far in the past (so leaked user-server-keys cannot be reused indefinitely), but it is currently unknown whether this is done, and if so, what the expiry time is.

			[[Category:Technical]]

Xiretza at 22:09, 18 October 2024

2024-10-18T22:09:30Z

← Older revision		Revision as of 22:09, 18 October 2024
Line 10:		Line 10:

	=== <code>/generate-server-padlock-2</code> ===		=== <code>/generate-server-padlock-2</code> ===

			This endpoint is called by the game server once on startup to obtain a public identifier and a shared secret.

	==== Request ====		==== Request ====
Line 28:		Line 30:
	! Key !! Type !! Description		! Key !! Type !! Description
	\|-		\|-
	\| <code>server_padlock</code> \|\| string \|\| ~~Opaque random string, shared~~ secret between game server and auth server		\| <code>server_padlock</code> \|\| string \|\| Shared secret between game server and auth server, opaque string
	\|-		\|-
	\| <code>server_hash</code> \|\| string \|\| ~~Opaque game server~~ identifier		\| <code>server_hash</code> \|\| string \|\| Server identifier, opaque string
	\|}		\|}

	=== <code>/generate-user-server-key-2</code> ===		=== <code>/generate-user-server-key-2</code> ===

			This endpoint is called by a client when attempting to join a game server.

	==== Request ====		==== Request ====
Line 54:		Line 58:
	\| <code>token</code> \|\| User auth token, as obtained from the [[Web authentication API]]		\| <code>token</code> \|\| User auth token, as obtained from the [[Web authentication API]]
	\|-		\|-
	\| <code>sever_hash</code> \|\| ~~Server~~'s identifier, transmitted during connection establishment		\| <code>sever_hash</code> \|\| Game server's identifier, transmitted during connection establishment
	\|}		\|}

Line 71:		Line 75:
	== User-server-key algorithm ==		== User-server-key algorithm ==

	The game server verifies the join by calculating its own version of the user-server-key using the <code>server_padlock</code>, username, and <code>server_key_timestamp</code>. If it matches the <code>server_key</code> transmitted by the client, it ~~knows that it was~~ generated by the authentication server, attesting the validity of the user's credentials.		The game server verifies the join by calculating its own version of the user-server-key using the <code>server_padlock</code>, username, and <code>server_key_timestamp</code>. If it matches the <code>server_key</code> transmitted by the client, it must have been generated by the authentication server (because only it shares knowledge of the server padlock), thereby attesting the validity of the user's credentials.

	The algorithm is as follows:		The algorithm is as follows:

	1. Concatenate the padlock, username and timestamp strings, separated by underscores.		# Concatenate the padlock, username and timestamp strings, separated by underscores.
	2. Generate an MD5 HMAC over the resulting string, with the server padlock as the key		# Generate an MD5 HMAC over the resulting string, with the server padlock as the key
	3. Base64-encode the result		# Base64-encode the result

	As an illustrative example, using shell commands:		As an illustrative example, using shell commands:

	<~~pre~~>		<syntaxhighlight lang="bash">
	$ padlock=ZjX+YSCEZgdFMVCzLLt8F8NOoWAmAG9WkUwv1dir4gg=		$ padlock=ZjX+YSCEZgdFMVCzLLt8F8NOoWAmAG9WkUwv1dir4gg=
	$ username=Xiretza		$ username=Xiretza
Line 88:		Line 92:
	$ printf '%s_%s_%s' "$username" "$padlock" "$timestamp" \| openssl mac -digest md5 -macopt "key:$padlock" -binary HMAC \| base64		$ printf '%s_%s_%s' "$username" "$padlock" "$timestamp" \| openssl mac -digest md5 -macopt "key:$padlock" -binary HMAC \| base64
	nV89TIBaIOvwUDQwrdK0/Q==		nV89TIBaIOvwUDQwrdK0/Q==
	</~~pre~~>		</syntaxhighlight>

			The game server should additionally verify that the <code>server_key_timestamp</code> is not too far in the past (so leaked user-server-keys cannot be reused indefinitely), but it is currently unknown whether this is done, and if so, what the expiry time is.

Xiretza at 21:59, 18 October 2024

2024-10-18T21:59:51Z

@@ Line 28: / Line 28: @@
 ! Key !! Type !! Description
 |-
-| <code>server_padlock</code> || string || Opaque random string
+| <code>server_padlock</code> || string || Opaque random string, shared secret between game server and auth server
 |-
-| <code>server_hash</code> || string || Opaque identifier generated from the <code>server_padlock</code> and a secret internal to the auth server
+| <code>server_hash</code> || string || Opaque game server identifier
 |}

Xiretza: Created page with "
'''Category:''' Internal API
The multiplayer authentication API allows multiplayer servers (be they dedicated headless servers or games hosted from within a client) to verify that a connecting user is who they claim to be. An overview of the API architecture is given in [https://www.factorio.com/blog/post/fff-139 FFF-139]. All endpoints are..."

2024-10-18T21:43:54Z

Created page with "<div align="center" class="stub">'''Category:''' Internal API</div> The multiplayer authentication API allows multiplayer servers (be they dedicated headless servers or games hosted from within a client) to verify that a connecting user is who they claim to be. An overview of the API architecture is given in [https://www.factorio.com/blog/post/fff-139 FFF-139]. All endpoints are..."

New page

<div align="center" class="stub">'''Category:''' [[Factorio_HTTP_API_usage_guidelines#Internal|Internal API]]</div>

The multiplayer authentication API allows multiplayer servers (be they dedicated [[Multiplayer#Dedicated/Headless_server|headless servers]] or games hosted from within a client) to verify that a connecting user is who they claim to be.

An overview of the API architecture is given in [https://www.factorio.com/blog/post/fff-139 FFF-139].

All endpoints are relative to the <code>https://auth.factorio.com/</code> URL.

== API endpoints ==

=== <code>/generate-server-padlock-2</code> ===

==== Request ====

{| class="wikitable"
|+ Query parameters
|-
! Key !! Description
|-
| <code>api_version</code> || always set to <code>6</code> by clients
|}

==== Response ====

{| class="wikitable"
|+ JSON body
|-
! Key !! Type !! Description
|-
| <code>server_padlock</code> || string || Opaque random string
|-
| <code>server_hash</code> || string || Opaque identifier generated from the <code>server_padlock</code> and a secret internal to the auth server
|}