Overview

A Payload and Delivery (PaD) file is a self-extracting executable
that can be packaged as either a script or a program. In addition
to extracting their payload, PaD executables support flexible
payload delivery. In other words, the user controls if, when,
and how a given payload will be delivered. Within the PaD context,
delivery refers to the act of running one or more commands to
manipulate or otherwise make use of the extracted payload.

The Basics

When invoked without command-line arguments, a PaD executable
will extract its payload to a file whose name is the basename of
the executable. For example, payload.tgz.pad would be extracted
to payload.tgz.

When invoked with command-line arguments, a PaD executable will
first extract its payload. Then, it will proceed to deliver that
payload by invoking the remaining arguments as a new command.
For example, the command line shown below would extract
payload.tgz.pad to a file named payload.tgz, and then, deliver
the payload using gzip and tar. The %payload argument is a place
holder. A PaD executable will replace all instances of this
token with the actual payload filename prior to delivery.

payload.tgz.pad gzip -dc %payload \| tar -C /tmp -xf -

Note how the '|' character is escaped. This ensures that all
command-line arguments are passed to the PaD executable. As it
turns out, this particular type of delivery would have worked
regardless of whether or not the '|' character was escaped.
That's because PaD logic does not write any diagnostic/error
messages to stdout -- i.e. stdout is kept clean for delivery
purposes.

Highlights and Advantages

PaD technology is particularly attractive for the following
reasons:

Its extract/delivery logic is simple and easy to validate. This
supports the position that the PaD mechanism, itself, is safe and
reliable.

It supports binary payloads.

Payload delivery is flexible -- i.e. the user determines if, when,
and how the payload will be delivered. This provides a mechanism
for the user to include custom payload validation checks in-line
with the delivery arguments.

It is well suited to on-the-fly construction. This makes it a
good candidate for automated content delivery schemes.

Payload delivery is not bound to payload extraction -- i.e. one
payload can be delivered many ways.

It allows you to turn regular files, such as SSH keys or configuration
files, into PaD executables. These executables can then be used
to drive programs that normally require such files as input.

Drawbacks and Issues

PaD technology is not for everyone:

It is general purpose and can, therefore, cut both ways. In other
words, an attacker could use or cause you to use a PaD executable
to infiltrate and execute malicious tools.

It lacks the ability validate payload integrity and has no inherent
self-protection mechanisms.

It depends on delivery programs that exist on the target system.
If you can't trust such programs, then extra precautions may need
to be taken to verify that the delivery process went as expected.

Construction

To create a functional PaD executable, you need to combine the
following components in their respective order: PaD logic, PaD
delimiter, and target payload. PaD logic comes in two forms:
script and binary. The PaD delimiter is simply the string,
PAD_GUTS_DELIMITER, followed by a newline (i.e. '\n'). PaD logic
uses this delimiter to determine the location of the embedded
payload.

By convention, PaD filenames are constructed by appending '.pad'
to the payload's filename. In fact, PaD logic will refuse to
extract its payload unless this suffix is present.

The following example demonstrates how payload.tgz.pad can be
constructed from payload.tgz. The newly constructed PaD file
needs to be executable, so remember to check its permissions and
make any necessary adjustments before invoking it.

pad-make-binary --create payload.tgz > payload.tgz.pad

or

pad-make-script --create payload.tgz > payload.tgz.pad

The pad-make-{binary|script} commands conveniently automate PaD
construction. The binary form, however, can't create cross-platform
PaD files. When you need that capability, use pad-join as it
allows you to combine binary guts from the appropriate platform
with the target payload. The following example demonstrates how
payload.tgz.pad would be constructed from payload.tgz. Assume,
for this example, that the binary guts are from Solaris and the
the command is invoked under Linux. The result is a native Solaris
binary.

pad-join pad-binary-guts payload.tgz > payload.tgz.pad

PaD Requirements

Any delivery programs that you intend to use (e.g., gzip, tar,
etc.) must exist on the target system a priori.

For PaD scripts to work properly, the following programs must
exist on the target system: [, awk, basename, echo, expr, grep,
head, rm, sed, sh, tail, and wc.

For PaD programs to work properly, they must contain binary guts
that are native to the target system.

PaD and WebJob

PaD executables were designed to work in conjunction with WebJob.
In particular, they extend the run time environment by allowing
WebJob to, in effect, download it. Suppose you need a whole
directory of tools to perform some task. One approach would be
to tar up the directory and make it available to WebJob clients
as a PaD executable. Since payload delivery is user-defined, it
would be possible to unpack the tar ball (i.e. the environment)
and execute a program or script within it. The following example
shows how this might work.

This example assumes that unpacking payload.tgz will create a
directory called payload.

Note: If you execute a PaD command from within a Windows batch file
(i.e., .bat or .cmd), you'll need to escape the '%' in '%payload'.
This is done by prefixing the string with an additional '%'. Thus,
'%payload' becomes '%%payload' in your command.

Acknowledgments

The idea to use 'tail +${SKIP}' as the extraction mechanism comes
from makeself-1.5.3 by Stéphane Peter.

License

All PaD documentation and code is distributed under same terms
and conditions as WebJob.