aboutsummaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
authorEgor Tensin <Egor.Tensin@gmail.com>2016-05-22 01:47:56 +0300
committerEgor Tensin <Egor.Tensin@gmail.com>2016-05-22 01:47:56 +0300
commit308f9139bd358bd094ec9623f6e2bd3c16799594 (patch)
tree44408a2aaa346ab96241d5868bb0eeb888c633a0
parentREADME updates (diff)
downloadaes-tools-308f9139bd358bd094ec9623f6e2bd3c16799594.tar.gz
aes-tools-308f9139bd358bd094ec9623f6e2bd3c16799594.zip
README updates
Diffstat (limited to '')
-rw-r--r--README.md54
-rw-r--r--test/README.md39
-rw-r--r--utils/README.md36
3 files changed, 68 insertions, 61 deletions
diff --git a/README.md b/README.md
index 7177ea0..c0f85a5 100644
--- a/README.md
+++ b/README.md
@@ -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