diff options
| -rw-r--r-- | README.md | 41 | ||||
| -rw-r--r-- | test/README.md | 90 | ||||
| -rw-r--r-- | utils/README.md | 59 |
3 files changed, 108 insertions, 82 deletions
@@ -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 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 |