This post details how the implementation works and how to use it.

Background

Matrix Cards are a relatively niche form of two factor authentication where the client is tested on partial elements of a Pre-shared Key. The client is first given a Matrix Card in the form of either a document or a physical card akin to the one shown in figure 1.

The Chinese text in the top left means “Serial Number:”. This card is very unlikely to have been used with the Wrath of the Lich King or prior clients since it has a variable number of digits per field, which this algorithm does not support, however it can still be used to illustrate how the system works.

The server would ask the client which digits are in cell “A6” and the client would enter “483”. This would repeat for however many rounds the server has requested. The results are then hashed and the proof is sent by the client. The server makes the same calculations and compares the hashes. If they are identical the client knows the layout of the Matrix Card.

The server may send a width, height, digit count, challenge count, and seed in CMD_AUTH_LOGON_CHALLENGE_Server ^wiki . The client may send the resulting proof in CMD_AUTH_LOGON_PROOF_Client ^wiki . Real clients will always reply with a proof if the fields from the server message are present.

If the server also sends the fields required for PIN authentication the PIN prompt will be displayed first, followed by the Matrix Card prompt.

Figure 2 shows the complete login process in a 3.3.5 client with Matrix Card validation with a width of 10 and height of 20, digit count of 3, and challenge count of 2.

Implementation details

This section describes how to implement the algorithm on a function-by-function basis. A completelely functional program will only be possible when everything has been implemented.

The wow_srp Rust crate implements the full algorithm. This Github Gist by Barncastle implements the full algorithm in C#.

The algorithm requires keeping the state of in progress RC4 and HMAC-SHA1 objects alive while the algorithm is executed.

Generate Coordinates

The coordinates control which fields are checked.

• width is the width sent by the server.
• height is the height sent by the server.
• challenge_count is the challenge count/rounds sent by the server.
• seed is the seed sent by the server.
• % is the modulus operator.

Generating the coordinate array in pseudo code:

function generate_coordinates
    argument width: u8
    argument height: u8
    argument challenge_count: u8
    argument seed: u64
    returns array of u32s

    # width, height, and challenge_count can not be 0
    # challenge_count must be greater than or equal to width * height


    matrix_indices = array of (width * height) u32s that where the value is the same as the index
    # So if width * height was 4 the matrix_indices would be [0, 1, 2, 3]

    coordinates = array of challenge_count u32s

    for i, coordinate in enumerate(coordinates):
        count = len(matrix_indices) - i;
        index = seed % count;

        coordinate = matrix_indices[index];

        for j in index..(count - 1) {
            matrix_indices[j] = matrix_indices[j + 1];
        }

        seed /= count;

    return coordinates

Implementations

• Rust (wow_srp)
• C# (Barncastle Gist)

Verification values

• coordinates_regression contains the columns:

Create new objects

This function creates the coordinates, rc4, and hmac objects required for further functions.

• width is the width sent by the server.
• height is the height sent by the server.
• challenge_count is the challenge count/rounds sent by the server.
• seed is the seed sent by the server.
• session_key is the 40 byte session key created by the SRP6 algorithm.
• MD5 is the MD5 hash function.
• HMAC-SHA1 is the HMAC-SHA1 function.
• RC4 is the RC4 function.
• + is array concatenation

Creating the objects in pseudo code:

function create_new_objects
    argument width: u8
    argument height: u8
    argument challenge_count: u8
    argument seed: u64
    argument session_key: array of 40 bytes
    returns in-progress HMAC-SHA1, in-progress RC4, array of u32s

    coordinates = generate_coordinates(width, height, challenge_count, seed)

    md5 = MD5(seed as little endian array + session_key)

    # Do not drop anything, unlike headers dropping 1024
    rc4 = RC4(md5)

    hmac = HMAC-SHA1(md5)

    return hmac, rc4, coordinates

Implementations

• Rust (wow_srp)
• C# (Barncastle Gist)

Verification values

There are no verification values for this function since the HMAC and RC4 ciphers aren’t finished, and the coordinates are verified in Generate Coordinates.

Get Coordinate

This function returns the (x, y) location on the pre shared key that should be entered using Enter Value.

• width is the width sent by the server.
• height is the height sent by the server.
• challenge_count is the challenge count/rounds sent by the server.
• round is the iteration number. So the first iteration would be 0, the second 1, and so on.
• coordinates is the array created by Generate Coordinates.

Getting coordinates in pseudo code would look like:

function get_coordinate
    argument challenge_count: u8
    argument coordinates: array of u32s
    argument width: u8
    argument height: u8
    argument round: u8
    returns u8, u8

    # round can not be greater than challenge_count

    coord = coordinates[round]

    x = coord % width
    y = coord / width

    # y can not be greater than or equal to height
    return x, y

Implementations

• Rust (wow_srp) Rust test implementation
• C# (Barncastle Gist)

Verification Values

• get_coordinate_regression contains the columns:

Enter Digit

Enters a single digit from a cell. Digits should be in the range [0;9] and should be entered one by one. Nothing needs to be done in between rounds.

Entering digits in pseudo code would look like:

function enter_digit
    argument rc4: in progress RC4 object created by create_new_objects
    argument hmac: in progress HMAC-SHA1 object created by create_new_objects
    argument value: u8

    new_value = rc4.apply(value)
    hmac.apply(new_value)

Implementations

• Rust (wow_srp) Rust test implementation
• C# (Barncastle Gist)

Verification Values

Since this function doesn’t provide any output there are no verification values. Test this using Create Proof instead.

Create Proof

Finalizes the proof after digits have been entered.

In pseudo code it would look like:

function create_proof
    argument hmac: in progress HMAC-SHA1 object created by create_new_objects
    returns array of 20 bytes

    return hmac.finalize()

Implementations

• Rust (wow_srp)
• C# (Barncastle Gist)

Verification Values

• proof_regression contains the columns:

Usage

Usage in pseudo code would look like:

width = 26
height = 26
challenge_count = 2
digit_count = 3
seed = random()
session_key = a valid generated session key

hmac, rc4, coordinates = create_new_objects(width, height, challenge_count, seed, session_key)

for round in 0..challenge_count:
    x, y = get_coordinate(challenge_count, coordinates, width, height, round)
    digits = use x and y to get the cell digits
    for digit in digits:
        value = enter_digit(rc4, hmac, digit)

create_proof(hmac)

# Send the proof to the server, or compare it with what the client sent

Background

The server may send a PIN grid seed and PIN salt in CMD_AUTH_LOGON_CHALLENGE_Server ^wiki if it chooses. The client may send the PIN salt and client PIN hash in CMD_AUTH_LOGON_PROOF_Client ^wiki in the field just after the client proof.

Figure 1 shows the PIN window during login.

The client does not require the server to prove that expected key matches like it does for the primary authentication check.

This will work for all versions after 1.12.

The PIN the client enters can either be a static (it never changes) or be time based, the client just sends the digits entered by the user.

PINs can be between 4 and 10 digits long.

The implementation is the same for the server and client. They will both calculate a hash for the entered digits and the server will then compare the two hashes for equality.

The grid of the PIN can be randomized with the PIN grid seed sent by the server. This will move the locations of the numbers so that they are no longer in order. So instead of the keypad being 1, 2, 3, ..., it could be 9, 2, 5, .... Figure 2 shows the randomized PIN window.

Implementation details

The algorithm goes through the following steps:

• Get the PIN from the client or database.
• Use the PIN grid seed to randomize the grid.
• Apply the randomized grid to the PIN.
• Convert PIN to ASCII by adding 0x30 (48) to every value.
• The PIN is SHA1 hashed twice along with server and client salts.

The PIN is in the form of a byte array of at least 4 bytes and at most 10 bytes, where every byte is a single digit of the PIN. So a PIN of 1, 2, 3, 4 would be an array of [1, 2, 3, 4].

Main Algorithm

This function ties everything together.

• pin is the digits of the PIN code as a byte array.
• pin_grid_seed is the PIN grid seed.
• server_salt is the salt sent by the server.
• client_salt is the salt sent by the client.
• % is the modulus operator.
• + is array concatenation.
• SHA1 is the SHA1 hash function.

function calculate_hash
    argument pin: array of bytes
    argument pin_grid_seed: u32
    argument server_salt: array of 16 bytes
    argument client_salt: array of 16 bytes
    returns array of 20 bytes

    remapped_pin_grid = remap_pin_grid(pin_grid_seed)

    randomized_grid = randomize_grid(pin, remapped_pin_grid)

    # Convert to ASCII
    for b in randomized_grid:
        b += 0x30

    first_hash = SHA1(server_salt + randomized_grid)

    return SHA1(client_salt + first_hash)

Implementations

• Rust (wow_srp)
• C++ (Ember)

Verification values

• regression

Remap PIN Grid

This function converts the PIN grid seed into a remapped array.

• pin_grid_seed is sent by the server in CMD_AUTH_LOGON_CHALLENGE_Server.
• % is the modulus operator.

function remap_pin_grid
    argument pin_grid_seed: u32
    returns array of 10 bytes

    grid = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    remapped_grid = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

    # Go backwards
    # Start on 10 and do not go to 0
    for i in 10..0:
        # Iteration count, could also use enumerate()
        remapped_index = 10 - i

        remainder = pin_grid_seed % i
        pin_grid_seed = pin_grid_seed / i
        remapped_grid[remapped_index] = grid[remainder]

        copy_size = i - remainder - 1

        for j in 0..copy_size:
            grid[remainder + j] = grid[remainder + j + 1]

    return remapped_grid

Implementations

• Rust (wow_srp)
• C++ (Ember)

Verification values

• remap_regression

Randomize Grid

This function converts the PIN grid seed into a remapped array.

• bytes is the PIN as a byte array.
• remapped_pin_grid is the remapped PIN grid created by remap_pin_grid.

function randomize_grid
    argument bytes: array of bytes
    argument remapped_pin_grid: array of 10 bytes
    # Can return a new array if modifying bytes in place is not possible
    
    for i, byte in enumerate(bytes):
        remapped_value = index of byte value from remapped_pin_grid
        bytes[i] = remapped_value

Implementations

• Rust (wow_srp)
• C++ (Ember)

Verification values

• convert_regression

Background

The server sends a checksum salt in CMD_AUTH_LOGON_CHALLENGE_Server in the field just after the SRP6 salt. The client sends the final hash in CMD_AUTH_LOGON_PROOF_Client in the field just after the client proof.

The client does not require the server to make this calculation like it does for the SRP6 algorithm and malicious clients can just fake the proof, so there’s no real security benefits to implementing this check.

The integrity check is different for login and reconnection. The integrity check is not platform specific, but the specific files and contents of those files are platform and version specific.

This guide is specifically for 1.12, although it will probably work on other versions as well.

Implementation details for login

The implementation is a HMAC-SHA1 of game files together with the server provided checksum salt, and then a SHA1 of the resulting HMAC along with the client public key. The implementation is not different for Mac/Windows, it only differs in the files that are checked.

Generic

This describes a function that can be used for both Windows and Mac without any modifications. The algorithm is the same as the platform specific versions, but all the checked files are just concatenated into a single slice to make the function generic.

• checksum_salt is sent by the server in CMD_AUTH_LOGON_CHALLENGE_Server in the field just after the SRP6 salt.
• all_files is all platform specific files concatenated together. See the platform specific versions for which specific files.
• client_public_key is the client public key provided by the client.
• + is array concatenation.

Calculating the integrity hash in pseudo code would look like:

function integrity_check_generic
    argument all_files: array of an arbitrary amount of bytes
    argument checksum_salt: array of 16 bytes
    argument client_public_key: array of 32 bytes
    returns array of 20 bytes

    checksum_hmac = HmacSha1(checksum_salt)
    checksum_hmac.update(all_files)

    checksum = checksum_hmac.finalize()

    return SHA1(client_public_key + checksum)

Implementations

• Rust (wow_srp)
• C++ (Ember)

Verification values

• generic_regression

Windows

The windows integrity calculation uses the generic version, but it specifically enumerates the files required for Windows.

• wow_exe, the bytes of the WoW.exe file.
• fmod_dll, the bytes of the fmod.dll file.
• ijl15_dll, the bytes of the ijl15.dll file.
• dbghelp_dll, the bytes of the dbghelp.dll file.
• unicows_dll, the bytes of the unicows.dll file.
• checksum_salt is sent by the server in CMD_AUTH_LOGON_CHALLENGE_Server in the field just after the SRP6 salt.
• client_public_key is the client public key provided by the client.
• + is array concatenation.

Calculating the integrity hash in pseudo code would look like:

function integrity_check_windows
    argument wow_exe: array of an arbitrary amount of bytes
    argument fmod_dll: array of an arbitrary amount of bytes
    argument ijl15_dll: array of an arbitrary amount of bytes
    argument dbghelp_dll: array of an arbitrary amount of bytes
    argument unicows_dll: array of an arbitrary amount of bytes
    argument checksum_salt: array of 16 bytes
    argument client_public_key: array of 32 bytes
    returns array of 20 bytes

    all_files = wow_exe + fmod_dll + ijl15_dll + dbghelp_dll + unicows_dll

    return integrity_check_generic(all_files, checksum_salt, client_public_key)

Verification values

• windows_regression

Mac

The windows integrity calculation uses the generic version, but it specifically enumerates the files required for Windows.

• world_of_warcraft, the bytes of the MacOS/World of Warcraft file.
• info_plist, the bytes of the Info.plist file.
• objects_xib, the bytes of the Resources/Main.nib/objects.xib file.
• wow_icns, the bytes of the Resources/wow.icns file.
• pkg_info, the bytes of the PkgInfo file.
• checksum_salt is sent by the server CMD_AUTH_LOGON_CHALLENGE_Server in the field just after the SRP6 salt.
• client_public_key is the client public key provided by the client.
• + is array concatenation.

Calculating the integrity hash in pseudo code would look like:

function integrity_check_windows
    argument world_of_warcraft: array of an arbitrary amount of bytes
    argument info_plist: array of an arbitrary amount of bytes
    argument objects_xib: array of an arbitrary amount of bytes
    argument wow_icns: array of an arbitrary amount of bytes
    argument pkg_info: array of an arbitrary amount of bytes
    argument checksum_salt: array of 16 bytes
    argument client_public_key: array of 32 bytes
    returns array of 20 bytes

    all_files = world_of_warcraft + info_plist + objects_xib + ow_icns + pkg_info

    return integrity_check_generic(all_files, checksum_salt, client_public_key)

Verification values

• mac_regression

Implementation details for reconnect

The reconnection integrity check does away with any local files and simply gets the SHA1 of the provided salt along with a zero buffer. This is likely to save on resources since it would be very unlikely for the files to change in between login and reconnecting.

• checksum_salt is sent by the server CMD_AUTH_RECONNECT_CHALLENGE_Server in the field just after the SRP6 salt.
• + is array concatenation.

Calculating the reconnect integrity hash in pseudo code would look like:

function integrity_check_reconnect
    argument checksum_salt: array of an arbitrary amount of bytes

    # Array of 20 bytes, filled with zero
    all_zero = [0; 20]

    return SHA1(checksum_salt + all_zero)

Verification values

• reconnect_regression

Implementations

• Rust (wow_srp)
• C++ (Ember)

The goal of this article is to be an approachable, complete guide to implementing the protocol specifically for WoW 1.12 without requiring external references.

The article starts out by giving a high level overview of the protocol and the specifics of the WoW implementation before giving a function-by-function implementation guide, including files for verification and examples of implementation in Rust, C++ and Elixir.

Important terms have been highlighted with bold. The exact definitions of these will come later in the article.

This article will only cover the SRP6 protocol, not the network aspects of authenticating with a client.

This is not intended to be a guide for production usage. I have no cryptographic experience and essentially stumbled upon the solutions by accident. SRP6 is also not very widely used, possibly for a reason. Use this only for interacting with legacy World of Warcraft game clients.

Ensure that you actually need to implement this from scratch

There is little reason to implement this from scratch if you can just use an existing library for it.

These are the libraries that I know of, if you want yours added to the list send me an email. There are more implementations linked later in the article, but they are part of applications and can’t be used as libraries.

SRP6 Overview

SRP6 is a protocol for proving that a client and server both know the same specific password without having to send it over the network. It does this via various mathematical tricks, none of which are important to us.

When a new account is added, the server generates a random salt value and calculates a password verifier before saving the username, salt and password verifier to the database.

When authenticating, the protocol works in 5 different stages:

1. The client sends their username to the server.
2. The server retrieves the password verifier and salt from the database, then it randomly generates a private key which it uses to calculate a public key. It then sends the public key and salt to the client, as well as a large safe prime and a generator.
3. The client generates a private key and calculates a public key. Then it calculates a session key and client proof. It then sends both the public key and client proof to the server.
4. The server calculates a session key, then calculates the client proof on its own and compares it to the one the client sent. If they are identical the client and server have used the same password for their calculations. The server then sends a server proof to the client to prove that it also knows the correct password.
5. If the client gets an identical server proof it is now authenticated and will send the “Send Realmlist” packet to ask the server to send a realmlist.
6. If the client loses connection, it can reconnect by proving that it knows the original session key. More on this in the Reconnecting section.

The above description can also be seen as a sequence diagram in figure 1.

There are some important conceptual points to remember:

1. The private keys are never sent over the network. Only the client will know what the client private key is, and only the server will know what the server private key is. Both values are chosen completely at random and are not identical.
2. The public keys are sent over the network and are not identical.
3. The session keys are calculated by both the client and the server based on different variables. These keys are identical and the client proof and server proof prove to the other part that they both have the same session key without saying what the key is.
4. The client proof and server proof are calculated using the public information and their respective session keys. This means that the client calculates a client proof, then the server calculates a client proof using the same algorithm and if the client proofs match the session keys used are identical. The same happens for the server proofs.

Reconnecting and packet header encryption are described in their own sections.

Important Knowledge Before Starting

Before we dive into the implementation itself, there are a few things you should know that would ease your implementation.

Integers

You will need to convert an array of bytes to a number, this is often called a BigInt, BigInteger or arbitrary size integer. You might need a third party library for this although some languages do have standard library support for this.

The integers should be signed and positive.

Modulo vs Remainder

It’s important that your BigInteger implementation uses modulo rather than the remainder for mod_pow. With remainder, (-2)^3 % 9 = -8 while with modulo (-2)^3 % 9 = 1. Test your BigInteger implementation and if it uses remainder, add the large safe prime to the result to get the correct result. For example:

large_safe_prime = 9
a = -2
b = 3
result = a.mod_pow(b, large_safe_prime)

# if result == 1 you don't need to do anything else

# if result == -8 you need to create a wrapper around your mod_pow like so:
def real_mod_pow(a, b, large_safe_prime):
    c = a.mod_pow(b, large_safe_prime)
    if c < 0:
        c += large_safe_prime
    return c

result = real_mod_pow(a, b, large_safe_prime)
# result is now 1

Convertion of hexadecimal strings to byte arrays

When using the provided examples you will need to convert a hexadecimal string to arrays of bytes. It’s important to understand the difference between a byte array of a hexadecimal integer, and a byte array of a string.

Hexadecimal strings can be thought of as containing a byte every 2 characters. So the string FF would be an array with a single element containing the value 255 (0xFF), while the string FFEE would be an array with two elements containg the value 255 (0xFF) and the value 238 (0xEE).

A byte array of a string are the literal values that represent the characters in the string, while a byte of array of an integer are the individual components of the integer. So the byte array of the hexadecimal string FF would contain two elements with the value 70 (0x46) and the value 70, since these are the ASCII/UTF-8 values of the F character.

Consider two the functions HexToBytes and StringToBytes. HexToBytes converts a hexadecimal string to an array of the byte values while StringToBytes converts any string to an array of the character values.

If you read one of the examples and get the hexadecimal string ABCDEF you can test whether you have a byte array of the string or the byte values by checking the length of the returned by array.

The array returned by HexToBytes for the string ABCDEF would contain 3 elements ([ 0xAB, 0xCD, 0xEF ]), while the array returned by StringToBytes for the string ABCDEF would contain 6 elements ([ 0x41, 0x42, 0x43, 0x44, 0x45, 0x46 ]).

Endianness

All operations are performed on little endian arrays. This means that if your arbitrary size integer has generic as_bytes(), to_bytes() or from_bytes() functions, you will need to investigate which endianness it expects and outputs.

To visualize endianness consider the hexadecimal (base/radix 16) number 0xABCD (43981 in decimal (base/radix 10)).

Most hexadecimal string parsers would consider the number to be in big endian representation with the most significant digit A to the far left representing the digit that would affect the number most if changed, in the same way that 1 is the most significant digit in 100 (one hundred).

If you convert the number to big endian bytes the most significant byte, AB, is in the first position and the rest follow along. In little endian bytes the least significant byte, CD, is the in the first position followed by the second least significant byte, AB in this case.

See the psuedo code below to build a mental model of endianness.

BigInt value = 0xABCD
byte[] big_endian = { 0xAB, 0xCD }
byte[] little_endian = { 0xCD, 0xAB }

To test your BigInt implementation, try to load up the hexadecimal number ABCD and get it as bytes. The Rust num_bigint library has both to_bytes_le() and to_bytes_be() so there’s no confusion. Make a note of whether the bytes you get are little endian or big endian.

Rust Playground

use num_bigint; // 0.4.0
use num_traits::Num;

fn main() {
    let number = num_bigint::BigInt::from_str_radix("ABCD", 16).unwrap();
    dbg!(&number.to_bytes_be()); // Outputs [ 171, 205 ] which is [ 0xAB, 0xCD ] in hex
    dbg!(&number.to_bytes_le()); // Outputs [ 205, 171 ] which is [ 0xCD, 0xAB ] in hex
}

Remember that there’s a different between the string representation and the literal bytes representation. A hexadecimal string is just a human readable representation of the value, the value of the characters that make up the string is not the same.

Padding

All operations are performed on padded arrays, the sizes for different types can be seen below. Do not worry about understanding why the different sizes are chosen, most are simply the result of the client not being able to accept higher values or having fixed sized fields.

Hashing

All operations use SHA-1 which produces an output of 20 bytes.

To test that your SHA-1 implementation works correctly, ensure that hashing the string test leads to the output of a94a8fe5ccb19ba61c4c0873d391e987982fbbd3, and that hashing the bytes 0x53 0x51 leads to 0c3d7a19ac7c627290bf031ec3df76277b0f7f75.

Constants

The large safe prime should always be 0x894B645E89E1535BBDAD5B8B290650530801B18EBFBF5E8FAB3C82872A3E9BB7 (big endian string). The large safe prime can be expressed as a little endian Rust array like

pub const LARGE_SAFE_PRIME_LITTLE_ENDIAN: [u8; 32] = [
    0xb7, 0x9b, 0x3e, 0x2a, 0x87, 0x82, 0x3c, 0xab,
    0x8f, 0x5e, 0xbf, 0xbf, 0x8e, 0xb1, 0x01, 0x08,
    0x53, 0x50, 0x06, 0x29, 0x8b, 0x5b, 0xad, 0xbd,
    0x5b, 0x53, 0xe1, 0x89, 0x5e, 0x64, 0x4b, 0x89
];

or as a big endian Rust array like

pub const LARGE_SAFE_PRIME_BIG_ENDIAN: [u8; 32] = [
    0x89, 0x4b, 0x64, 0x5e, 0x89, 0xe1, 0x53, 0x5b,
    0xbd, 0xad, 0x5b, 0x8b, 0x29, 0x06, 0x50, 0x53,
    0x08, 0x01, 0xb1, 0x8e, 0xbf, 0xbf, 0x5e, 0x8f,
    0xab, 0x3c, 0x82, 0x87, 0x2a, 0x3e, 0x9b, 0xb7,
];

The generator should always be 7.

The k value should always be 3.

The XOR Hash with these values will always be 0xA7C27B6C96CA6F505A7C98031173AC383AB07BDD (big endian string). The XOR Hash can be expressed as a little endian Rust array like

const PRECALCULATED_XOR_HASH: [u8; 20] = [
    0xdd, 0x7b, 0xb0, 0x3a, 0x38, 0xac, 0x73, 0x11, 0x3, 0x98,
    0x7c, 0x5a, 0x50, 0x6f, 0xca, 0x96, 0x6c, 0x7b, 0xc2, 0xa7,
];

Aliases

Previously terms like client public key and large safe prime have been used instead of the single letters A and N which are used in RFC2945.

The one letter abbreviations are in my opinion difficult to remember and internalize unless you already know what they mean beforehand. The long forms will therefore be used, and the table below will serve as a translation between the long and short forms. Not all terms have a long term, since some terms only exist as intermediate results.

Implementation Details

This section describes how to implement the algorithm on a function-by-function basis. A completely functional program will only be possible once everything except for the Reconnect proof has been implemented. Test against the provided text files for every function to ensure that no mistakes occur.

The wow_srp Rust crate implements the full algorithm, with examples for both client and server located in the examples/ directory. WowSrp has a C# version. Ember has a C++ version. Shadowburn has an Elixir version. wow_srp6 is a Python version.

The various Mangos forks and derivatives also have SRP6 implementations but these are of very low quality and some will produce incorrect results in as often as 1/1000 cases.

Password Verifier

The password verifier, v, is calculated as v = g^x % N, where:

• g is the static generator equal to 7 defined in Constants.

• x is discussed below.

• % is the modulo operator.

• N is the static large safe prime defined in Constants.

Calculating the password verifier in pseudo code would look like

function calculate_password_verifier
    argument username: string
    argument password: string
    argument salt: little endian array of 32 bytes
    returns little endian array of 32 bytes

    x = calculate_x(username, password, salt)

    // modpow is a power of and modulo operation in the same function
    return g.modpow(x, large_safe_prime)

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember). Slightly confusing way of doing it. Callsite is here, then here and then here.
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_v_values.txt contains the columns:

Calculating x

The x value is calculated as x = SHA1( s | SHA1( U | : | p )), where:

• U is the uppercased username of the user. See this section for notes.

• p is the uppercased password of the user. See this section for notes.

• s is the randomly generated salt value for the user.

• | is concatenating the values.

• SHA1 is SHA-1 hashing the values.

• : is the literal character :.

Calculating x in pseudo code would look like

function calculate_x
    argument username: string
    argument password: string
    argument salt: little endian array of 32 bytes
    returns little endian array of 20 bytes

    interim = SHA1( username + ":" + password )

    // Array concatenation
    return SHA1( salt + interim )

Implementations

• Rust (wow_srp)
• C# (WowSrp)
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_x_salt_values.txt assumes a static username of USERNAME123 and a static password of PASSWORD123. It contains the columns:

• calculate_x_values.txt assumes a static salt of 0xCAC94AF32D817BA64B13F18FDEDEF92AD4ED7EF7AB0E19E9F2AE13C828AEAF57 (big endian). It contains the columns:

Server public key

The server public key, B, is calculated as B = (k * v + (g^b % N)) % N, where:

• k is a k value statically defined in Constants.

• v is the password verifier for the user.

• g is a generator statically defined in Constants.

• b is the server private key.

• % is the modulo operator.

• N is a large safe prime statically defined in Constants.

Calculating the server public key in pseudo code would look like:

function calculate_server_public_key
    argument password_verifier: BigInteger type
    argument server_private_key: BigInteger type
    returns little endian array of 32 bytes

    // modpow is a power of and modulo operation in the same function
    interim = k_value * password_verifier 
        + generator.modpow(server_private_key, large_safe_prime)
    return interim % large_safe_prime

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_B_values.txt contains the columns:

Session key

The session key, K, is calculated differently depending on whether it is the client or server doing the calculation because they only have access to their own private keys.

Both ways calculate an interim S key value that is finally interleaved in order to get the common session key.

For completeness, both the server and client session key, K, is calculated as K = interleaved(S), where interleaved is a function described below. The calculation of the client and server S keys are below.

Client S Key

The client S Key, S, is calculated as S = (B - (k * (g^x % N)))^(a + u * x) % N, where:

• g is a generator statically defined in Constants.

• % is the modulo operator.

• N is a large safe prime statically defined in Constants.

• k is a k value statically defined in Constants.

• a is the client private key.

• B is the server public key.

• x is an interim value described under the Password Verifier section.

• u is an interim value described below.

Calculating the client S key in pseudo code would look like:

function calculate_client_S_key
    argument client_private_key: little endian array of 32 bytes
    argument server_public_key: little endian array of 32 bytes
    argument x: little endian array of 32 bytes
    argument u: little endian array of 32 bytes
    returns little endian array of 32 bytes

    S = (server_public_key - (k * g.modpow(x, large_safe_prime))).modpow(client_private_key + u * x, large_safe_prime)
    return S

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Python (wow_srp6)

Verification values

If you’re getting an error on the 6th line of this file, your BigInteger implementation is likely using remainder instead of modulo.

• calculate_client_S_values.txt expects a static generator and large safe prime from Constants, and contains the columns:

Server S Key

The server S key, S, is calculated as S = (A * (v^u % N))^b % N, where:

• A is the client public key.

• v is the password verifier for the user.

• % is the modulo operator.

• N is a large safe prime statically defined in Constants.

• b is the server private key.

• u is an interim value described below.

Calculating the server S key in pseudo code would look like:

function calculate_server_S_key
    argument client_public_key: BigInteger type
    argument password_verifier: BigInteger type
    argument u: BigInteger type
    argument server_private_key: BigInteger type
    returns little endian array of 32 bytes

    S = (client_public_key * password_verifier.modpow(u, large_safe_prime))
                .modpow(server_private_key, large_safe_prime)

    return S

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_S_values.txt expects a static generator and large safe prime from Constants, and contains the columns:

u

The u value is calculated as u = SHA1( A | B ), where:

• A is the client public key.

• B is the server public key.

• SHA1 is SHA-1 hashing.

• | is array concatenation.

Calculating the server S key in pseudo code would look like:

function calculate_u
    argument client_public_key: little endian array of 32 bytes
    argument server_public_key: little endian array of 32 bytes
    returns little endian array of 20 bytes
    
    return SHA1( A + B )

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn) where it’s called the scrambler.
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_u_values.txt contains the columns:

Interleaved

The interleaved function converts the S key to the session key. It is calculated as K = SHA_Interleave(S), where:

• K is the session key.

• S is the S key.

• SHA_Interleave() is a function described below:

If the least significant byte is 0, the two least significant bytes are removed. If the next least significant byte is also 0, the two new least significant bytes are again removed. This process continues until the least significant byte is not equal to 0. The even elements of the split S key are then hashed, as are the odd elements. The two hashes are then zipped together, with the even elements in the first position.

The SHA_Interleave() function in pseudo code would look like:

function split_s_key
    argument s_key: little endian array of 32 bytes
    returns little endian array of 32 bytes or fewer

    // While the _least_ significant byte is 0,
    // remove the 2 least significant bytes.
    // Always keep the length even without
    // trailing zero elements
    while s_key[0] == 0
        // In the pseudo code the s_key variable is modified in place
        // so the first iteration `s_key` has length 32, in the second
        // it has length 30, and so on.
        s_key = s_key[2:]

    return s_key
        

function SHA_Interleave
    argument s_key: little endian array of 32 bytes
    returns array of 40 bytes

    split_s_key = split_s_key(s_key)

    E = dynamic vector of bytes
    // Only add the even elements
    for i in split_s_key.even_elements
        E.push(i)
    G = SHA1(E)
        
    F = dynamic vector of bytes
    for i in split_s_key.odd_elements
        F.push(i)
    H = SHA1(F) 

    session_key = little endian array of 40 bytes
    for i = 0, while i < 20, i += 2
        session_key[i * 2] = G[i]
        session_key[(i * 2) + 1] = H[i]

    return session_key

Implementations

• Rust (wow_srp) (split_s_key)
• Rust (wow_srp)
• C# (WowSrp (SplitSKey)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_interleaved_values.txt contains the columns:

• calculate_split_s_key.txt contains the columns:

Server Session Key

The server session key combines all the previous functions:

function calculate_server_session_key:
    argument client_public_key: array of 32 bytes
    argument server_public_key: array of 32 bytes
    argument password_verifier: array of 32 bytes
    argument server_private_key: array of 32 bytes
    returns array of 40 bytes

    u = calculate_u(client_public_key, server_public_key)
    S = calculate_S(client_public_key, password_verifier, u, server_private_key)

    return calculate_interleaved(S)
}

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

You will need to calculate the server public key using the supplied password verifier and server private key in order to test this.

• calculate_server_session_key.txt contains the columns:

Client Session Key

The client session key combines all the previous functions:

function calculate_client_session_key:
    argument username: string
    argument password: string
    argument server_public_key: array of 32 bytes
    argument client_private_key: array of 32 bytes
    argument generator: unsigned integer
    argument large_safe_prime: array of 32 bytes
    argument client_public_key: array of 32 bytes
    argument salt: array of 32 bytes
    returns array of 40 bytes

    x = calculate_x(username, password, salt)

    u = calculate_u(client_public_key, server_public_key)
    S = calculate_client_S(
        server_public_key,
        x,
        client_private_key,
        u,
        generator,
        large_safe_prime,
    )

    return calculate_interleaved(S)
}

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Python (wow_srp6)

Verification values

• calculate_client_session_key.txt contains the columns:

The usernames and passwords will need to be uppercased before this test will pass.

Server proof

The server proof, M2 or sometimes just M, is calculated as M2 = SHA1(A | M1 | K), where:

• A is the client public key.

• M1 is the client proof. Remember that M1 must be calculated and verified on the server before this calculation takes place.

• K is the session key.

• | is concatenation.

Calculating the server proof in pseudo code would look like:

function calculate_server_proof
    argument client_public_key: little endian array of 32 bytes
    argument client_proof: little endian array of 20 bytes
    argument session_key: little endian array of 40 bytes
    returns little endian array of 20 bytes (SHA1 hash)

    // Array concatenation
    return SHA1(client_public_key + client_proof + session_key)

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember) calls into here.
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_M2_values.txt contains the columns:

Client proof

The client proof, M1 or sometimes just M, is calculated as M1 = SHA1( X | SHA1(U) | s | A | B | K ), where:

• X is the XOR Hash, described below. It requires the large safe prime and the generator. Can be precalculated if both are known.

• SHA1(U) is a SHA-1 hash of the uppercased username.

• s is the salt.

• A is the client public key.

• B is the server public key.

• K is the session key.

Calculating the client proof in pseudo code would look like:

function calculate_client_proof
    argument xor_hash: little endian array of 20 bytes
    argument username: string
    argument session_key: little endian array of 40 bytes
    argument client_public_key: little endian array of 32 bytes
    argument server_public_key: little endian array of 32 bytes
    argument salt: little endian array of 32 bytes

    hashed_username = SHA1( username )
    
    // | is array concatenation
    return SHA1( xor_hash 
                | hashed_username 
                | salt 
                | client_public_key 
                | server_public_key 
                | session_key )

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_M1_values.txt contains the columns:

XOR Hash

This value can be precalculated on the server and you can avoid the calculation. See the verification values for the value.

The xor_hash is calculated as SHA1(N) XOR SHA1(g), where:

• SHA1(g) is a SHA-1 hash of the generator statically defined in Constants on the server and variable on the client.

• SHA1(N) is a SHA-1 hash of the large safe prime statically defined in Constants on the server and variable on the client.

• XOR uses the XOR operator on every element of the two arrays.

Calculating the XOR Hash in pseudo code would look like:

function calculate_xor_hash
    argument large_safe_prime: little endian array of 32 bytes
    argument generator: byte value
    returns little endian array of 20 bytes (SHA-1 hash)

    hashed_generator = SHA1( generator )
    hashed_large_safe_prime = SHA1( large_safe_prime )

    result is a 20 byte array
    for index in hashed_generator
        result[index] = hashed_generator[index] ^ hashed_large_safe_prime[index]
    end for

    return result

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)

Verification values

• calculate_xor_hash.txt contains the columns:

Client public key

Generating the client public key is not necessary if you’re only writing the server part.

The client public key, A, is calculated as A = g^a % N, where:

• g is a generator. Clients do not get to choose the generator, so they can not assume a static value is used.

• a is the client private key.

• % is the modulo operator.

• N is a large safe prime. Clients do not get to choose the large safe prime, so they can not assume a static value is used.

Calculating the client public key in pseudo code would look like:

function calculate_client_public_key
    argument client_private_key: little endian array of 32 bytes
    argument generator: 1 byte integer
    argument large_safe_prime: little endian array of 32 bytes
    returns little endian array of 32 bytes

    // modpow is a power of and modulo operation in the same function
    return generator.modpow(client_private_key, large_safe_prime)

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Python (wow_srp6)

Verification values

• calculate_A_values.txt expects a static generator and large safe prime as defined under Constants. It contains the columns:

Reconnecting

If a client loses connection with the logon server after getting a session key but before connecting to a realm, the client will attempt bypass the creation of a new session key by proving to the client that it knows the old session key.

When reconnecting, the protocol works in 6 steps:

1. The client sends their username to the server.
2. The server checks for an existing session with the username and creates randomized server data that it sends to the client.
3. The client generates randomized client data and uses the server data along with the username and session key to create a reconnect proof. It then sends the client data and reconnect proof to the server.
4. The server calculates their own reconnect proof from the username, server data, client data, and session key to see if it matches the client reconnect proof.
5. The client is now authenticated again and will send the ‘Send Realmlist’ packet to as the server to send a realmlist.

The above description can also be seen as a sequence diagram in figure 2.

The only function needed for the above is calculating the reconnect proof and generating random 16 byte values.

Reconnect proof

The reconnect proof is not part of SRP6 and does not have a short term. It is calculated the same for the client and server. The reconnect proof is calculated as SHA1( username | client_data | server_data | session_key ), where:

• username is the username of the user attempting to reconnect.

• client_data is the randomized data sent by the client.

• server_data is the randomized data sent by the server.

• session_key is the session key from a previous successful authentication.

• | is array concatenation. Strings are converted to UTF-8 bytes.

Calculating the client public key in pseudo code would look like:

function calculate_reconnect_proof
    argument username: string
    argument client_data: little endian array of 16 bytes
    argument server_data: little endian array of 16 bytes
    argument session_key: little endian array of 40 bytes
    returns little endian array of 20 bytes

    return SHA1(username + client_data + server_data + session_key)

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_reconnection_values.txt contains the columns:

Vanilla World Message Header Encryption

World Packets encrypt their header using the session key. None of the Login Packets require encryption, but this section is included because it can be tedious to implement and is necessary for getting to the character screen.

The sending party encrypts the header and the receiving party decrypts the header. Client and server headers have different length, but this does not matter since the algorithm works on any amount of bytes.

The “encryption” is not real encryption, since it’s very easily breakable and can leak the session key which is used for reconnection.

To be explicit, if you’re writing a server you will only ever decrypt headers received from the client and encrypt headers sent to the client.

Figure 3 shows both encryption and decryption visually. Individual images can be found at step 1, step 2, step 3, step 4 and step 5.

Encryption

Encryption works by XORing the unencrypted value with a byte of the session key and adding the previous encrypted value. The index into the session key is then incremented. This is done for every element of the array to be encrypted.

The encryption is calculated as E = (x ^ S) + L where:

• E is the encrypted value, what is sent over the wire.

• x is the unencrypted value, a byte of the opcode or size.

• S is a byte of the session key, incrementing after every encryption.

• L is the last encrypted value. This is E from the previous iteration.

In pseudo code this would look like:

function encrypt
    argument data: little endian array of length AL
    returns little endian array of length AL
    
    static int index = 0 // Static variables keep their values between function calls
    static int last_value = 0 // Last value starts at zero
    // The session key exists somewhere else as `session_key`

    return_array = {} // Encrypted values

    for unencrypted in data {
        encrypted = (unencrypted ^ session_key[index]) + last_value

        index = (index + 1) % session_key.length // Use the session key as a circular buffer

        return_array.append(encrypted)
        last_value = encrypted
    }

    return return_array

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)

Verification values

• calculate_encrypt_values.txt contains the columns:

World Packet headers contain a 2 byte big endian size field and either a 4 (SMSG) or 6 (CMSG) byte opcode field. The following files can be used to verify utility methods that return a size and opcode. The data should be decrypted first using the side in the file name, then encrypted again in order to verify that the write also matches.

session_key = [
    0x2E, 0xFE, 0xE7, 0xB0, 0xC1, 0x77, 0xEB, 0xBD, 0xFF, 0x66, 0x76, 0xC5, 0x6E, 0xFC, 0x23,
    0x39, 0xBE, 0x9C, 0xAD, 0x14, 0xBF, 0x8B, 0x54, 0xBB, 0x5A, 0x86, 0xFB, 0xF8, 0x1F, 0x6D,
    0x42, 0x4A, 0xA2, 0x3C, 0xC9, 0xA3, 0x14, 0x9F, 0xB1, 0x75,
];
username = "A";
client_seed = 0xDEADBEEF;
server_seed = 0xDEADBEEF;

• vanilla_server contains the columns:

• vanilla_client contains the columns:

Decryption

Decryption does the opposite of encryption. So first the old encrypted value is subtracted from the encrypted value, before it is XORed with the session key.

The decryption is calculated as x = (E - L) ^ S where:

• x is the unencrypted value, a byte of the opcode or size.

• E is the encrypted value, what is sent over the wire.

• L is the last encrypted value. This is E from the previous iteration.

• S is a byte of the session key, incrementing after every encryption.

In pseudo code this would look like:

function decrypt
    argument data: little endian array of length AL
    returns little endian array of length AL
    
    static int index = 0 // Static variables keep their values between function calls
    static int last_value = 0 // Last value starts at zero
    // The session key exists somewhere else as `session_key`

    return_array = {} // Unencrypted values

    for encrypted in data {
        unencrypted = (encrypted - last_value) ^ session_key[index]

        index = (index + 1) % session_key.length // Use the session key as a circular buffer

        last_value = encrypted
        return_array.append(unencrypted)
    }

    return return_array

Implementations

• Rust (wow_srp)
• C# (WowSrp
• C++ (Ember)
• Elixir (Shadowburn)
• Python (wow_srp6)

Verification values

• calculate_decrypt_values.txt contains the columns:

TBC World Message Header Encryption

Has the same implementation for encryption/decryption as Vanilla, but it performs an HMAC-SHA1 on the session key along with a seed and iterates over that instead. Verification values are provided for

Remember that the key for TBC is only 20 bytes, while it’s 40 for Vanilla so you will probably need different functions for each.

Key Generation

• HMAC-SHA1 is the HMAC-SHA1 function.

In pseudo code the generation looks like:

function create_tbc_key:
    argument session_key: array of 40 bytes
    returns array of 20 bytes

    S = [0x38, 0xA7, 0x83, 0x15, 0xF8, 0x92, 0x25, 0x30, 0x71, 0x98, 0x67, 0xB1, 0x8C, 0x4, 0xE2,
        0xAA]
    hmac = HMAC-SHA1(S)
    hmac.update(session_key)
    
    return hmac.finalize()

Implementations

• Rust (wow_srp)
• C# (WowSrp)

Verification values

• create_tbc_key.txt contains the columns:

Encryption/Decryption

This is identical to the Vanilla version except the key is only 20 bytes instead of 40 bytes.

Encrypt this and verify that it matches Expected Encrypt, then decrypt it and verify that it matches the original Data.

Verification values

• calculate_tbc_encrypt_values.txt contains the columns:

World Packet headers contain a 2 byte big endian size field and either a 4 (SMSG) or 6 (CMSG) byte opcode field. The following files can be used to verify utility methods that return a size and opcode. The data should be decrypted first using the side in the file name, then encrypted again in order to verify that the write also matches.

session_key = [
    0x2E, 0xFE, 0xE7, 0xB0, 0xC1, 0x77, 0xEB, 0xBD, 0xFF, 0x66, 0x76, 0xC5, 0x6E, 0xFC, 0x23,
    0x39, 0xBE, 0x9C, 0xAD, 0x14, 0xBF, 0x8B, 0x54, 0xBB, 0x5A, 0x86, 0xFB, 0xF8, 0x1F, 0x6D,
    0x42, 0x4A, 0xA2, 0x3C, 0xC9, 0xA3, 0x14, 0x9F, 0xB1, 0x75,
];
username = "A";
client_seed = 0xDEADBEEF;
server_seed = 0xDEADBEEF;

• tbc_server contains the columns:

• tbc_client contains the columns:

Wrath World Message Header Encryption

Wrath creates an intermediate key by running a fixed key and the session key through HMAC-SHA1, and then uses this to seed an ARC4 cipher that encrypts the header.

The key generation function is essentially the same as the TBC generation, except TBC uses the same hardcoded seed for both client and server, while Wrath has separate keys.

The seed keys are:

// Used for Client (Encryption) to Server (Decryption)
const S: [u8; 16] = [
    0xC2, 0xB3, 0x72, 0x3C, 0xC6, 0xAE, 0xD9, 0xB5, 0x34, 0x3C, 0x53, 0xEE, 0x2F, 0x43, 0x67, 0xCE,
];

// Used for Server (Encryption) to Client (Decryption) messages
const R: [u8; 16] = [
    0xCC, 0x98, 0xAE, 0x04, 0xE8, 0x97, 0xEA, 0xCA, 0x12, 0xDD, 0xC0, 0x93, 0x42, 0x91, 0x53, 0x57,
];

Key Generation

• HMAC-SHA1 is the HMAC-SHA1 function.

In pseudo code the generation looks like:

function create_wrath_key:
    argument session_key: array of 40 bytes
    argument key: array of 16 bytes
    returns array of 20 bytes

    hmac = HMAC-SHA1(key)
    hmac.update(session_key)
    
    return hmac.finalize()

Implementations

• Rust (wow_srp)
• C# (WowSrp)
• Go (go-wow-srp6)

Verification values

• create_wrath_hmac_key.txt contains the columns:

Encryption/Decryption

Initialize a RC4A with the previously calculated key. Then apply the keystream to 1024 bytes (since this is the drop1024 variant).

After this apply the keystream to the header to be encrypted.

function create_crypto:
    argument session_key: array of 40 bytes
    argument key: array of 16 bytes
    returns RC4A in progress

    S = create_wrath_key(session_key, key)

    rc4 = RC4(S)

    rc4.apply_keystream to 1024 0 bytes

    retrurn rc4


function encrypt/decrypt:
    argument rc4: RC4A in progress 
    argument data: array of bytes

    # Modifies data in place
    rc4.apply(data)

Implementations

• Rust (wow_srp)
• C# (WowSrp)
• Go (go-wow-srp6)

Verification values

These verification values use the above keys. Ensure that you’re using the correct one for the correct direction and side.

• calculate_wrath_encrypt_values.txt contains the columns:

World Message headers contain a 2 byte big endian size field and either a 4/5 (SMSG) or 6 (CMSG) byte opcode field. If, after decrypting, the top level bit is set for SMSG (that is (top_byte & 0x80) != 0), the size field is 3 bytes instead of 2. This must also be set when sending messages larger than 0x7fff. The following files can be used to verify utility methods that return a size and opcode. The data should be decrypted first using the side in the file name, then encrypted again in order to verify that the write also matches.

session_key = [
    0x2E, 0xFE, 0xE7, 0xB0, 0xC1, 0x77, 0xEB, 0xBD, 0xFF, 0x66, 0x76, 0xC5, 0x6E, 0xFC, 0x23,
    0x39, 0xBE, 0x9C, 0xAD, 0x14, 0xBF, 0x8B, 0x54, 0xBB, 0x5A, 0x86, 0xFB, 0xF8, 0x1F, 0x6D,
    0x42, 0x4A, 0xA2, 0x3C, 0xC9, 0xA3, 0x14, 0x9F, 0xB1, 0x75,
];
username = "A";
client_seed = 0xDEADBEEF;
server_seed = 0xDEADBEEF;

• wrath_server contains the columns:

• wrath_client contains the columns:

World Server Proof

After receiving the CMSG_AUTH_SESSION ^wiki message the server will have to verify that the client does indeed know the correct session key. This is done by having both the server and client use 32 bit (not byte) values as seeds in a hash with the session key.

The world server proof works for all versions from Vanilla through to Wrath.

The proof is calculated as SHA1( username | 0 | client_seed | server_seed | session_key ), where:

• username is the username of the user attempting to connect.

• 0 is the literal value zero, taking up 4 bytes (32 bits, a standard int).

• client_seed is a random 4 byte value sent by the client.

• server_seed is a random 4 byte value generated by the server.

• session_key is the session key from the original authentication.

Calculating the world proof in pseudo code would look like:

function calculate_world_server_proof
    argument username: string
    argument client_seed: unsigned 4 byte value, converted to little endian bytes
    argument server_seed: unsigned 4 byte value, converted to little endian bytes
    argument session_key: little endian array of 40 bytes
    returns little endian array of 20 bytes

    zero = [0, 0, 0, 0] // Assume this is a 4 byte array of zeros

    return SHA1(username + zero + client_seed + server_seed + session_key)

Implementations

• Rust (wow_srp)
• C# (WowSrp)
• C++ (Ember)
• C++ (Mangos)
• Elixir (Shadowburn)
• Python (wow_srp6)
• Go (go-wow-srp6)

Verification values

• calculate_world_server_proof.txt contains the columns:

Notes on uppercasing username and password

The username and password are UTF-8 strings that are automatically uppercased by the client before being sent over the network. This might present some issues with getting the correct name from the registration form and the client, more information is present at the wow_srp library documentation.

External Resources

• The Shadowburn Project has a guide on authenticating that focuses more on the networking and specific packets.
• The WoWDev Wiki has an overview of packets.
• Wireshark at version 3.5 or greater has support for parsing 1.12 packets through the WOW and WOWW protocols. You will need this if you’re trying to debug a networked implementation.

Git repository

The full assembly and a makefile can be found in this Github repository.

Background

As seen on the Pine64 BL602 EVB ver 1.1 schematics LED1 is three separate diodes controlled through GPIO17 (Red), GPIO14 (Green) and GPIO11 (Blue). LED1 is not to be confused with LED2 which just lights up red when the board is plugged in.

Page 18 of the BL602 reference manual shows that the XIP (eXecute In Place) memory starts at address 0x23000000. blflash version 0.3.0 writes binary files to address 0x23000000 by default so no linker scripts are necessary.

GPIO on the BL602

GPIO on the BL602 can be controlled through several pre defined registers. Page 24 to 29 of the BL602 reference manual describes the general approach.

In order to initialize and control the GPIO pins the following must be done:

1. The GPIO pin function and resistor type must be set. The exact register depends on the GPIO pin.
2. The relevant bit in the GPIO Output Enable register (GPIO_CFGCTL34_OFFSET) must be set.
3. The relevant bit in the GPIO Output register (GPIO_CFGCTL32_OFFSET) must be set.

The locations are described in the unofficial hardware notes.

Exact plan for GPIO11

The Global Register (GLB) is located at address 0x40000000.

Page 28 and 29 of the BL602 reference manual list GPIO_CFGCTL5 as the register for configuring GPIO10 and GPIO11. The register overview on page 36 describes the 16 most significant bits as being used for GPIO11 and the 16 least significant bits as being used for GPIO10. The two parts of the register have the same layout, GPIO11 is just bitshifted left 16:

Where reserved bits are blank and following symbols are used:

The function select should be set to 11 (0b1011) in order to choose Software GPIO, and the pull up resistor should be enabled. This means we will have to write the value 0b0000101100100000 << 16 to the GPIO_CFGCTL5 register at address 0x40000144. The LEDs require sinking current into the GPIO pins, so it should be off until you explicitly pull it LOW. If the pulldown resistor was enabled the LED would be on by default.

Next, the 11th bit of the Output Enable register (GPIO_CFGCTL34_OFFSET) at address 0x40000190 must be set. Bit shifting 1 << 11 will work.

Finally the 11th bit of the Output register (GPIO_CFGCTL32_OFFSET) at address 0x40000188 must be set LOW.

C and assembly examples

The C code is provided for reference only and has not been tested. In C we would do:

int main() {
    int* GPIO_CFGCTL5 = 0x40000114;
    int GPIO_BITSET_CFGCTL5 = 0b0000101100100000 << 16;
    *GPIO_CFGCTL5 = GPIO_BITSET_CFGCTL5;

    int* GPIO_CFGCTL32 = 0x40000188;
    int GPIO_BITSET_OUTPUT_ENABLE = 1 << 11;
    *GPIO_CFGCTL32 = GPIO_BITSET_OUTPUT_ENABLE;

    int* GPIO_CFGCTL34 = 0x40000190;
    int GPIO_BITSET_OUTPUT = 0 << 11;
    while (1) {
        // Trap execution to prevent weird results.

        // Continuously set GPIO status to ensure it isn't
        // quickly toggled off for some reason.
        *GPIO_CFGCTL34 = GPIO_BITSET_OUTPUT;
    }
}

In assembly we do almost the same, except we use the GLB as a reference point and compute relative addresses using the sw instruction.

# RM = BL602 Reference Manual 1.2. See the Pine64 bl602-docs repo.

# Global Register base address. Page 23 of the RM.
.set GLB_BASE, 0x40000000
# GPIO 10 and 11 configuration. Page 36 of the RM.
.set GPIO_CFGCTL5_OFFSET, 0x114

# GPIO Output Register. Not described in RM.
.set GPIO_CFGCTL32_OFFSET, 0x188

# GPIO Output Enable register. Not described in RM.
.set GPIO_CFGCTL34_OFFSET, 0x190

# Bitset to set GP11FUNC to 11 (SWGPIO), Pullup to 1
# and rest to zero. Page 36 of the RM.
# GPIO11 are the 16 highest bits.
.set GPIO_BITSET_CFGCTL5, 0b0000101100010000 << 16

# Bitset for Output and Output Enable register. 11th bit = GPIO11.
# High enables the output.
.set GPIO_BITSET_OUTPUT_ENABLE, 1 << 11

# Low enables the LED because the GPIO sinks current.
.set GPIO_BITSET_OUTPUT, 0 << 11

.section .text

main:
    # la = Load Address
    # Can be used to compute an offset from address, 
    # but not used here.
    # Load GLB_BASE pointer into 'temporary1'
    # int* t1 = (int*) GLB_BASE;
    la t1, GLB_BASE

    # Load bitset for config control 5 into 'temporary2'
    # int t2 = GPIO_BITSET_CFGCTL5;
    la t2, GPIO_BITSET_CFGCTL5

    # sw = Store Word (32 bits)
    # Store 'temporary2' in GLB_BASE pointer, plus the
    # GPIO10/GPIO11 register offset.
    # *(t1 + GPIO_CFGCTL5_OFFSET) = t2;
    sw t2, GPIO_CFGCTL5_OFFSET(t1)

    # Load bitset for enabling GPIO11 into 'temporary2'.
    # t2 = GPIO_BITSET_OUTPUT_ENABLE; 
    la t2, GPIO_BITSET_OUTPUT_ENABLE

    # Store 'temporary2' in GLB_BASE pointer, plus the
    # Output Enable register offset.
    # *(t1 + GPIO_CFGCTL34_OFFSET) = t2;
    sw t2, GPIO_CFGCTL34_OFFSET(t1)

    # t2 = GPIO_BITSET_OUTPUT;
    # The bitset for output enable should not be used for
    # output.
    la t2, GPIO_BITSET_OUTPUT

# Loop label.
loop:

    # Store 'temporary2' in GLB_BASE pointer, plus the
    # Out register offset.
    # This is the bit you would switch in order to blink
    # LED.
    # *(t1 + GPIO_CFGCTL32_OFFSET) = t2;
    sw t2, GPIO_CFGCTL32_OFFSET(t1)

    # Unconditionally Jump to loop.
    # goto loop;
    j loop

Building, linking and flashing

The general approach is to:

1. build the assembly with as,
2. link it with ld,
3. convert the ELF file to binary with objcopy,
4. flash it to the board with blflash.

The Pine64 version of the repository include the necessary riscv64-unknown-elf versions of every tool mentioned above (in toolchain/riscv/Linux/bin), except for blflash which can be found at the Github repository.

Exact commands can be found in the Makefile at the git repository.

Prerequisites

It is assumed that a working Pihole newer than version 5 is set up at 192.168.1.11 with an accessible admin interface at http://192.168.1.11 and that a working Edgerouter X is set up at 192.168.1.1 with an accessible admin interface at https://192.168.1.1. It might be necessary to downgrade the Edgerouter X connection to HTTP depending on settings.

The device to be regulated is assumed to be located at 192.168.1.60, and it will be referred to as “the TV” from now on. It is assumed that the TV has a reason for being on the network, since the most effective way of preventing something from communicating through a network is by not connecting it to the network. The tutorial below assumes that a single service must be used through a smart TV, and that everything else must be blocked.

Be aware that 192.168.**1**.0 and 192.168.**0**.0 are two popular address spaces for home networks that look alike at a glance. Make sure that you’re using the correct network for you, despite what the examples say.

DNS blocking on Pihole

The images are from version 5.1.1 of the Pihole Web Interface.

Log in to the Pihole Web Interface at http://192.168.1.11/admin.

Go to “Groups” under “Group Management” in the left menu as seen in figure 1.

Add a new group called “TV” and put any comments in the “Description” field as seen in figure 2.

Go to “Clients” through the same menu as figure 1.

Add the address of the TV as seen in figure 3 and include a short description. It is recommended to identify the address in some way, even if it’s just “TV”, since few people can correctly remember the IP-addresses of every device on their LAN. If the address of the TV is not found in the dropdown you can manually insert it using the “Custom, specified below” option.

Assign the new client to the group made in figure 2 and remove it from the “Default” group as seen in figure 4.

Next, go to “Domains” through the same menu as figure 1.

Add [a-z]*|[0-9]*|\. as a “Domain”, and Block all domains. as the “Comment” as seen in figure 5, and click “Add to Blacklist” just below. Remember to check the “Add domain as wildcard. This will block all domains.

Scroll down until you find the filter you added in figure 5.

Ensure that the [a-z]*|[0-9]*|\. filter you just added is a “Regex blacklist”, “Enabled” and applied only to the group you created in figure 2. It must not be applied to the “Default” group, otherwise all domains will be blocked on all devices.

All DNS queries are now blocked on the TV, and you must manually approve individual services that you require. To find out whether you need to set up your Edgerouter X for DNS redirection you should turn on your TV and check if network features are completely broken. If they are, your TV respects the DHCP provided DNS, and if they are not you either have not set your Pihole as the DNS in your DHCP settings or your TV does not respect DHCP settings.

You will now need to approve the necessary domains for your service to work. After trying to access the required service on your TV, go into the “Query Log” under “Long-term data” in the left menu. Select the date and time range “Today”. Scroll down and narrow the search to your TV by entering 192.168.1.60 in the “Search” field like in figure 7. The exact domain depends on the service you’re trying to allow. If you’re in doubt, do a search for the domain in question and read up on what it does. It might be necessary to do this over several iterations, as services on the TV might require different domains at several points.

DNS Redirection on Edgerouter X

If your TV does not use the DHCP DNS by default, you should set up DNS redirection on a firewall or router.

Log into the web interface of your Edgerouter X and click the “Firewall/NAT” tab as shown in figure 8.

Next, click the “NAT” tab as shown in figure 9.

Click the “Add Source NAT Rule” button as shown in figure 10.

Set up the rule as shown in figure 11, paying special attention to the below fields:

1. Description: Name of the rule.
2. Outbound Interface: If you used the Basic Wizard to set up the Edgerouter X, you should set this to switch0.
3. Src Address: The addresses that this rule should apply to. Since my DHCP range is 192.168.1.100 to 192.168.1.254 that’s what I’m putting in. If you only want to apply to the TV, set it to 192.168.1.1.60.
4. Src Port: Leave blank.
5. Dest Address: Set to the address of your Pihole. Set to 192.168.1.11.
6. Dest Port: Set to 53.

Click save on figure 11 and then “Add Destination NAT Rule” just below the button in figure 10.

Set up the rule as shown in figure 12, paying special attention to the below fields:

1. Description: Name of the rule.
2. Inbound Interface: Same as in figure 11.
3. Translations Address: Set to the address of your Pihole, 192.168.1.11.
4. Translations Port: Set to 53.
5. Src Address: Set to addresses you want to redirect DNS for. For everything except your pihole set to !192.168.1.11, noticing the ! which means NOT.
6. Src Port: Leave blank.
7. Dest Address: Set to the same as Src Address.
8. Dest Port: Set to 53.

Testing

In order to test your solution you should, on Windows or Linux, run nslookup [blocked domain] 8.8.8.8 and see that you get a 0.0.0.0 result back.

I have improved slightly upon his method, creating a simple Python script to download the equation images prior to publication and serving them from the local web server.

Why?

The primary reason was that I wanted a missing noscript equation to be an error at compile time instead of just a dead link. When going to the codecogs website at the time of writing, I see the following in a little box:

Licence Details
Registered use:     CLOUD
Expiration date:    31-12-2020

What does that mean? I have no idea. It might mean that service transistions to a new backend at the start of 2021, or it might mean that the service completely shuts down.

How?

Lincoln created a shortcode¹ that inserts an image with src=latex.codecogs.com/gif.latex? followed by the equation to render, ending with title= (the " are removed by Hugo).

Knowing this it is possible to create a script that finds all instances of the codecogs.com sources, downloads the equation as a file and replaces the src= attribute with the local file.

The benefits of this approach is that the noscript equations still work before the script is run, it’s just fetched from codecogs.com instead of locally.

Script

Running the script in the directory that contains the public folder will download equations, place them next to the .html file and replace the src= attribute.

#!/user/bin/env python3
from pathlib import Path
import requests
import urllib

EXTENSION = "svg"
LATEX_URL = f"https://latex.codecogs.com/{EXTENSION}.latex?"
LATEX_INLINE = f"https://latex.codecogs.com/{EXTENSION}.latex?\inline&space;"

for path in Path('public').rglob('*.html'):
    contents = Path(path).read_text();

    while (LATEX_INLINE in contents) or (LATEX_URL in contents):
        latex_url = ""
        if LATEX_INLINE in contents:
            latex_url = LATEX_INLINE
        elif LATEX_URL in contents:
            latex_url = LATEX_URL
        else:
            continue

        print("PATH: " + str(path))

        index = contents.find(latex_url)
        end = contents.find(" title=", index)
        equation = contents[index + len(latex_url):end]
        url = contents[index:end]

        f = requests.get(url).content
        with open(path.parent.joinpath(equation + f".{EXTENSION}"), 'wb') as w:
            w.write(f)

        print(f"\tReplacing {url} with {urllib.parse.quote(equation)}.{EXTENSION}")
        contents = contents.replace(url, urllib.parse.quote(equation) + f".{EXTENSION}")

    with open(path, 'w') as w:
        w.write(contents)

Future work

Ideally the equations would be done entirely at compile time without external dependencies. Currently it does not seem possible to do entirely in HTML, since the math requires some fonts that are not installed by default on most platforms. A LaTeX to SVG tool could be used, but would break the hugo serve tool since it does not seem possible to insert arbitrary commands in that process.