diff options
| -rw-r--r-- | README.md | 38 | ||||
| -rw-r--r-- | test/README.md | 39 | ||||
| -rw-r--r-- | utils/README.md | 25 |
3 files changed, 59 insertions, 43 deletions
@@ -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 |