PunkBuster MD5 Tool (pbmd5)

History

Starting in January of 2004, PunkBuster Server Admins have the option of using the new PB MD5Tool facility to check the digital signatures of files and/or portions of files in each player's game directory and child subdirectories during gameplay. This is useful, for example in Quake3 based games, to check for modified, replaced or additional pk3 files for cheats and/or exploits that have to this point not been detectable by PunkBuster. In Rainbow Six 3: Ravenshield, this facility can be used to check for modified or missing ambient sound files, etc.

The MD5 (Message Digest 5) algorithm was developed by Rivest and is ©Copyright by RSA Data Security, Inc.. PunkBuster extensions to MD5 are ©Copyright by Even Balance, Inc. Source code for MD5 with PB extensions can be found on the links page of this website. PunkBuster uses 128-bit (32 hex character) MD5 strings to compare files on players' systems against parameters specified by server admins who choose to deploy PB's MD5Tool Facility on their server(s).

Installation and Usage

WARNING: This is an advanced topic intended for experienced server admins who are comfortable with running PunkBuster-enabled game servers. Improper use of the MD5Tool Facility can result in inadvertently configuring PunkBuster to kick all players from the server.

By default, PunkBuster does not scan files during gameplay because disk access during gameplay can cause minor hanging, stuttering and/or lag effects for players depending on their individual systems. However, in some cases, admins and players are willing to allow minimal file scanning as a tradeoff to ensure that the files being used by players are not tampered with to exploit the game beyond what each server admin deems allowable. The PB MD5Tool Facility was developed for those admins and players.

To use the MD5Tool Facility, server admins must configure their PunkBuster server(s) to keep a list of files to be checked along with certain other parameters such as file offset and number of bytes to check. For each check, PunkBuster limits the offset to 16 byte boundaries and the length of data checked to between 16 and 2048 bytes per check. Additionally, PunkBuster waits a while between file checks so that players will not see constant disk activity during gameplay. By default, one file is checked every 60 seconds. Admins can set the pb_sv_md5toolfreq setting from 30 to 300 seconds to determine how often PB cycles from one file check to the next for each player on their server(s).

To help server admins configure PB servers for use with the MD5Tool Facility, we have developed a small utility program that should be used to generate PB Server commands for use in configuring their system(s). Currently, this beta utility program is available as a win32 or linux console command line program. It can be downloaded from here:

• Windows MD5 tool (version 0.90)
• Linux MD5 tool (version 0.90)

To use the utility, place it in the game's installation folder and run it from a windows command line or linux shell command line with 3 supplied parameters (filename with path, file offset, and length in bytes to check). For example, if you are a Quake3 admin and you wish to check the first 2048 bytes of the pak0.pk3 file that is installed as part of a standard Quake3 installation, use one of the following utility commands:

Windows: md5tool.exe baseq3/pak0.pk3 0 2048
Linux: ./md5tool.x86 baseq3/pak0.pk3 0 2048

Another example for Ravenshield admins who want to check, for example, a sound file:

md5tool.exe sounds/ambiences_alpine.uax 0 1980

Note the use of the forward slash to separate folders and filenames. This facility automatically adjusts between forward slash and backslash for the target operating system. Specifying files outside the game folder is also not allowed. Trying to specify other drive letters, absolute/fully qualified filepaths or parent directories in the filename will cause the system to behave in an undefined manner and will almost certainly result in causing problems for players.

Issuing a command similar to one of the provided examples will cause the md5tool utility program to append a PB Server command to the pbsvuser.cfg file in the target folder from where the utility was launched. Admins may run the utility as many times as desired to populate a trial pbsvuser.cfg file with desired file checks. This trial pbsvuser.cfg file should then be edited with a text editor such as wordpad or notepad for copy/pasting to the live pbsvuser.cfg file in the game's home pb directory. The format of the PB Server's pb_sv_md5tool command is as follows:

pb_sv_md5tool [O/S] [gamever] [type] [filename] SZ[size] AT[offset] LEN[bytes] [MD5]

Note that if the file being checked has between 16 and 2048 bytes, the entire file may be checked by specifying 0 for the offset parameter and the file size as the length paramether. However, only our provided MD5Tool utility program should be used to generate data for PB's MD5Tool Facility. We use custom MD5 extensions to produce digital signatures of the files and using other MD5 generators or utilities will not provide the same signature on a given file or partial file for use with PB's MD5Tool Facility.

When editing the trial pbsvuser.cfg file produced by our MD5Tool utility program, the first 3 parameters of the pb_sv_md5tool may need to be modified for each filecheck depending on the admin's desires for the file being checked.

The first parameter is the [O/S] parameter. This will tell the PB Server which Operating System(s) to check for the specified file:

• a=all
• w=win32
• l=linux
• m=mac

If an O/S dependent file such as a *.dll or *.so file is specified, then this parameter must be adjusted accordingly or there will be problems for players running PB under other platforms.

The second parameter is the [gamever] parameter. This will tell the PB Server to which version of the game this file check applies. The MD5Tool utility program outputs a double quote "" by default for this parameter which means 'all versions'. If a version specific file is being checked, then a version string should be specified for this second parameter or future game versions that modify files normally may falsely trigger players whose new files are being compared against old signatures. When the PunkBuster Server starts up, it outputs the current game version both to the console and to the PB Server logs - specifying the numeric portion of the version is generally sufficient (for example "1.32" for Quake3).

The third parameter is the [type] of file check:

• v=violation on mismatch
• l=log on mismatch
• a=log all file checks

Additionally, if for some reason, an admin does not care that the filesize of the player's file match the actual filesize of the target file, the SZ[size] parameter may be set to zero. The other parameters should not be changed.

There are two special cases. First, if a filename is specified that does not exist, the MD5Tool utility program will output a line that ends with "NOT_FOUND". This may be useful to admins who want to make sure that players do not have a file with a specific name. For example, in Quake3, it may be useful to know that players do not have a baseq3/pak9.pk3 file. The second special case is if parameters are specified such that the MD5Tool utility program tries to read beyond the end of the target file. In this case, a line that ends with "READ_FAIL" will be output. We encourage admins to not use any file checks that contain a "READ_FAIL" message.

Once the trial pbsvuser.cfg file has been edited to the admin's satisfaction, the lines can be copy/pasted into the pb/pbsvuser.cfg file so that the PunkBuster Server will process the commands the next time it is initialized/restarted. Admins are heavily encouraged to fully test all file checks on a private server before deploying to a live public server.

For example, a Quake3 admin who wanted to check against all 8 base Q3 pak files may want to copy/paste the following set of file checks into the actual pbsvuser.cfg file in the game's home PB directory:

pb_sv_md5tool a 1.32 v baseq3/pak0.pk3 SZ479493658 AT0 LEN2048 7F0A1D6E2BB8E138B61E08B716CE2758
pb_sv_md5tool a 1.32 v baseq3/pak1.pk3 SZ374405 AT0 LEN2048 C4002CF54644DF2A8DD5C9B8E1D21BB5
pb_sv_md5tool a 1.32 v baseq3/pak2.pk3 SZ7511182 AT0 LEN2048 C14AF544F75AD0DEF99587CB210FAEA5
pb_sv_md5tool a 1.32 v baseq3/pak3.pk3 SZ276305 AT0 LEN2048 9E9E8ED4B881CB902A86B0640C0D26BA
pb_sv_md5tool a 1.32 v baseq3/pak4.pk3 SZ9600350 AT0 LEN2048 0F6CE153C6E94E8BC35CB08A7B70050C
pb_sv_md5tool a 1.32 v baseq3/pak5.pk3 SZ191872 AT0 LEN2048 D95EF079DD04753835B385DF4F458872
pb_sv_md5tool a 1.32 v baseq3/pak6.pk3 SZ7346884 AT0 LEN2048 60F6DB55045A336BCAA103774E46402F
pb_sv_md5tool a 1.32 v baseq3/pak7.pk3 SZ320873 AT0 LEN2048 0BA06C9ADD4EC5ED277155783B85D43A
pb_sv_md5tool a 1.32 v baseq3/pak8.pk3 SZ454478 AT0 LEN2048 2E10507A574871D3ED1394A3F951B959
pb_sv_md5tool a 1.32 v baseq3/pak9.pk3 NOT_FOUND

Additional Commands

There are a few other PB Server commands that pertain to the MD5Tool Facility:

• The pb_sv_md5toollist command will output to the server console all file checks in the PB Server's current working set (each with a slot#).
• The pb_sv_md5tooldel command will delete a specific file check in memory (using the slot# shown by the pb_sv_md5toollist command output).
• The pb_sv_md5toolempty command will clear out the file checks in the PB Server's memory - akin to deleting all current file checks.

Also keep in mind that, beginning with PB Client version 1.066, players are able to set "pb_logmd5tool 1", if desired, to monitor every file check queried from their system during gameplay.

Players should also be aware that any detected attempt to circumvent MD5Tool file checks will be subject to a Global PB GUID ban. The banned GUIDs/CD keys associated with such attempts will not be allowed to join any Internet based PB servers from that point forward without recourse. Banned GUIDs/CD keys will still be usable on non-PB Servers.

Getting Help

For MD5Tool support, please use our Web Ticket System.