Prototype enduser documentation If you open a file which was encrypted by this program, you'll be prompted to supply a passphrase. This passphrase becomes the default to be used when saving files. The passphrase is not the actual encryption key, but is used to generate a 256 bit encryption key called the file key. Master Keys An Encrypted file can optionally contain a copy of its own file key, encrypted with a master key, derived from a master passphrase. This allows anyone who knows the master passphrase to decode any file encrypted with any file key which uses this master key structure. As long as the file passphrase is not changed, the master key can be propogated to new versions of the file without typing the master phrase again. Why use a master key? #1) Data recovery. It is not generally a good idea to use the same passphrase for all files, or to continue using the same passphrase forever. The principle hazard is that if even one key is revealed, every encrypted file you have ever created can also be read. Consequently, different keys should be used for different files, and over time, those keys should change. Since the keys change, they are subject to being lost or forgotton, resulting in lost data - it's still there, but no one can decode it. If you use a master key, and you have misplaced the file key, you can still recover your data. Since master key is not routinely used to decrypt the file, and never needs to be shared with anyone, is is much less likely to be compromised, so it is reasonable for a good master key to be used for a very long time in a lot of different files. Recommendation: Use a master passphrase that will be very hard for anyone to guess and very hard for you to forget. For example: "My Favorite movie is Gone with the Wind" "When it rains in New York, even Chicago is a better place to be" Never tell anyone what it is or write it down. It's an EMERGENCY measure to prevent catastrophic data loss, so treat it that way. Never use it to read or open any encrypted file except for testing, or if you have really lost the file passphrase. #2) Trapdoor access. Sometimes it is desirable to allow a second party to decode the file without knowing the encryption passphrase - a good example is where an automated program is intended to read an encrypted file that is prepared by a human. The program has to have the passphrase or the key embedded in it somewhere. It's possible for a dedicated attacker to find it, but it's much more likely that the source of compromise will be clumsy humans. Allowing the program to use the master key and humans to use the ordinary file keys will allow the routine-use keys to be changed as often as necesary, while still letting the program read the files without being told the new key. Technical Details: Passphrase Management: 256 bit encryption keys are geneated from ascii passphrases by passing the passphrase through a SHA256 hash. Passphrases are never Stored anywhere except in the dynamic memory of the encrypting program. Key management over file generations: If the file is opened using a file passphrase, the passphrase is retained and used as the default for the passphrase dialog. If the file is opened using a master passphrase, the recovered file key is used as the default encryption for new files. This allows an editor who does not know the file passphrase to propogate a file key he could not create. If the file contains a master key, and neither the file or master passphrase is changed, then the retained, master-encrypted file key is copied into the next file generation. (It is still valid). This allows an editor who knows only the file passphrase to propogate a master key he could not create. Encrypted files start with an 8 byte preable, the first 4 bytes are a "magic number" to identify the file type (currently 0x04030201) and a 4 byte subfile type, (currently either 0x00000001 or 0x00000002) The next 16 bytes are the initialization vector for the AES engine, to be used with the file key. Each file gets a unique 16 bytes of pseudorandom noise. Next, for master keyed files, is a 16 byte IV for the master key, followed by a 32 byte block containing the file key, encrypted with the master key, using the master key IV and CBC block chaining. Next, is the actual file data, encrypted using the file key and the IV, and CBC block chaining. Finally, are 1-16 bytes of padding to round out the AES block. Note that there are never 0 bytes of padding. A Word about pass phrases and overall security. While this encryption scheme uses high quality AES encryption and quite long 256 bit keys, that is almost irrelevant to the overall security of the system. It's like having a very expensive lock on your front door. Thieves won't go to great lengths to pick your lock; they will simply break a window instead. The weak link in this encryption scheme is YOU and your selection of pass phrases. If your encrypted files are compromised, the most likely, by far, method is the simplest; (1) they ask, you tell. or (2) they find the scrap of paper where you wrote the passphrase or (3) some key logger watches you type the passphrase. The only other likely method is a dictionary-type attack using a program to try lots of possible passphrases. Any short, word-like passphrase CAN be compromised using a few days of computer time. Finally, consider the suitablility of this encryption scheme for your purpose. If your goal is to prevent your wife from reading your girlfriend's phone number in your address book: definitely. If your goal is to prevent disclosure of sensitive data if your laptop is stolen: most likely. If your goal is to prevent fishing by the IRS, should they ever become curious about you: don't count on it. They'll throw you in jail until you tell them the password, or install a key logger and wait for you to tell them voluntarily. If your goal is to keep secrets people who are definitely out to get you, and are willing to shove bamboo splints under you fingernails until you talk: don't even think about it.