Written by Jari Ruusu <jariruusu@users.sourceforge.net>, September 10 2017

Copyright 2002-2017 by Jari Ruusu.
Redistribution of this file is permitted under the GNU Public License.


Table of Contents
~~~~~~~~~~~~~~~~~
1.    General information
2.    How to compile aespipe program
3.    Examples
3.1.  Example 1 - Encrypted archive with seeded and iterated key setup
3.2.  Example 2 - Encrypted archive with gpg-encrypted key file
3.3.  Example 3 - Encrypted CD-ROM
3.4.  Example 4 - Adding encryption to existing file system
4.    Files
5.    Credits


1. General information
~~~~~~~~~~~~~~~~~~~~~~
aespipe program is AES encrypting or decrypting pipe. It reads from standard
input and writes to standard output. It can be used to create and restore
encrypted tar or cpio archives. It can be used to encrypt and decrypt
loop-AES compatible encrypted disk images.

Latest version of this package can be found at:

    http://loop-aes.sourceforge.net/
    http://sourceforge.net/projects/loop-aes/files/aespipe/


2. How to compile aespipe program
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To compile, test and install, run:

    ./configure
    make
    make tests
    make install

Possible options for ./configure script:

--disable-asm       Disable assembler code for x86/amd64/padlock/intelaes
--enable-asm=x86    Always use optimized assembler code for x86
--enable-asm=amd64  Always use optimized assembler code for amd64
--enable-padlock    Add support for VIA padlock hardware AES
--disable-padlock   Remove support for VIA padlock hardware AES
--enable-intelaes   Add support for Intel hardware AES
--disable-intelaes  Remove support for Intel hardware AES

Fastest code for 32 bit x86 (i386, IA-32 & clones):

    ./configure --enable-asm=x86 --enable-padlock --enable-intelaes

Fastest code for 64 bit amd64 (AMD64, x86-64, EM64T, Intel64):

    ./configure --enable-asm=amd64 --enable-padlock --enable-intelaes

When using GNU tool chain (C compiler, assembler, linker)
x86/amd64/padlock/intelaes are automatically detected by ./configure script
and need not be specified. Assembler code for x86/amd64/padlock/intelaes
require GNU tool chain to compile correctly. If ./configure script
incorrectly detects the tool chain in use, then --disable-asm option may be
needed to successfully compile aespipe. --enable-padlock and
--enable-intelaes options can be used in situations where build host
computer doesn't have padlock/intelaes hardware, but intended target
computer does. padlock/intelaes code always include run time fall back to
slower software implementation in case the padlock/intelaes hardware isn't
found.

If you want to use special compiler and/or linker flags, ./configure script
understands exported CFLAGS= and LDFLAGS= environment variables. In cases
where compiler/linker produces position independent executable (PIE) by
default and you want to use assembler optimized code, the PIE thingy needs
to be disabled like this:

    CFLAGS="-O2 -Wall -fno-pie" LDFLAGS="-no-pie" ./configure

Above installs aespipe program to /usr/local/bin/ directory and man page to
/usr/local/man/man1/ directory. If you want aespipe program installed in
/usr/bin/ and man page installed in /usr/share/man/man1/, add
"--bindir=/usr/bin" and "--mandir=/usr/share/man" parameters to ./configure
script.

When aespipe uses gpg version 2 to decrypt public-key encrypted key file,
gpg needs special bug workaround. gpg version 1 does not need that
workaround, and that workaround is not compatible with gpg version 1.
configure script detects the need for this gpg bug workaround at configure
time. If you change installed gpg version from 1 to 2, or from 2 to 1, then
aespipe needs to be configured and compiled again to enable/disable the
workaround.


3. Examples
~~~~~~~~~~~
Many of following examples depend on gpg-encrypted key files. gpg appears to
prevent its own keys from being leaked to swap, but does not appear to
prevent data handled by it from being leaked to swap. In gpg-encrypted key
file cases, the data handled by gpg are aespipe encryption keys, and they
may leak to swap. Therefore, use of gpg-encrypted key file depends on
encrypted swap.


3.1. Example 1 - Encrypted archive with seeded and iterated key setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A random password seed and password iteration count are used to slow down
dictionary attacks. Edit bz2aespipe script to suit your needs, and copy it
to someplace in your path, /usr/local/bin/ for example.

Write files to bzip2 compressed, encrypted tar archive:

    tar cvf archive.aes --use-compress-program=bz2aespipe files...

Restore files from bzip2 compressed, encrypted tar archive:

    tar xvpf archive.aes --use-compress-program=bz2aespipe


3.2. Example 2 - Encrypted archive with gpg-encrypted key file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create 65 random encryption keys and encrypt those keys using gpg. Reading
from /dev/random may take indefinitely long if kernel's random entropy pool
is empty. If that happens, do some other work on some other console (use
keyboard, mouse and disks). Use of gpg-encrypted key file depends on
encrypted swap.

    head -c 3705 /dev/random | uuencode -m - | head -n 66 | tail -n 65 \
        | gpg --symmetric -a >mykey1.gpg

Write files to bzip2 compressed, encrypted tar archive. aespipe asks for
passphrase to decrypt the key file.

    tar cvf - files... | bzip2 | aespipe -w 10 -K mykey1.gpg >archive.aes

Restore files from bzip2 compressed, encrypted tar archive. aespipe asks for
passphrase to decrypt the key file.

    aespipe -d -K mykey1.gpg <archive.aes | bzip2 -d -q | tar xvpf -


3.3. Example 3 - Encrypted CD-ROM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create 65 random encryption keys and encrypt those keys using gpg. Reading
from /dev/random may take indefinitely long if kernel's random entropy pool
is empty. If that happens, do some other work on some other console (use
keyboard, mouse and disks). Use of gpg encrypted key file depends on
encrypted swap.

gpg encrypted key file is recorded to first 8192 bytes of the CD-ROM. Key
file does not use all of 8192 bytes so remaining part of the 8192 bytes is
padded with newlines.

    yes "" | dd of=image.iso bs=512 count=16
    head -c 3705 /dev/random | uuencode -m - | head -n 66 | tail -n 65 \
        | gpg --symmetric -a | dd of=image.iso conv=notrunc

Create encrypted ISO9660 CD-ROM image that can be mounted using Linux
loop-AES crypto package version 3.0a or later:

    mkisofs -quiet -r directory-tree | aespipe -K image.iso -O 16 >>image.iso

This image file can then be mounted under Linux like this:

    mount -t iso9660 image.iso /cdrom -o loop=/dev/loop0,encryption=AES128,gpgkey=image.iso,offset=8192

Or, after writing image.iso to CD-ROM, like this:

    mount -t iso9660 /dev/cdrom /cdrom -o loop=/dev/loop0,encryption=AES128,gpgkey=/dev/cdrom,offset=8192

Or, if this line is added to /etc/fstab file:

 /dev/cdrom /cryptcd iso9660 defaults,noauto,loop=/dev/loop0,encryption=AES128,gpgkey=/dev/cdrom,offset=8192 0 0

Then encrypted CD-ROMs can be mounted and unmounted like this:

    mkdir /cryptcd
    mount /cryptcd
    umount /cryptcd

In above mount cases the mounted device name must be identical to gpgkey=
definition and offset= must be specified. That condition is special cased
inside mount and losetup programs to prevent gpg from reading all of cdrom
contents when gpg is decrypting the key file.

If you ever need to extract unencrypted image of encrypted CD-ROM, you can
do that like this:

    dd if=/dev/cdrom bs=8192 count=1 of=key.gpg
    dd if=/dev/cdrom bs=8192 skip=1 | aespipe -d -K key.gpg -O 16 >clear.iso

Latter of above dd commands may cause some kernel error messages when dd
command attempts to read past end of CD-ROM device.


3.4. Example 4 - Adding encryption to existing file system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create 65 random encryption keys and encrypt those keys using gpg. Reading
from /dev/random may take indefinitely long if kernel's random entropy pool
is empty. If that happens, do some other work on some other console (use
keyboard, mouse and disks). Use of gpg-encrypted key file depends on
encrypted swap.

    umask 077
    head -c 3705 /dev/random | uuencode -m - | head -n 66 | tail -n 65 \
        | gpg --symmetric -a >/etc/fskey1.gpg

Add loop-AES (v3.0a or later) compatible encryption to 1.44 MB floppy disk:

    dd if=/dev/fd0 bs=64k | aespipe -K /etc/fskey1.gpg | dd of=/dev/fd0 bs=64k conv=notrunc

Encrypted floppy can be mounted and unmounted under Linux like this:

    mount -t ext2 /dev/fd0 /floppy -o loop=/dev/loop1,encryption=AES128,gpgkey=/etc/fskey1.gpg
    umount /floppy

Remove encryption from loop-AES encrypted 1.44 MB floppy disk:

    dd if=/dev/fd0 bs=64k | aespipe -d -K /etc/fskey1.gpg | dd of=/dev/fd0 bs=64k conv=notrunc


4. Files
~~~~~~~~
ChangeLog       History of changes and public releases.

Makefile.in     Source for generated Makefile. configure script reads this
                and creates Makefile.

README          This README file.

aes-GPL.diff    A patch for aes-amd64.S and aes-x86.S files that updates
                licenses to be fully GPL compatible. aes-amd64.S and
                aes-x86.S files are derived from Brian Gladman's December
                2001 published version that had no mention of GPL, but both
                Brian Gladman and Jari Ruusu permit this license change.

aes-amd64.S     Optimized assembler implementation of AES cipher for AMD64
                and compatible processors.

aes-intel*.S    Optimized assembler implementation of AES cipher using Intel
                hardware AES instructions for x86 processors in 32 bit or 64
                bit mode.

aes-x86.S       Optimized assembler implementation of AES cipher for x86
                processors.

aes.[ch]        AES encryption functions, portable and usable in Linux
                kernel and in user space, as well as in other operating
                systems.

aespipe.1       Man page for aespipe.

aespipe.c       Main aespipe source that calls cipher and hash functions in
                aes.c/aes-*.S md5.c/md5-*.S sha512.c rmd160.c files.

bz2aespipe      Example script to be used as GNU tar 'compress' program.
                This script both compresses and encrypts the archive. Edit
                default options in the script and install it somewhere in
                your path, /usr/local/bin/ for example.

configure       Script to create Makefile.

configure.ac    Source for configure script.

gpgkey[123].asc gpg encrypted key files that are used by Makefile when "make
                tests" command is run. These key files are encrypted with
                symmetric cipher using 12345678901234567890 password.

md5-2x-amd64.S  Optimized assembler implementation of MD5 transform function
                for AMD64 and compatible processors. Does two transforms
                simultaneously.

md5-amd64.S     Optimized assembler implementation of MD5 transform function
                for AMD64 and compatible processors.

md5-x86.S       Optimized assembler implementation of MD5 transform function
                for x86 processors.

md5.[ch]        MD5 transform function implementation that is used to
                compute IVs. This source code was copied from Linux kernel
                CryptoAPI implementation.

rmd160.[ch]     Implementation of RIPE-MD160. This source code was copied
                from GnuPG.

sha512.[ch]     Implementation of SHA-256, SHA-384, and SHA-512.


5. Credits
~~~~~~~~~~
This package uses AES cipher sources that were originally written by
Dr Brian Gladman:

// Copyright (c) 2001, Dr Brian Gladman <brg@gladman.uk.net>, Worcester, UK.
// All rights reserved.
//
// TERMS
//
//  Redistribution and use in source and binary forms, with or without
//  modification, are permitted subject to the following conditions:
//
//  1. Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
//
//  2. Redistributions in binary form must reproduce the above copyright
//     notice, this list of conditions and the following disclaimer in the
//     documentation and/or other materials provided with the distribution.
//
//  3. The copyright holder's name must not be used to endorse or promote
//     any products derived from this software without his specific prior
//     written permission.
//
//  This software is provided 'as is' with no express or implied warranties
//  of correctness or fitness for purpose.