Written by Jari Ruusu , October 23 2023 Copyright 2002-2023 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: https://loop-aes.sourceforge.net/ https://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. Example: CFLAGS="-O2 -Wall" LDFLAGS="" ./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 >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 , 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.