Concepts

SqexArg

This is the “encrypted argument” format used by a lot of FFXIV programs and is used in place of regular plaintext command line arguments. However, this is barely a security measure and just prevents easily snooping stuff like your login token. Despite this, the SqexArg format is well known, reversible and easily breakable.

Format #

When viewing the command line arguments for, say ffxiv.exe you will see it’s only something like this:

//**sqex0003S2_Utl8qdamv3_82SH7Lhtk=S**//

(Yes, I did garble some of the text, so it’s not actually decodable :-))

There are three distinct parts of this string:

//**sqex0003S2_Utl8qdamv3_82SH7Lhtk=S**//
           ^^                       ^
    version||                       |
            | base64 string         |
                                    | checksum

Let’s break them down:

Encryption Algorithm #

The resulting bytes when you decode the base64 string is going to Blowfish ECB encrypted.

Note: In the new Steam launcher update, Square Enix has actually switched to a more sane version of Blowfish ECB without their weird changes. Please look at XIVQuickLauncher for the changes required, as I have not tested this yet.

Key #

The key used for encrypting/decrypting the encrypted arguments is just your system’s uptime clock. All FFXIV executables just call GetTickCount(), and theres about ~50 or so ticks of freedom before the game or launcher considers it invalid. There is a specific transformation you need to do in order to fetch a valid key though:

unsigned int rawTicks = TickCount();
unsigned int ticks = rawTicks & 0xFFFFFFFFu;
unsigned int key = ticks & 0xFFFF0000u;

char buffer[9] = {};
sprintf(buffer, "%08x", key);

To make this easier, here is a couple of platform-specific implementations of TickCount(). Thank you Wine for being easily searchable, as this is what Wine is actually doing under the hood to emulate GetTickCount(), so these are exact and have been tested on Astra for all platforms.

Windows #
uint32_t TickCount() {
    return GetTickCount();
}
macOS #
uint32_t TickCount() {
    struct mach_timebase_info timebase;
    mach_timebase_info(&timebase);

    auto machtime = mach_continuous_time();
    auto numer = uint64_t (timebase.numer);
    auto denom = uint64_t(timebase.denom);
    auto monotonic_time = machtime * numer / denom / 100;
    return monotonic_time / 10000;
}
Linux #
uint32_t TickCount() {
    struct timespec ts;

    clock_gettime(CLOCK_MONOTONIC, &ts);

    return (ts.tv_sec * 1000 + ts.tv_nsec / 1000000);
}

Checksum #

If you’re just interested in decrypting game arguments, this is not essential. This is presumably used as a checksum when the game checks your encrypted string.

static char ChecksumTable[] = {
    'f', 'X', '1', 'p', 'G', 't', 'd', 'S',
    '5', 'C', 'A', 'P', '4', '_', 'V', 'L'
};

static char GetChecksum(unsigned int key) {
    auto value = key & 0x000F0000;
    return ChecksumTable[value >> 16];
}

Decrypting #

You can try the dedicated argcracker in Novus for this purpose. It allows you to easily crack any SqexArg enabled program assuming you have access to the string.

Notes #

Every instance where SqexArg is used, the first argument is always T, where T is set to the value of ticks (as shown above). I’m not sure what the purpose of this really is, maybe for verifying the checksum?

The arguments (before encoding of course) must be formatted as " /%1 =%2". The extra space is required, even at the beginning of the arguments. Make sure that any spaces in your string is double padded as well.

See Also #

Implementations #

Packets

Communication between the client and Servers happen with custom, binary packet structures sent over TCP.

Packets #

Each packet begins with a header, that is always the same size and is never encrypted or compressed:

struct PacketHeader {
    unk1: u64, /// Unknown value
    unk2: u64, /// Another unknown value
    timestamp: u64, /// Milliseconds since UNIX epoch 
    size: u32, /// Total size of the packet *INCLUDING* this header
    connection_type: ConnectionType, /// The connection this happened on
    segment_count: u16, /// How many segments follow this header
    unk3: u8, /// Yet another unknown value
    compression_type: CompressionType, /// The type of compression used for segment data
    unk4: u16, /// Whoop, more unknowns
    uncompressed_size: u32, /// If compressed, the size of the data when uncompressed. Otherwise, always 0.
}

Logical Data Center

These are data centers.

Logging into Official Servers

Note

This only covers logging in via non-Steam Square Enix accounts right now.

Logging into the official FFXIV servers is actually very simple, and all you need is the ability to send/receive HTTP requests, parse JSON responses and read some files off of the disk.

If you’re wondering about the safety of these calls, as long as you don’t do anything stupid (i.e. throw a 1 megabyte username into a form) then your account is safe. I guess Square Enix doesn’t care about these endpoints too much, because even if you log into the game legitimately a hundred times in an hour they don’t care. However, if you try logging into the account with invalid credentials, then it might get locked.

You’ll also notice the variable {unique_id} used in some of the User Agents. This is a unique id used by the official launcher, for an unknown purpose. However, any sort of unique ID will work.

Checking the Gate Status #

First you must check the gate status from the Frontier server, which tells if the servers are under maintenance. The legitimate launcher will not allow you to log in if the gate is closed. Square Enix does not expect legitimate users to enter servers under maintenance, not that you even can.

GET https://frontier.ffxiv.com/worldStatus/gate_status.json

The response is a simple JSON as follows:

{
    "status": 1
}

If the status is 1, the gate is open and you’re free to log in. Any other value should indicate that you should not attempt to log in, the gate is “closed”.

Boot Update Check #

You also need to ensure that the boot components of the game are properly updated by contacting the boot patch server.

Note

This is not a typo, and this endpoint is actually in plaintext HTTP…

GET http://patch-bootver.ffxiv.com/http/win32/ffxivneo_release_boot/{boot_version}

If you receive an empty response, then you don’t need to update any of your boot components and proceed to the next step. However if your boot components are out of date, you will receive a list of patches to update.

Getting STORED #

GET https://ffxiv-login.square-enix.com/oauth/ffxivarr/login/top

The response is actually fully formed HTML, most likely better suited for the real launcher where it’s a web browser. However, if you have regex available, you can query the variables needed for later.

Note

If you’re logging in with a Steam service account, you can find your username using `<input name=

To get the _STORED_ value, use \t<\s*input .* name="_STORED_" value="(?<stored>.*)"> and use the second captured variable. You also need to the store the full URL of this request (including all of the queries) for use in the next request.

If you get an error during this response, it may indicate that the Square Enix servers are down for maintenance.

Logging in #

Now it’s time to perform the first step of logging in:

POST https://ffxiv-login.square-enix.com/oauth/ffxivarr/login/login.send

Just like the previous request, you will get a pretty disgusting HTML response. You will need some way to parse this data, but we have some regex queries to get you started.

The response may have multiple parts depending on how you log in, and if the login was successful. Start with this: window.external.user\("login=auth,ok,(?<launchParams>.*)\); to get the launch parameters.

If you do not manage to get a match, this means there is a general account error. Luckily, Square Enix actually gives us an error message! Match this regex query now: window.external.user\("login=auth,ng,err,(?<launchParams>.*)\);. The second capture has a comma-separated string that contains the relevant error message such as “Account locked due to too many attempts.”

However if you do get a match, that’s good but there’s still quite a bit of parsing to do. First you’ll want to split the second captured group since it’s a comma-separated string. There are multiple parts which we’ll refer to by name:

First you’ll want to check if the account is even playable, which of course is checking to see if {playable} is 1. This may indicate billing or license issues with that account. You’ll want to check if {terms} is 1 as well, which indicates that there’s a terms of service agreement the account must sign.

The {SID}, {region} and {max_expansion} will be needed later, so store these variables.

Now that we got an SID, you may expect that we can now log into the game! Well you’d be wrong, as we still have to register a session with the lobby server. If you attempt to launch the client with the {SID} you got, the lobby server will disconnect you as soon as you log in.

Calculating the boot hash #

We need to calculate the hashes of everything in the boot directory. Why you ask? I guess this is Square Enix’s idea of security.

Here’s the files we need to hash:

We now build a string like this:

{file_name}/{file_hash},...

Please note that it’s comma separated and there is no newlines. The file hash is simply the SHA1 of the file (yes, really, SHA1). However, it’s not just the SHA1 and must also be sent with the file size in bytes:

{file_size}/{file_sha1}

The final string might look something like this:

ffxivboot.exe/256/fea677811b91f51a9f66dcb809a94ddac480f054,ffxivboot64.exe...

You’ll want to store this completed hash as the variable {boot_hash} for the next step.

Registering a Session #

Square Enix expects the launcher to pass it’s “security check” next, and this request will also check for if any game updates are required too.

Note

{game_version} is referring to the version stored in $GAME_DIR/game/ffxivgame.ver.

POST https://patch-gamever.ffxiv.com/http/win32/ffxivneo_release_game/{game_version}/{SID}

Before you can POST this request, you need to build a report of all of your installed game versions as well as some hashes. This is simply a string in the body of the HTTP request.

The string is built as follows:

{boot_version}={boot_hash}\n
ex1\t{ex1_version}\n
...

Please note that the client must report all of it’s installed expansions. The base game version is already reported in the request URL itself, so you should start at “ex1”. Each entry in this body is separated by newlines, except for the last entry. Yes, the \t in the body is referring to the tab character.

Once you send this request, there may or may not be a response body. First you’ll want to check for the response header called X-Patch-Unique-Id, if this found then you’ve actually successfully registered a session! If this is missing, you may have triggered the anti-tamper check, or the game requires an update.

The {true_SID} is now the value of the X-Patch-Unique-ID field. Congratulations, you now logged into the game!

Launching the game #

Now you can launch the game! See ffxiv.exe for more arguments.

Game Masters

These are moderators in the game, and can be called upon when reporting a player. To carry out their tasks, they are given access to special commands not available to normal players. If a normal player attempts to use a command, nothing happens - the client won’t even send it unless they have a GM rank.

Ranks #

There is not a single “rank” or “level” of GM, but in fact several. This probably mirrors the same structure seen in XI, where there are Junior GMs lead by one or more senior GMs. There are also event GMs?

Commands #

Since we don’t have access to any documentation to what these commands do, the purpose and usage are guesswork.

CommandDescription
//gm invisTurns the current player invisible.

Equipment

Note

This documentation is incomplete nd may be missing information for weapons, demihumans, other races and slot types.

This is useful for people implementing similar TexTools or FFXIV Explorer functionality, and it’s actually trivial to do so. Before you can do so, you must be able to read Excel data sheets.

Read item data #

The Excel sheet you’re interested is called item and since it also contains localized names make sure to choose the relevant language sheet. Once you have done so, you’re interested in a couple of columns (tested as of 6.1):

Reading the slot id #

You’ll get an integer from the slot item column, and this corresponds to a specific slot:

IntegerSlot
3Head
4Body
5Hands
7Legs
8Feet
9Earring
10Neck
11Wrists
12Rings

Reading the model data #

There are two separate integers, primary and secondary. Right now, we’re only interested in the first 2 bytes of the primary integer - this is your primary ID.

Grabbing the equipment path #

chara/equipment/e{model_id:04d}/model/c{race_id:04d}e{model_id:04d}_{slot}.mdl

{race_id} is the race-specific equipment you want. {model_id} is the primary model id.

Note: :04d means that it must be padded with 4 zeroes.

Content ID

This is a unique number assigned to each player character.

Client-Side Scripts

Events are scripted using Lua, and are shipped with the client as bytecode. One example is game_script/quest/047/FesSxt103_04798.luab, notice the .luab extension.

The version of Lua used in the client is Lua 5.1. They don’t seem to modify much - if any - of the base Lua state - including dangerous stuff like the os module that’s not needed for client-side scripts.

Decompiling #

Decompiling the bytecode is trivial, one tool that can be used is unluac. But there many other 5.1 decompilers available online.

Since only the bytecode remains, there’s very little useful information left in the file. Much of the logic and API calls are intact though!

API #

Here are the currently known functions of the API:

Class Pc #

IsWarriorOfLight() → boolean

Unknown purpose. But probably returns true if the player character is legacy (1.x).

IsHowTo{id=…} → boolean

Unknown purpose.

Class EventHandler #

See game_script/system/EventHandler.luab for various constants used throughout event scripts.

PlayBGM{id=…}

Unknown purpose. But probably plays BGM.

FadeOut{unk=…}

Unknown purpose. But probably fades out the screen.

WaitForFade()

Unknown purpose. But probably waits for the current fade to stop animating.

BeginCutScene()

Unknown purpose. But probably starts preparing a cutscene to play.

PlayCutScene{unk=…}

Unknown purpose. But probably plays a cutscene.

EndCutScene()

Unknown purpose. But probably ends the current cutscene.

DisableSceneSkip()

Unknown prupose. But probably prevents the player from skipping the cutscene.

FadeIn{unk=…}

Unknown purpose. But probably starts a fade in animation.

EnableSceneSkip()

Unknown purpose. But probably allows the player to skip the cutscene.

LoadMovePosition{unk=…}

Unknown purpose.

HowTo{id=…}

Unknown purpose.

GetTerritoryType() → unk

Unknown purpose. But probably returns the current territory type id.

PlayLandscapeCamera{unk=…}

Unknown purpose. But probably moves the current camera to a set landscape camera.

Zoom{unk=…, unk=…, unk=…, unk=…, unk=…}

Unknown purpose. But probably begins zooming the camera.

Wait{unk=…}

Unknown purpose. But probably waits for a set amount of time.

UpdownPan{unk=…, unk=…, unk=…, unk=…, unk=…}

Unknown purpose. But probably pan related.

SidePan{unk=…, unk=…, unk=…, unk=…, unk=…}

Unknown purpose. But probably pan related.

PlayScreenShake{unk=…, unk=…, unk=…}

Unknown purpose. But probably starts shaking the screen.

StopScreenShake{unk=…}

Unknown purpose. But probably stops shaking the screen.

ScreenImage{unk=…}

Unknown purpose. But probably shows a set image on the screen.

Class Opening #

EnableEventRange{unk=…, unk=…, unk=…}

Unknown purpose.

DisableEventRange{unk=…, unk=…, unk=…}

Unknown purpose.

Class Chara extends Actor #

Move{unk=…, unk=…, unk=…}

Unknown purpose. But probably moves the character to a specified position.

WaitForMove()

Unknown purpose. But probably waits until the character has stopped moving.

Class Actor #

EndEventRollback{unk=…, unk=…}

Unknown purpose.

Account ID

This is a unique number assigned to a service account.