README updates

3 files changed, 108 insertions, 82 deletions

diff --git a/README.md b/README.md
index 1365397..7177ea0 100644
--- a/README.md
+++ b/README.md
@@ -4,14 +4,14 @@ Simple AES implementation and utilities.
 
 ## Building
 
-I've used the compiler and the assembler shipped with Visual Studio Express
-2013 with Update 4 for Windows Desktop.
+To build the project:
 
-You can generate the solution using CMake and build it using Visual Studio.
+1. generate the solution aes_tools.sln using CMake,
+2. build the solution using Visual Studio.
 
-Some of the utilities also depend on a few Boost libraries.
-In particular, Boost.Filesystem, Boost.Program\_options, and Boost.System has
-to be built prior to building these utilities.
+Some of the [utilities] also depend on a few Boost libraries.
+In particular, Boost.Filesystem, Boost.Program\_options, and Boost.System must
+be built prior to building these utilities.
 To enable CMake to find Boost libraries, pass the path to the root Boost
 directory like this:
 
@@ -20,32 +20,39 @@ directory like this:
 Remember that in order to link to the static Boost libraries, you also have to
 pass `-D Boost_USE_STATIC_LIBS=ON` to CMake.
 
-## Running on older CPUs
+## Usage on older CPUs
 
 To run the executables that are using the AES-NI instruction set on a CPU w/o
-the support for these instructions, one can use
-[Intel Software Development Emulator](https://software.intel.com/en-us/articles/intel-software-development-emulator).
-You can then run an executable like this:
+the support for these instructions, you can use [Intel Software Development
+Emulator].
+After you install the emulator, you can run an executable like this:
 
     > sde -- encrypt_block.exe -a aes128 -m ecb -- 000102030405060708090a0b0c0d0e0f 00112233445566778899aabbccddeeff
     69c4e0d86a7b0430d8cdb78070b4c55a
 
 ## Documentation
 
-You can generate the docs using
-[Doxygen](http://www.stack.nl/~dimitri/doxygen/).
-The docs will be put into the `doc` directory in the repository's root.
+You can generate the docs using [Doxygen].
+The docs will be put to the `doc/` directory under the project's root.
 
 ## Utilities
 
-See [Utilities](utils#utilities).
+See [Utilities].
 
 ## Testing
 
-See [Testing](test#testing).
+See [Testing].
 
-## Licensing
+## License
 
 This project, including all of the files and their contents, is licensed under
 the terms of the MIT License.
-See LICENSE.txt for details.
+See [LICENSE.txt] for details.
+
+
+
+[LICENSE.txt]: LICENSE.txt
+[Doxygen]: http://www.stack.nl/~dimitri/doxygen/
+[Intel Software Development Emulator]: https://software.intel.com/en-us/articles/intel-software-development-emulator
+[testing]: test/README.md
+[utilities]: utils/README.md
diff --git a/test/README.md b/test/README.md
index 8843066..6d7cc8b 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,76 +1,88 @@
 # Testing
 
-After you've [built](../README.md#building) the utilities, you can verify the
-implementation either [manually](#manually) or
-[automatically](#using-test-vectors) using test vectors.
+Using the [utilities], you can validate the implementation either by providing
+an arbitrary set of inputs (see [manual testing]) or by using the test vectors
+provided by various AES [validation programs].
 
-Using the built utilities, you can also test
-[file encryption](#file-encryption).
+You can also test that [file encryption] works (at least to some extent).
 
-## Manually
+## Manual testing
 
-You can test the implementation using the block encryption/decryption utilities
-`encrypt_block.exe` and `decrypt_block.exe`.
-Use the `--help` option to examine the usage info of a utility.
-
-File encryption
-
-For example, for AES-128 in ECB mode:
+You can validate the implementation manually using the block
+encryption/decryption utilities `encrypt_block.exe` and `decrypt_block.exe`.
+Pass the `--help` parameter to examine the utility's usage info.
 
     > encrypt_block.exe -a aes128 -m ecb -- 000102030405060708090a0b0c0d0e0f 00112233445566778899aabbccddeeff
     69c4e0d86a7b0430d8cdb78070b4c55a
 
-and for AES-192 in CBC mode:
-
     > decrypt_block.exe -a aes192 -m cbc -- 8e73b0f7da0e6452c810f32b809079e562f8ead2522c6b7b 000102030405060708090a0b0c0d0e0f 4f021db243bc633d7178183a9fa071e8 b4d9ada9ad7dedf4e5e738763f69145a 571b242012fb7ae07fa9baac3df102e0 08b0e27988598881d920a9e64f5615cd
     6bc1bee22e409f96e93d7e117393172a
     ae2d8a571e03ac9c9eb76fac45af8e51
     30c81c46a35ce411e5fbc1191a0a52ef
     f69f2445df4f9b17ad2b417be66c3710
 
-On older CPUs, you can run the utilities
-[using Intel SDE](../README.md#running-on-older-cpus).
+## Validation programs
+
+A number of test vectors have been collected from various AES validation
+programs/reference implementations.
 
-## Using test vectors
+The test scripts are written in Python 3 and are used in similar fashion:
 
-The test scripts are written in Python 3 and have uniform interfaces: they
-accept a path to the directory with the block encryption/decryption utilities
-and allow to run them [using Intel SDE](../README.md#running-on-older-cpus).
-They also write log files with a short summary at the end.
-In general, each scripts counts the number of tests that failed, succeeded,
-caused an error, and the tests that were skipped.
+* they accept the path to the directory with the block encryption/decryption
+  utilities,
+* they produce log files with short summaries at the end.
+
+In general, each of the scripts counts the number of tests that have failed,
+succeeded, ended with an error, and were skipped.
 You must therefore make sure that
 
-* no errors occured while running the tests,
-* all the tests succeeded,
+* no errors occured while running the script,
+* all the tests succeeded except for those that were skipped,
 * and the skipped tests were skipped for a good reason.
 
-To pass a path to the directory with the required utilities, use the `--path`
+To pass the path of the directory with the required utilities, use the `--path`
+parameter.
+To allow the utilities to be executed on older CPUs, pass the `--sde`
 parameter.
-To make scripts run the utilities using Intel SDE, pass `--sde`.
-Use `--help` to see the script's usage details.
+Pass the `--help` parameter to see examine the script's usage info.
 
 ### NIST Special Publication 800-38A
 
-To test the implementation against the vectors from
-[NIST SP 800-38A](http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf),
-use `nist-sp-800-32a.py`.
+To validate the implementation using the inputs from [NIST SP 800-38A], use
+`nist-sp-800-32a.py`:
 
-    > nist-sp-800-38a.py -p C:\build\utils\Debug
+    > nist-sp-800-38a.py -p C:\workspace\personal\build\aes-tools\utils\Debug
 
 ### Cryptographic Algorithm Validation Program
 
-To test the implementation against the vectors from
-[CAVP](http://csrc.nist.gov/groups/STM/cavp/), use `cavp.py`.
-The AES Known Answer Test (KAT) Vectors are used and read from `KAT_AES.zip`.
+To validate the implementation using the inputs from [CAVP], use `cavp.py`.
 
-    > cavp.py -p C:\build\utils\Debug
+    > cavp.py -p C:\workspace\personal\build\aes-tools\utils\Debug
+
+The AES Known Answer Test (KAT) Vectors are used and read from `KAT_AES.zip`.
 
 ## File encryption
 
 You can also test file encryption using `file.py`.
-Its interface and output is similar to the
-[block encryption](#using-test-vectors) test scripts.
+Its interface and output is similar to the [validation programs] test scripts.
 The expected ciphertexts (for encryption) and plaintexts (for decryption),
 along with the keys and initialization vectors, are stored in the files under
 a separate directory (`file/` by default).
+
+## See also
+
+* [Building]
+* [Usage on older CPUs]
+* [License]
+
+
+
+[building]: ../README.md#building
+[license]: ../README.md#license
+[usage on older cpus]: ../README.md#usage-on-older-cpus
+[utilities]: ../utils/README.md
+[manual testing]: #manual-testing
+[validation programs]: #validation-programs
+[file encryption]: #file-encryption
+[NIST SP 800-38A]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+[CAVP]: http://csrc.nist.gov/groups/STM/cavp/
diff --git a/utils/README.md b/utils/README.md
index a1cfeb5..312c754 100644
--- a/utils/README.md
+++ b/utils/README.md
@@ -1,24 +1,21 @@
 # Utilities
 
-Here are a couple of useful utilities built on top of the library.
+A couple of useful utilities built on top of the library.
 Each of the utilities accepts the `--help` flag, which can be used to examine
-utility's usage info.
+the utility's usage info.
 
 The included utilities are:
 
-* [block encryption](#block-encryption) utilities,
-* [file encryption](#file-encryption) utilities,
-* and [bitmap encryption](#bitmap-encryption) utilities.
-
-On older CPUs, you can run the utilities
-[using Intel SDE](../README.md#running-on-older-cpus).
+* [block encryption] utilities,
+* [file encryption] utilities,
+* and [bitmap encryption] utilities.
 
 ## Block encryption
 
-The block encryption utilities can produce verbose human-readable output,
-including round keys, intermediate initialization vector values, etc.
-This is primarily intended for debugging purposes.
-Enable verbose output by passing the `--verbose` flag to the utilities.
+Block encryption utilities can produce verbose human-readable output, including
+round keys, intermediate initialization vector values, etc.
+Those are primarily intended for debugging purposes.
+Enable verbose output by passing the `--verbose` flag to a utilities.
 Please note that verbose output can only be produced when *not* using the
 "boxes" interface (the `--use-boxes` flag).
 
@@ -27,8 +24,6 @@ Please note that verbose output can only be produced when *not* using the
 Encrypts blocks using the selected algorithm in the specified mode of
 operation.
 
-#### Usage examples
-
 For example, to encrypt
 
 * the plaintext block `0x00112233445566778899aabbccddeeff`
@@ -55,8 +50,6 @@ run:
 Decrypts blocks using the selected algorithm in the specified mode of
 operation.
 
-#### Usage examples
-
 For example, to decrypt
 
 * the ciphertext block `0x69c4e0d86a7b0430d8cdb78070b4c55a`
@@ -85,9 +78,7 @@ run:
 Encrypts a file using the selected algorithm in the specified mode of
 operation.
 
-#### Usage examples
-
-For example, to encrypt the plaintext `input.txt`
+For example, to encrypt the plaintext from `input.txt`
 
 * using AES-128 in ECB mode
 * with key `0x11111111111111111111111111111111`
@@ -113,8 +104,6 @@ run
 Decrypts a file using the selected algorithm in the specified mode of
 operation.
 
-#### Usage examples
-
 To decrypt the ciphertext from `input.txt`
 
 * using AES-128 in ECB mode
@@ -143,16 +132,34 @@ ECB mode (namely, the fact that identical plaintext blocks get mapped to
 identical ciphertext blocks).
 This can be explicitly shown using 8-bit-per-pixel bitmaps:
 
-Plaintext BMP | Encrypted in ECB mode | Encrypted in CBC mode
-------------- | --------------------- | ---------------------
-![Plaintext butterfly](bmp/butterfly.bmp?raw=true) | ![Ciphertext butterfly in ECB mode](bmp/cipherfly_ecb.bmp?raw=true) | ![Ciphertext butterfly in CBC mode](bmp/cipherfly_cbc.bmp?raw=true)
+Plaintext BMP    | Encrypted in ECB mode | Encrypted in CBC mode
+---------------- | --------------------- | ---------------------
+![butterfly.bmp] | ![cipherfly_ecb.bmp]  | ![cipherfly_cbc.bmp]
 
 ### encrypt_bmp.exe
 
 Encrypts the pixels in a BMP image file, preserving the header.
-The usage is the same as for [encrypt_file.exe](#encrypt_fileexe).
+The usage is the same as for [encrypt_file.exe].
 
 ### decrypt_bmp.exe
 
 Decrypts the pixels in a BMP image file, preserving the header.
-The usage is the same as for [decrypt_file.exe](#decrypt_fileexe).
+The usage is the same as for [decrypt_file.exe].
+
+## See also
+
+* [Building]
+* [License]
+
+
+
+[building]: ../README.md#building
+[license]: ../README.md#license
+[block encryption]: #block-encryption
+[file encryption]: #file-encryption
+[bitmap encryption]: #bitmap-encryption
+[encrypt_file.exe]: #encrypt_fileexe
+[decrypt_file.exe]: #decrypt_fileexe
+[butterfly.bmp]: bmp/butterfly.bmp?raw=true
+[cipherfly_ecb.bmp]: bmp/cipherfly_ecb.bmp?raw=true
+[cipherfly_cbc.bmp]: bmp/cipherfly_cbc.bmp?raw=true