From 83614cfda30d32eb6683a8767bf67f08974b5739 Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Wed, 10 Jun 2015 05:42:47 +0300 Subject: README updates --- README.md | 13 +++++------ test/README.md | 72 +++++++++++++++++++++++++--------------------------------- 2 files changed, 37 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 7f4b01e..8a10fb6 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,18 @@ I've used the compiler and the assembler shipped with Visual Studio Express 2013 You can generate the solution using CMake and build it using Visual Studio. -To make AES block I/O functions use big-endian by default (also used in the original FIPS standard; required for the tests), -pass the `LIBAESNI_BE_IO_BY_DEFAULT=1` preprocessor definition. -Using CMake, you can pass the definition like this: - - cmake -D CMAKE_C_FLAGS=/DLIBAESNI_BE_IO_BY_DEFAULT=1 ... - ## Running on older CPUs To run programs 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 a program like this: - sde -- app.exe arg1 arg2... + > sde -- aes128ecb_encrypt_block.exe 000102030405060708090a0b0c0d0e0f 00112233445566778899aabbccddeeff + 69c4e0d86a7b0430d8cdb78070b4c55a + +## Testing + +See [Testing](https://github.com/egor-tensin/aesni/tree/master/test#testing). ## Licensing diff --git a/test/README.md b/test/README.md index 69058be..5bb437a 100644 --- a/test/README.md +++ b/test/README.md @@ -1,27 +1,29 @@ -# Testing the implementation +# Testing -After you've [built](https://github.com/egor-tensin/aesni#building) the basic utilities, -you can verify the implementation either manually or automatically using scripts. +After you've [built](https://github.com/egor-tensin/aesni#building) the block encryption/decryption utilities, you can verify the implementation either manually or automatically using test vectors. ## Manually -The basic utilities have uniform interfaces. -For the ECB mode of operation, the usage is follows: +The block encryption/decryption utilities have uniform interfaces. +For the ECB mode of operation, the usage is: - aesNNNecb_encrypt.exe KEY [PLAIN...] + aesNNNecb_encrypt_block.exe KEY0 [PLAIN0...] [-- KEY1 [PLAIN1...]...] and - aesNNNecb_decrypt.exe KEY [CIPHER...] + aesNNNecb_decrypt_block.exe KEY [CIPHER...] [-- KEY1 [PLAIN1--]...] -For the modes of operation involving initialization vectors (CBC, CFB, OFB, CTR, etc.), -use the utilities like this: +where `NNN` is either `128`, `192` or `256`. - aesNNNxxx_encrypt.exe KEY INIT_VECTOR [PLAIN...] +For the modes of operation involving initialization vectors (CBC, CFB, OFB, CTR, etc.), use the utilities like this: + + aesNNNxxx_encrypt.exe KEY0 IV0 [PLAIN0...] [-- KEY1 IV1 [PLAIN1...]...] and - aesNNNxxx_decrypt.exe KEY INIT_VECTOR [CIPHER...] + aesNNNxxx_decrypt.exe KEY0 IV0 [CIPHER0...] [-- KEY1 IV1 [CIPHER1...]...] + +where `NNN` is the same. For example, @@ -33,45 +35,33 @@ For example, d42bdf90c1a48221a92a5137c1445418 96248fca82fbefa31345ae7d8fb7933e -On older CPUs, you can run the executables -[using Intel SDE](https://github.com/egor-tensin/aesni#running-on-older-cpus). +On older CPUs, you can run the utilities [using Intel SDE](https://github.com/egor-tensin/aesni#running-on-older-cpus). ## Using test vectors -### From NIST 800-38A - -You can test the implementation against the vectors from -[NIST Special Publication 800-38A](http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf) -using `800-32a.py`. - -The script is written in Python 3, so you need to be able to run Python 3 scripts prior to testing. -Then you can run the script, passing the path to the directory with the required `*_encrypt.exe` and `*_decrypt.exe` files like this: +The test scripts are written in Python 3, hence you need to be able to run Python 3 scripts in order to use them. +The scripts 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). +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. +You must therefore make sure that - python 800-32a.py -r C:\build\test\Debug +* no errors occured while running the tests, +* all the tests succeeded, +* and the skipped tests were skipped for a good reason. -On older CPUs, you can make the script run the executables -[using Intel SDE](https://github.com/egor-tensin/aesni#running-on-older-cpus) -using +To pass a path to the directory with the required utilities, use the `--root` parameter. +To make scripts run the utilities using Intel SDE, pass `--sde`. +Use `--help` to see the script's usage details. - python 800-32a.py -r C:\build\test\Debug -e +### NIST Special Publication 800-38A -The script writes a log file, with a short summary at the end. +To test the implementation against the vectors from [NIST Special Publication 800-38A](http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf) using `800-32a.py`. -### From Cryptographic Algorithm Validation Program + python 800-38a.py -r C:\build\test\Debug -You can test the implementation against the vectors from -[CAVP](http://csrc.nist.gov/groups/STM/cavp/) using `cavp.py`. -The AES Known Answer Test (KAT) Vectors are used and included in `KAT_AES.zip`. +### Cryptographic Algorithm Validation Program -The script is written in Python 3, so you need to be able to run Python 3 scripts prior to testing. -Then you can run the script, passing the path to the directory with the required `*_encrypt.exe` and `*_decrypt.exe` files like this: +To test the implementation against the vectors from [CAVP](http://csrc.nist.gov/groups/STM/cavp/) using `cavp.py`. +The AES Known Answer Test (KAT) Vectors are used and read from `KAT_AES.zip`. python cavp.py -r C:\build\test\Debug - -On older CPUs, you can make the script run the executables -[using Intel SDE](https://github.com/egor-tensin/aesni#running-on-older-cpus) -using - - python cavp.py -r C:\build\test\Debug -e - -The script writes a log file, with a short summary at the end. -- cgit v1.2.3