README

AESKeyFinder 1.0 (2008-07-18)
By Nadia Heninger and Ariel Feldman

This program illustrates automatic techniques for locating 128-bit and
256-bit AES keys in a captured memory image, as described in Section
6.1 of the research paper:

  J. A. Halderman, S. D. Schoen, N. Heninger, W. Clarkson, W. Paul,
  J. A. Calandrino, A. J. Feldman, J. Appelbaum, and E. W. Felten.
  "Lest We Remember: Cold-Boot Attacks on Encryption Keys."
  Proc. 17th USENIX Security Symposium (Sec '08), San Jose, CA, July 2008.

For more information, see: http://citp.princeton.edu/memory/


The program uses the following algorithm:

1. Iterate through each byte of the memory image.  Treat the following block of 
   176 or 240 bytes as an AES key schedule.

2. For each word in the potential key schedule, calculate the Hamming
   distance from that word to the key schedule word that should have
   been generated from the surrounding words.

3. If the total number of bits violating the constraints on a correct
   AES key schedule is sufficiently small, output the key.

For efficiency, it also performs a simple entropy test to filter out
blocks that are not keys.  It counts the number of repeated bytes and
skips blocks that have too many repeats.

This method works even if several bits of the key schedule have been
corrupted due to memory decay.

This modified version of the original AESKeyFinder can additionally
find key schedules whose entries are in reverse order or which have
had InvMixColumn pre-applied for use by decryption code that uses
this optimisation. (Currently only implemented for 128-bit keys.)

USAGE:

  aeskeyfind [OPTION]... MEMORY-IMAGE

Options:

  -v            verbose output -- prints the extended keys and the 
                  constraints on the rows of the key schedule
  -q            don't display a progress bar
  -t THRESHOLD  sets the maximum number of bit errors allowed in a
                  candidate key schedule
  -h            displays usage help