diff options
| -rw-r--r-- | README.md | 26 | ||||
| -rw-r--r-- | test/README.md | 27 | ||||
| -rw-r--r-- | utils/README.md | 17 |
3 files changed, 47 insertions, 23 deletions
@@ -1,24 +1,30 @@ # aesni -Simple AES encryption algorithm implementation using the AES-NI instruction set. +Simple AES encryption algorithm implementation using the AES-NI instruction +set. ## Building -I've used the compiler and the assembler shipped with Visual Studio Express 2013 with Update 4 for Windows Desktop. +I've used the compiler and the assembler shipped with Visual Studio Express +2013 with Update 4 for Windows Desktop. You can generate the solution using CMake and build it using Visual Studio. Some of the utilities also depend on a few Boost libraries. -In particular, Boost.ProgramOptions has to be built prior to building these utilities. -To enable CMake to find Boost libraries, pass the path to the root Boost directory like this: +In particular, Boost.ProgramOptions has to be built prior to building these +utilities. +To enable CMake to find Boost libraries, pass the path to the root Boost +directory like this: cmake -D BOOST_ROOT=C:\workspace\third-party\boost_1_58_0 ... -Remember that in order to link to the static Boost libraries, you also have to pass `-D Boost_USE_STATIC_LIBS=ON` to CMake. +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 -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 +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: @@ -27,7 +33,8 @@ You can then run an executable like this: ## Documentation -You can generate the docs using [Doxygen](http://www.stack.nl/~dimitri/doxygen/). +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. ## Utilities @@ -40,5 +47,6 @@ See [Testing](test#testing). ## Licensing -This project, including all of the files and their contents, is licensed under the terms of the MIT License. -See LICENSE.txt for details. +This project, including all of the files and their contents, is licensed under +the terms of the MIT License. +See [LICENSE.txt](LICENSE.txt) for details. diff --git a/test/README.md b/test/README.md index 0192a64..b36db98 100644 --- a/test/README.md +++ b/test/README.md @@ -1,10 +1,13 @@ # Testing -After you've [built](../#building) the block encryption/decryption utilities, you can verify the implementation either [manually](#manually) or [automatically](#using-test-vectors) using test vectors. +After you've [built](../#building) the block encryption/decryption utilities, +you can verify the implementation either [manually](#manually) or +[automatically](#using-test-vectors) using test vectors. ## Manually -You can test the AES implementation using the block encryption/decryption utilities `aes_encrypt_block.exe` and `aes_decrypt_block.exe`. +You can test the AES implementation using the block encryption/decryption +utilities `aes_encrypt_block.exe` and `aes_decrypt_block.exe`. Use the `--help` option to examine the usage info of a utility. For example, for AES-128 in ECB mode: @@ -20,32 +23,40 @@ and for AES-192 in CBC mode: 30c81c46a35ce411e5fbc1191a0a52ef f69f2445df4f9b17ad2b417be66c3710 -On older CPUs, you can run the utilities [using Intel SDE](../README.md#running-on-older-cpus). +On older CPUs, you can run the utilities +[using Intel SDE](../README.md#running-on-older-cpus). ## Using test vectors -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](https://github.com/egor-tensin/aesni#running-on-older-cpus). +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. +In general, each scripts counts the number of tests that failed, succeeded, +caused an error, and the tests that were skipped. You must therefore make sure that * no errors occured while running the tests, * all the tests succeeded, * and the skipped tests were skipped for a good reason. -To pass a path to the directory with the required utilities, use the `--path` parameter. +To pass a path to the directory with the required utilities, use the `--path` +parameter. To make scripts run the utilities using Intel SDE, pass `--sde`. Use `--help` to see the script's usage details. ### 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) using `nist-sp-800-32a.py`. +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`. python nist-sp-800-38a.py -p C:\build\utils\Debug ### Cryptographic Algorithm Validation Program -To test the implementation against the vectors from [CAVP](http://csrc.nist.gov/groups/STM/cavp/) using `cavp.py`. +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`. python cavp.py -p C:\build\utils\Debug diff --git a/utils/README.md b/utils/README.md index 29c5abc..61204c6 100644 --- a/utils/README.md +++ b/utils/README.md @@ -1,7 +1,8 @@ # Utilities Here are 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. +Each of the utilities accepts the `--help` flag, which can be used to examine +utility's usage info. The included utilities are: @@ -9,13 +10,15 @@ The included utilities are: * [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). +On older CPUs, you can run the utilities +[using Intel SDE](../README.md#running-on-older-cpus). ## Block encryption ### aes_encrypt_block.exe -Encrypts 16-byte blocks using AES-128/192/256 in the specified mode of operation. +Encrypts 16-byte blocks using AES-128/192/256 in the specified mode of +operation. #### Usage examples @@ -42,7 +45,8 @@ run: ### aes_decrypt_block.exe -Decrypts 16-byte blocks using AES-128/192/256 in the specified mode of operation. +Decrypts 16-byte blocks using AES-128/192/256 in the specified mode of +operation. #### Usage examples @@ -125,8 +129,9 @@ run ## 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 identical ciphertext blocks). +These utilities were developed primarily to demonstrate the drawbacks of using +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 |