TPUtils - Tarma Preloader Utilities

The Tarma Preloader Utilities are a set of programs that convert an executable program to a compressed, self-extracting new program with optional predefined command line arguments, and an optional embedded Administrator password for deployment in locked-down environments.

  • Download TPUtils (requires a license and a password to install)
  • Secure Buy online (TPUtils costs US$49 per developer; you will automatically receive the password to install TPUtils)

After downloading, run TPUtils.exe to install the utilities on your system. The Tarma Preloader utilities consist of the following files:

  • Preloader.exe is a small executable that forms the head of the self-extracting archive. You do not use this program directly.
  • TPMake.exe is a console program that builds the self-extracting archive. It is documented below.
  • TPSet.exe is a console program that sets or removes the embedded Adminsitrator password. It is documented below.
  • TinCompress.dll is a helper library used by TPMake.exe.

The general workflow is as follows:

  1. Open a command prompt window (Start > Run > cmd.exe, press Enter; or Start > All Programs > Accessories > Command Prompt).
  2. Run TPMake.exe to build the compressed, self-extracting archive.
  3. Optional: Run TPSet.exe to embed the Administrator password for the intended target systems.
  4. Distribute the resulting self-extracting archive.

System requirements: Runs on Windows 2000, XP, Vista, their Server editions, and later, both 32-bit and 64-bit versions. It does not run on Windows 9x systems or Windows NT4.

TPMake.exe

TPMake /?
TPMake [/a:"arguments"] [/o:[path\]output_name.exe] [path\]input_name.exe

The first form displays a syntax summary and exits. The second form creates a self-extracting archive with optional embedded command line arguments. The following options are supported:

/a:"arguments"
Embed the argument list arguments in the self-extracting archive. At runtime, the command line for the embedded executable consists of arguments, followed by a space, followed by any additional arguments that are passed on the command line of the self-extracting archive. You must "quote" the set of arguments to avoid misinterpretation of any '/' or '-' characters inside the arguments list. The maximum allowed length of arguments is 63 characters.
/o:[path\]output_name.exe
Write the resulting self-extracting archive to [path\]output_name.exe. This must specify at least a file name (with a .exe extension), and may contain a full path specification. If this option is not specified, the self-extracting archive is written to [path\]input_name#.exe (i.e., the path and name of the input file, with a hash character '#' appended to the name).

TPMake.exe builds the self-extracting archive as follows:

  1. The Preloader.exe stub is copied to the output path (either [path\]output_name.exe or [path\]input_name#.exe).
  2. The VERSIONINFO from [path\]input_name.exe is copied to the VERSIONINFO of the output file, so the resulting self-extracting archive will carry the same internal product name and version, and other details, as the original executable.
  3. [Optional] If the /a command line option is specified, the given arguments are embedded in the preloader.
  4. The file [path\]input_name.exe is compressed and appended to the preloader stub to form the complete output file.

The resulting self-extracting file is ready to run. For details of its operation, see the section Runtime operation below.

TPSet.exe

TPSet /?
TPSet [/n:name] [/p:password] [path\]output_name.exe

The first form displays a syntax summary and exits. The second form modifies the self-extracting archive [path\]output_name.exe. The following options are supported:

/n:name
Embeds an encrypted version of name inside the self-extracting archive. If present, and if a password is also present (see /p option), then this name is used at runtime to run the embedded executable under the named account.
/p:password
Embeds an encrypted version of password inside the self-extracting archive. If present, this password is used at runtime to run the embedded executable under the name account (if the /n option is also used) or the local Administrator account (if the /n option was not used). If you do not specify the /p option, then any existing name and password are removed from the self-extracting archive.

TPSet.exe can be used to prepare an existing self-extracting archive for a new environment for which the Administrator password is known (for example, in a organizational setting where many systems share the same Administrator password).

Runtime operation

At runtime, the self-extracting archive created and modified by TPMake.exe and TPSet.exe can be run as:

output_name.exe [additional command line arguments...]

The preloader stub at the start of the self-extracting archive receives control and then performs the following actions:

  1. The embedded executable is extracted and copied to the Temp folder of the current user, using its original file name. In other words, the executable is stored as %TEMP%\input_name.exe
  2. A new set of command line arguments is prepared that consists of the arguments that were embedded through the TPMake /a option, followed by a space and the arguments, if any, that were passed by the command line that started the current instance of the self-extracting archive. The resulting command to be executed becomes "%TEMP%\input_name.exe" embedded_options additional_options
  3. If a non-empty password was embedded in the self-extracting archive by the TPSet /p option, then:
    1. If an account name was also embedded (with the /n option), then that name is used; else the name of the local Administrator account is retrieved from the system (this will be Administrator on most English Windows systems, but might be something else on non-English systems or if the system administrator intentionally renamed the Administrator account).
    2. Using the embedded or the administrative account name and the decrypted version of the embedded password, the program attempts to log on with those credentials and then starts the embedded executable under that account.
  4. If no password is present, the embedded executable is started normally. This may lead to a Windows UAC elevation prompt if the executable contains an application manifest that requests elevation.
  5. The preloader waits until the embedded program terminates, then deletes the temporary copy %TEMP%\input_name.exe and terminates itself. It returns the exit code from the embedded program.

If an error occurs at any point, the preloader stub terminates prematurely and returns a suitable exit code of its own. The following exit codes are defined:

Value Description
0 Success
250 Access denied: A password was embedded but could not be used to log on as Administrator.
251 WaitForProcess() failed while waiting for the embedded process to terminate.
252 CreateProcess() failed while trying to start the embedded process
253 (not used)
254 Invalid loader stub
255 General function failure
any other Exit code from the embedded process

Note: Under normal circumstances, the preloader does not display any error messages. You can enable the display of preloader error messages by pressing and holding either Shift key when you start the self-extracting archive. The preloader will then display an initial confirmation, after which you can release the Shift key. This option is meant for testing and diagnosis, not for normal usage.

Examples

Here is a usage example: 

TPMake /o:Editor.exe "C:\Program Files\PSPad\PSPad.exe"
TPSet /p:magic_words Editor.exe
Editor.exe sample.cpp

In this sample, we create a self-extracting archive called Editor.exe that contains the PSPad.exe program internally. We then set the embedded Administrator password to magic_words, and finally run the self-extracting archive with the command line option sample.cpp

If all goes well, this will extract and start the embedded PSPad.exe program, run it under the local Administrator account, and load the sample.cpp file for editing.

Another usage example: 

TPMake /o:Editor.exe "C:\Program Files\PSPad\PSPad.exe"
TPSet /n:RealAdmin /p:magic_words Editor.exe
Editor.exe sample.cpp

This sample is similar to the previous, but embeds the account name RealAdmin inside the self-extracting archive. At runtime, the preloader will try to run the embedded PSPad.exe program under account RealAdmin with password magic_words.