diff options
| -rw-r--r-- | README.md | 54 | ||||
| -rw-r--r-- | test/README.md | 39 | ||||
| -rw-r--r-- | utils/README.md | 36 |
3 files changed, 68 insertions, 61 deletions
@@ -2,57 +2,67 @@ Simple AES implementation and utilities. -## Building +## Development -To build the project: +### Prerequisites -1. generate the solution aes_tools.sln using CMake, -2. build the solution using Visual Studio. +* Boost.Filesystem, Boost.Program_options and Boost.System -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: +### Building the utilities - > cmake -D BOOST_ROOT=C:\workspace\third-party\boost_1_58_0 ... +Create the build files using CMake and build using your native build tools +(Visual Studio/make/etc.). -Remember that in order to link to the static Boost libraries, you also have to -pass `-D Boost_USE_STATIC_LIBS=ON` to CMake. +For example, using Visual Studio 2013 Update 4 for Windows Desktop (targetting +x86 and using static Boost libraries): + + > cd + C:\workspace\personal\build\aes-tools + + > cmake -G "Visual Studio 12 2013" ^ + -D BOOST_ROOT=C:\workspace\third-party\boost_1_58_0 ^ + -D Boost_USE_STATIC_LIBS=ON ^ + C:\workspace\personal\aes-tools + ... + + > msbuild aes-tools.sln + ... ## 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, you can use [Intel Software Development -Emulator]. +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 +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 +[Intel Software Development Emulator]: https://software.intel.com/en-us/articles/intel-software-development-emulator + ## Documentation You can generate the docs using [Doxygen]. -The docs will be put to the `doc/` directory under the project's root. +The docs will be generated in the "doc/" directory under the project's root. + +[Doxygen]: http://www.stack.nl/~dimitri/doxygen/ ## Utilities See [Utilities]. +[Utilities]: utils/README.md + ## Testing See [Testing]. +[Testing]: test/README.md + ## 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. - - [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 6d7cc8b..db7a418 100644 --- a/test/README.md +++ b/test/README.md @@ -1,16 +1,21 @@ # 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 +an arbitrary set of inputs (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 + ## Manual testing 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. +Pass the `--help` flag to examine the utility's usage info. > encrypt_block.exe -a aes128 -m ecb -- 000102030405060708090a0b0c0d0e0f 00112233445566778899aabbccddeeff 69c4e0d86a7b0430d8cdb78070b4c55a @@ -26,7 +31,7 @@ Pass the `--help` parameter to examine the utility's usage info. A number of test vectors have been collected from various AES validation programs/reference implementations. -The test scripts are written in Python 3 and are used in similar fashion: +The test scripts are used in similar fashion: * they accept the path to the directory with the block encryption/decryption utilities, @@ -46,6 +51,10 @@ 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. +### Prerequisites + +* Python (3.4 or higher) + ### NIST Special Publication 800-38A To validate the implementation using the inputs from [NIST SP 800-38A], use @@ -53,13 +62,17 @@ To validate the implementation using the inputs from [NIST SP 800-38A], use > nist-sp-800-38a.py -p C:\workspace\personal\build\aes-tools\utils\Debug +[NIST SP 800-38A]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf + ### Cryptographic Algorithm Validation Program To validate the implementation using the inputs from [CAVP], use `cavp.py`. > 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`. +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 @@ -67,22 +80,14 @@ You can also test file encryption using `file.py`. 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). +a separate directory ("file/" by default). ## See also -* [Building] +* [Building the utilities] * [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/ +[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 312c754..6bf52f6 100644 --- a/utils/README.md +++ b/utils/README.md @@ -1,21 +1,15 @@ # Utilities -A couple of useful utilities built on top of the library. +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. -The included utilities are: - -* [block encryption] utilities, -* [file encryption] utilities, -* and [bitmap encryption] utilities. - ## Block encryption 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. +They are primarily intended for debugging purposes. +Enable verbose output by passing the `--verbose` flag. Please note that verbose output can only be produced when *not* using the "boxes" interface (the `--use-boxes` flag). @@ -136,30 +130,28 @@ 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 + ### 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_file.exe]: #encrypt_fileexe + ### 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_file.exe]: #decrypt_fileexe + ## See also -* [Building] +* [Building the utilities] * [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 +[Building the utilities]: ../README.md#building-the-utilities +[License]: ../README.md#license |