MD5Tool
From PunksBusted
|
The MD5Tool is a component of PunkBuster which gives a game server administrator the ability to check files in a player's game directory against a list of signatures, for the purpose of finding any improper files that a player may use for cheating purposes. In a default PunkBuster installation, using the MD5Tool is optional; unless commands for the tool are explicitly given, it will not be used automatically. The tool uses the MD5 hash algorithm to create digital signatures for files.
Related Commands and Settings
Server:
Client:
How It Works
A game server administrator places a list of specially-created file checks on his server. When the game server is running and PunkBuster is enabled, a constant rotation of these checks runs in the background. At a regular interval, a file check from the list is sent to the player by the server. The PunkBuster client receives the check and then runs it. There is a delay between file checks in order to prevent noticeable lag on the player's computer caused by the hard disk activity required to check the files. If the player does not respond to the file check in a defined period of time, or if the result of the check does not match the defined value on the server's list, the player is kicked from the server for an MD5Tool violation.
MD5Tool versus PB_SV_File
The key distinctions between the MD5Tool and the PB_SV_File command are:
- PB_SV_File only allows file checks for files with *.u or *.dll extensions, while MD5Tool allows all file types.
- PB_SV_File checks are ALL executed at the time the player joins, while MD5Tool checks are spaced out in a timed rotation.
- PB_SV_File checks create an MD5 hash for the entire file as opposed to a section of the file (which is explained below) which requires more hard disk and CPU activity to complete.
- PB_SV_File is generally restricted to file checks in the game's system directory (wherever the game's core files are stored) while MD5Tool can check files in all directories in the game installation directory.
- MD5Tool can check to ensure that a specified file does not exist, whereas PB_SV_File cannot.
- MD5Tool can check certain files which the game may lock into memory while PB_SV_File often cannot, which often leads to being kicked from the server for not being able to complete the check.
- MD5Tool can accept a check which is valid for all versions of a game. When using PB_SV_File, you must define a specific game version for that check.
Creating the Signatures
The MD5 file hash used by MD5Tool is special because it uses a defined offset within the file and a length of the file data which is to be scanned for creating the hash instead of using the entire file. Lengths may be between 16 and 2048 bytes, and the offset must be in 16-byte increments. For all practical purposes, the largest possible length should be used for the file as this is most secure. If the file is 2048 bytes or greater, the length used should be 2048 bytes, but if the file size is less than that, the largest possible length should be used instead. The MD5 hashes created by MD5Tool are also unique in that they involve custom extensions integrated into the system that were developed by Even Balance.
Even Balance MD5Tool
Since a normal MD5 hash creator cannot be used for generating these checks, Even Balance released the MD5Tool console program to create these checks. This application can be downloaded below:
- Win32: http://www.evenbalance.com/downloads/md5tool.exe
- Linux: http://www.evenbalance.com/downloads/md5tool.x86
To use this program, you would place it in the game's installation directory and then run it from the command line, providing the following three parameters: file name and path to the file to generate a file sum for, the offset, and the length to be used.
In Windows, this command may look like the following:
md5tool.exe maps/mapname.map 0 2048
In Linux, the command may look like the following:
./md5tool.x86 maps/mapname.map 0 2048
If necessary, the tool will make any slash direction corrections depending on the operating system, so you may use either forward or backward slashes in the commands. Specifying files outside the game installation folder is not allowed. Trying to specify drive letters, absolute file paths, or parent directories in the file name is not recommended as this is likely to cause problems for players who, for example, installed their game in a non-standard location.
This program can only create one file check at a time.
Frontend for MD5Tool
There is also a GUI version of the Even Balance program which a PunksBusted staff member created which is recommended because it is easier to use. This program is available for Windows only.
This program can create a list of file checks for all the files in all the directories in a game installation folder at once, which is more convenient. See the page linked above for more information about this program.
Understanding the Generated Checks
No matter which tool you use to generate the MD5Tool checks, you will end up with results which look similar to the following:
pb_sv_md5tool a "" v maps/mapname.map SZ123456 AT0 LEN2048 4b15ea20788166439a11bd77938a8870
The syntax for this is as follows:
- pb_sv_md5tool - The command to be executed (see the PB_SV_MD5Tool page for more info).
- a - Operating system which the check is valid for. Acceptable values are a for All, w for Windows, l for Linux, and m for Mac.
- "" - Game version the check is valid for, in double-quotes. An empty version as is present in this check applies to ALL game versions. Any other value must be a valid game version number.
- v - Type of check. This can either be v meaning Violation (the player will be kicked from the server if the check returns an incorrect value, and the violation will be logged) or l meaning Log (the failed check will be recorded in the server log but the player will not be kicked). There is a third option which is rarely used: a, which logs all file checks, including those which are not mismatched. Be aware that this will probably fill up your log files very quickly with excess data.
- maps/mapname.map - The file path and file name of the file to be checked, relative to the game installation directory. If the file path or file name contain spaces, this part must be enclosed in double-quotes.
- SZ123456 - The size of the complete file, in bytes. The numeric value is preceded by the letters SZ and does not contain any commas.
- AT0 - The offset in the file at which the check will begin. The numeric value is preceded by the letters AT and does not contain any commas. This value must be in 16-byte increments (0, 16, 32, etc.).
- LEN2048 - The length of the file data to be checked (starting at the offset point defined above), in bytes. The numeric value is preceded by the letters LEN and does not contain any commas. This value must be between 16 and 2048, inclusive. 2048 is recommended whenever possible.
- 4b15ea20788166439a11bd77938a8870 - The MD5 hash that was generated using the MD5Tool which is an acceptable value for the file check.
Examples
Operating System and Game Version Specified
pb_sv_md5tool w "1.0" v maps/mapname.map SZ123456 AT0 LEN2048 4b15ea20788166439a11bd77938a8870
- Operating system set to w for Windows. This check will be ignored if the player is on any other operating system.
- Game version set to "1.0". This check will be ignored is the player's game version is not exactly equal to 1.0
Multiple Acceptable File Sums Defined
pb_sv_md5tool a "" v maps/mapname.map SZ123456 AT0 LEN2048 "4b15ea20788166439a11bd77938a8870 d62c7199d8d56d51fd143d88e163ece7"
- The check is all on a single line. It is displayed here on multiple lines for legibility only.
- If multiple versions of a file are acceptable, enclose the file sum results for them in double-quotes and put a space between each acceptable result.
- Note that this check is not effective if the different versions of the file have different file sizes. They must match except for the file sum result in order to use a check like this. Alternatively, you may set the SZ value in the check to zero (SZ0), however this reduces security significantly and is not recommended.
NOT_FOUND Check
pb_sv_md5tool a "" v system/badfile.bad NOT_FOUND
- This is a special check which determines if the stated file is present on the player's computer, and results in a violation if it is. Exclude the SZ, AT, LEN, and sum parameters and instead use the text NOT_FOUND (including the underscore).
Best Practices for Writing Checks
- Always define a game version number for game stock file checks. If a game patch is released, your checks will not be run against changed files and cause lots of false kicks.
- Define an operating system when possible. If a certain file is only going to be present on a Windows installation of the game, use the w parameter.
- Enclose any entry with a space in it with double-quotes.
Using the MD5Tool on Your Servers
In order to be executed, the list of checks you created needs to be either included into the automatically-executed PunkBuster configuration files on your server (pbsv.cfg or pbsvuser.cfg) or you will need to create another configuration file and use the PB_SV_Load command in either of the two above files to load it.
Using the PB_SV_MD5ToolEmpty command will clear all MD5Tool entries in your server's memory (but will not remove them from any configuration files on your server). To see a list of running MD5Tool checks in-game, use the PB_SV_MD5ToolList command. If you want to remove individual checks, you can use the PB_SV_MD5ToolDel command after you determine which check you want to remove by using the list command.
The MD5Tool Rotation Interval
One of the important concepts to understand about using the MD5Tool on your servers is that the checks are executed in a timed rotation. There is a set interval between each check, which is defined using the PB_SV_MD5ToolFreq setting. Depending on the game, this value may default to anywhere from 10 seconds to 30 seconds and even 60 seconds. This value determines the amount of time in between each MD5Tool file check request that is made by the server to the players.
To help you understand this process, we will use an example below. Assume that the interval value is 30 seconds. This means that one file check will be ordered by the server every thirty seconds.
The Time column is the number of seconds since the server was started. When a file check is scheduled to occur after that, the box in this column is highlighted in blue.
| Time | Server | Player |
| 0 | Server started. File Check #1 ordered. | |
| 30 | File Check #2 ordered. | |
| 35 | PlayerA joins server. | |
| 60 | File Check #3 ordered. | PlayerA executes File Check #3. |
| 65 | PlayerB joins server. | |
| 90 | File Check #4 ordered. | PlayerA and PlayerB execute File Check #4. |
In the cases of the first and second file check, no players are on the server when the server calls for them to be executed. PlayerA joins the server after the second file check is ordered but before the third one. When the third file check is ordered, his PunkBuster client executes the check given to it by the server and returns the result. PlayerB then joins the server. When the fourth file check in the list is ordered, both PlayerA and PlayerB is and will execute that check. Players who join the server enter the rotation of file checks at whatever point it is at when they join, they do not start from the top of the list on their own.
When the end of the list of check is reached, the rotation begins again at the top of the list, and this pattern is continued indefinitely until either the server is restarted (and it loads the checks again from the configuration files) or the PB_SV_MD5ToolEmpty command is issued.
It may seem that the best solution would be to lower the interval value to as low as possible and then more checks would be conducted more quickly. However, there is a problem when using MD5Tool checks that if too many occur too frequently, players become lagged or start dropping the requests to execute the checks. When this happens, the player is kicked by PunkBuster for Ignoring MD5Tool Queries. Therefore, PunkBuster will ignore any interval values that are set too low (which varies from game to game).
The optimal MD5Tool file check list rotation then must consider the following two points:
- The value of PB_SV_MD5ToolFreq should be as low as possible, but not so low that player experience is degraded and players get kicked routinely for Ignoring MD5Tool Queries.
- The total number of checks in the list should be as low as possible so that as many players are possible go through the entire list at least once during their time on the server, while still high enough to include enough file checks to be meaningful.
Changes to MD5Tool behavior in individual game (in regards to the default rotation interval and other settings) are announced in the PunkBuster release notes for each game. To find these release notes, go to the Even Balance support page and then click on your game. You should monitor that page frequently and note any changes that Even Balance may make to the MD5Tool in your game. You may also be able to find the default rotation interval on that page as well.
READ_FAIL Errors
An MD5Tool check may return a READ_FAIL error if the defined parameters of the check instruct the PunkBuster client to read beyond the boundaries of the file. For example, if a file which is going to be checked is 4000 bytes long, and the check that is requested has an offset of 3000 and a length of 2048, the final result is that the check is asking to read beyond the closing end of the file by 1048 bytes, which is not allowed.
Any checks that result in READ_FAIL errors should be removed from your list of checks or their logic should be corrected so that they do not continue to cause this error.
Client Logging of MD5Tool Checks
A client can use the PB_LogMD5Tool command to see the MD5Tool queries that are being executed. As a game server administrator, you can use this to debug your checks by watching them execute, which is helpful in seeing the rotation process and identifying any checks which cause errors or false kicks.
