aespipe-wrapper-0.49 README

Description
===========
This is simply a thin convenience wrapper around aespipe*.  The aespipe
utility acts as a filter (reading from STDIN, writing to STDOUT), but it
also reads a set of keys on a separate file descriptor.  There are two
sets of keys involved in the operation of this script.

  aespipe uses a set of AES keys for encrypting your stream of data
  GPG encrypts the AES keys, so they aren't stored unsafely on disk

NOTE:  During encryption, aespipe null-pads the end of the file to reach
       a block boundary.  During decryption, aespipe does not remove
       these nulls, so the checksum of the initial file and the
       decrypted will differ.  Compression utilities are comfortable
       stripping the nulls, so consider using bzip2/gzip before
       passing the data to aespipe.

Modes
=====
Encryption (--encrypt):  To accommodate automated encryption, aespipe-wrapper
does the following:

  1. it does not ask for passwords or passphrases from the terminal in
     encryption mode (suitable for fully automated use)
  2. it generates a keyset suitable for aespipe encryption
  3. it stores the keyset in the specified keyfile, encrypted using GPG
     public key cryptography to an arbitrary set of recipients
  4. finally, it calls aespipe, feeding STDIN, STDOUT and keys

Decryption (--decrypt):  Decryption is simpler.  The wrapper simply
calls aespipe with the provided keyfile and the input and output
redirections in place.

Creation (--create):  Key creation is a simple way to test that everything is working, and is
only supplied as a convenience.

The user must always:

  - specify a keyfile with the -k (--keyfile) option
  - specify an action (--decrypt, --encrypt or --create)

If you have a need to pass options through to aespipe itself, simply place
them after \"--\", and they will be passed through directly to aespipe.
See the example section below.


Options
=======
aespipe-wrapper operates on STDIN and STDOUT, as any good filter.  It provides
the compatibility options --input (-i) and --output (-o) for convenience.

Usually, data collected by the pseudo-random device (/dev/urandom) is
suitably random to use in cryptography, although many people prefer to
use a real random source (e.g., /dev/random).  Because of the possibility
for program delay awaiting random data, the default option is the 
pseudo-random device.

If no GPG recipient <id> is specified with the -r (--recipient) option,
aespipe-wrapper will use GPG's --default-recipient-self option to
specify a public key identity use for encrypting the AES keys.  Multiple
recipients can be specified with the --recipient option.  This could
allow any of the recipients to decrypt the AES keyset.

Examples
========
Encrypt the word 'HOWDY.' into a file called howdy.aes.  Retain the AES
keys used for encryption in the howdykeys.asc file.

  echo HOWDY. | aespipe-wrapper -E -k howdykeys.asc -o howdy.aes

Decrypt the file called howdy.aes, using the keys in the file called
howdykeys.asc.  Note that this will require reading the user's GPG
passphrase from the terminal.

  aespipe-wrapper -D -k howdykeys.asc -i howdy.aes

In this more practical example, let's look at how we might use
aespipe to encrypt a backup of our files.  To add further complexity,
let's ask aespipe to use 256-bit keys:

  tar --create                  \
      --bzip2                   \
      --to-stdout               \
      --files-from $filelist    \
    | aespipe-wrapper --encrypt \
      --keyfile $keys           \
      --output $archive         \
      -- -e aes256

Now, let's decrypt that same data file.  Note that we have to specify the
pass-through option to aespipe ('-e aes256') or else we'll have no luck
at all decrypting the data.

  aespipe-wrapper --decrypt     \
      --input $archive          \
      --keyfile $keys           \
      -- -e aes256              \
    | bzip2 --decompress        \
      --quiet                   \
      --stdout                  \
    | tar --list

Comments, criticism, corrections and suggestions are welcome.

 *How in the world did you get here without aespipe!?  If you don't have
  this great utility, then sprint to the aespipe site and grab yourself
  a copy:  http://loop-aes.sourceforge.net/aespipe/

Usage: aespipe-wrapper [ options ] -k <file> [ -- [ aespipe_options ] ]

Keyfile option (required):
  -k, -K, --keyfile <file>   Specify filename in which to store AES keys.

Action options (one of these mutually exclusive options is required):
  -d, -D, --decrypt          Decrypt the input file
  -e, -E, --encrypt          Encrypt the input file
  -c, -C, --create           Create and encrypt a keyset into <keyfile>.

Options (defaults marked, or in parentheses):
  -h, --help                 Print out this handy help screen.
  -L, --long-usage           Provide help and some more hints.
  -q, --quiet                Reset verbosity to none.
  -v, --verbose              Be verbose.  (interactive default)
  -i, --input <name>         Specify input filename (/dev/stdin)
  -o, --output <name>        Specify output filename (/dev/stdout)
  -U, --urandom              Use /dev/urandom. (default)
  -R, --random               Use /dev/random, might be slow.
  -r, --recipient <id>       Encrypt AES keys with <id>'s GPG pubkey. (self)
                             <id>s must be shell-safe (e.g., no spaces)