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 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 [ -- [ aespipe_options ] ] Keyfile option (required): -k, -K, --keyfile 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 . 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 Specify input filename (/dev/stdin) -o, --output Specify output filename (/dev/stdout) -U, --urandom Use /dev/urandom. (default) -R, --random Use /dev/random, might be slow. -r, --recipient Encrypt AES keys with 's GPG pubkey. (self) s must be shell-safe (e.g., no spaces)