Notepad3/Build/Docs/crypto/encryption-doc.txt

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.