aboutsummaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
authorEgor Tensin <Egor.Tensin@gmail.com>2016-06-21 19:53:05 +0300
committerEgor Tensin <Egor.Tensin@gmail.com>2016-06-21 19:53:05 +0300
commit376f911b4c5ca7bcdfc25142660d8ce23d2dfd8e (patch)
tree65e71c5593de416498b265b3e46cfbcdafd51b03
parenttest: fix Pylint warnings (diff)
downloadaes-tools-376f911b4c5ca7bcdfc25142660d8ce23d2dfd8e.tar.gz
aes-tools-376f911b4c5ca7bcdfc25142660d8ce23d2dfd8e.zip
README updates
-rw-r--r--README.md38
-rw-r--r--test/README.md39
-rw-r--r--utils/README.md25
3 files changed, 59 insertions, 43 deletions
diff --git a/README.md b/README.md
index c0f85a5..f303794 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,22 @@
-# AES tools
+AES tools
+=========
Simple AES implementation and utilities.
-## Development
+Development
+-----------
### Prerequisites
-* Boost.Filesystem, Boost.Program_options and Boost.System
+To build the whole solution, you first need to build a few of Boost's
+libraries.
+The complete list of Boost dependencies is:
-### Building the utilities
+* Boost.Filesystem,
+* Boost.Program_options,
+* Boost.System.
+
+### Building
Create the build files using CMake and build using your native build tools
(Visual Studio/make/etc.).
@@ -25,10 +33,11 @@ x86 and using static Boost libraries):
C:\workspace\personal\aes-tools
...
- > msbuild aes-tools.sln
+ > msbuild aes_tools.sln
...
-## Usage on older CPUs
+Usage on older CPUs
+-------------------
To run the executables that are using the AES-NI instruction set on a CPU
without the support for these instructions, you can use [Intel Software
@@ -40,26 +49,25 @@ After you install the emulator, you can run an executable like this:
[Intel Software Development Emulator]: https://software.intel.com/en-us/articles/intel-software-development-emulator
-## Documentation
+Documentation
+-------------
You can generate the docs using [Doxygen].
The docs will be generated in the "doc/" directory under the project's root.
[Doxygen]: http://www.stack.nl/~dimitri/doxygen/
-## Utilities
+See also
+--------
-See [Utilities].
+* [Utilities]
+* [Testing]
[Utilities]: utils/README.md
-
-## Testing
-
-See [Testing].
-
[Testing]: test/README.md
-## License
+License
+-------
This project, including all of the files and their contents, is licensed under
the terms of the MIT License.
diff --git a/test/README.md b/test/README.md
index db7a418..0cc74cd 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,17 +1,19 @@
-# Testing
+Testing
+=======
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].
+an arbitrary set of inputs of your choice (see [Manual testing]) or by using
+the test vectors provided by various AES [validation programs].
You can also test that [file encryption] works (at least to some extent).
[utilities]: ../utils/README.md
[Manual testing]: #manual-testing
-[Validation programs]: #validation-programs
-[File encryption]: #file-encryption
+[validation programs]: #validation-programs
+[file encryption]: #file-encryption
-## Manual testing
+Manual testing
+--------------
You can validate the implementation manually using the block
encryption/decryption utilities `encrypt_block.exe` and `decrypt_block.exe`.
@@ -26,15 +28,16 @@ Pass the `--help` flag to examine the utility's usage info.
30c81c46a35ce411e5fbc1191a0a52ef
f69f2445df4f9b17ad2b417be66c3710
-## Validation programs
+Validation programs
+-------------------
A number of test vectors have been collected from various AES validation
programs/reference implementations.
-The test scripts are used in similar fashion:
+The test scripts are written in Python 3 and are used in similar fashion:
* they accept the path to the directory with the block encryption/decryption
- utilities,
+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,
@@ -47,13 +50,12 @@ You must therefore make sure that
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.
-Pass the `--help` parameter to see examine the script's usage info.
+To allow the utilities to run on older CPUs, pass the `--sde` flag.
+Pass the `--help` flag to examine the script's usage info.
### Prerequisites
-* Python (3.4 or higher)
+To run the test scripts, Python 3.4 or higher is required.
### NIST Special Publication 800-38A
@@ -74,20 +76,21 @@ The AES Known Answer Test (KAT) Vectors are used and read from "KAT_AES.zip".
[CAVP]: http://csrc.nist.gov/groups/STM/cavp/
-## File encryption
+File encryption
+---------------
You can also test file encryption using `file.py`.
-Its interface and output is similar to the [validation programs] test scripts.
+Its interface and behaviour are similar to those of 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
+See also
+--------
-* [Building the utilities]
* [Usage on older CPUs]
* [License]
-[Building the utilities]: ../README.md#building-the-utilities
[Usage on older CPUs]: ../README.md#usage-on-older-cpus
[License]: ../README.md#license
diff --git a/utils/README.md b/utils/README.md
index 6bf52f6..08d5847 100644
--- a/utils/README.md
+++ b/utils/README.md
@@ -1,10 +1,12 @@
-# Utilities
+Utilities
+=========
A couple of useful utilities are built on top of the library.
Each of the utilities accepts the `--help` flag, which can be used to examine
the utility's usage info.
-## Block encryption
+Block encryption
+----------------
Block encryption utilities can produce verbose human-readable output, including
round keys, intermediate initialization vector values, etc.
@@ -65,7 +67,8 @@ run:
decrypt_block.exe -a aes192 -m ofb 000102030405060708090a0b0c0d0e0f101112131415161718 22222222222222222222222222222222 bda298884f5c3a9eb7068aa7063a3b75
-## File encryption
+File encryption
+---------------
### encrypt_file.exe
@@ -119,7 +122,8 @@ run
decrypt_file.exe -a aes192 -m ofb -k 111111111111111111111111111111111111111111111111 -v 22222222222222222222222222222222 -i input.txt -o output.txt
-## Bitmap encryption
+Bitmap encryption
+-----------------
These utilities were developed primarily to demonstrate the drawbacks of using
ECB mode (namely, the fact that identical plaintext blocks get mapped to
@@ -130,9 +134,9 @@ Plaintext BMP | Encrypted in ECB mode | Encrypted in CBC mode
---------------- | --------------------- | ---------------------
![butterfly.bmp] | ![cipherfly_ecb.bmp] | ![cipherfly_cbc.bmp]
-[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
+[butterfly.bmp]: bmp/butterfly.bmp
+[cipherfly_ecb.bmp]: bmp/cipherfly_ecb.bmp
+[cipherfly_cbc.bmp]: bmp/cipherfly_cbc.bmp
### encrypt_bmp.exe
@@ -148,10 +152,11 @@ The usage is the same as for [decrypt_file.exe].
[decrypt_file.exe]: #decrypt_fileexe
-## See also
+See also
+--------
-* [Building the utilities]
+* [Usage on older CPUs]
* [License]
-[Building the utilities]: ../README.md#building-the-utilities
+[Usage on older CPUs]: ../README.md#usage-on-older-cpus
[License]: ../README.md#license