1 files changed, 158 insertions, 0 deletions
diff --git a/aesxx/utils/README.md b/aesxx/utils/README.md
new file mode 100644
index 0000000..c133c92
--- /dev/null
+++ b/aesxx/utils/README.md
@@ -0,0 +1,158 @@
+Utilities
+=========
+
+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
+utility's detailed usage information.
+
+Block encryption
+----------------
+
+Block encryption utilities can produce verbose human-readable output, including
+round keys, intermediate initialization vector values, etc.
+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).
+
+### encrypt_block
+
+Encrypts blocks using the selected algorithm in the specified mode of
+operation.
+
+For example, to encrypt
+
+* the plaintext block `0x00112233445566778899aabbccddeeff`
+* using AES-128 in ECB mode
+* with key `0x000102030405060708090a0b0c0d0e0f`,
+
+run:
+
+    encrypt_block -a aes128 -m ecb 000102030405060708090a0b0c0d0e0f 00112233445566778899aabbccddeeff
+
+To encrypt
+
+* the plaintext block `0x00112233445566778899aabbccddeeff`
+* using AES-192 in OFB mode
+* with initialization vector `0x22222222222222222222222222222222`
+* and key `0x000102030405060708090a0b0c0d0e0f101112131415161718`,
+
+run:
+
+    encrypt_block -a aes192 -m ofb 000102030405060708090a0b0c0d0e0f101112131415161718 22222222222222222222222222222222 00112233445566778899aabbccddeeff
+
+### decrypt_block
+
+Decrypts blocks using the selected algorithm in the specified mode of
+operation.
+
+For example, to decrypt
+
+* the ciphertext block `0x69c4e0d86a7b0430d8cdb78070b4c55a`
+* using AES-128 in ECB mode
+* with key `0x000102030405060708090a0b0c0d0e0f`,
+
+run:
+
+    decrypt_block -a aes128 -m ecb 000102030405060708090a0b0c0d0e0f 69c4e0d86a7b0430d8cdb78070b4c55a
+
+To decrypt
+
+* the ciphertext block `0x762a5ab50929189cefdb99434790aad8`
+* using AES-192 in OFB mode
+* with initialization vector `0x22222222222222222222222222222222`
+* and key `0x000102030405060708090a0b0c0d0e0f101112131415161718`,
+
+run:
+
+    decrypt_block -a aes192 -m ofb 000102030405060708090a0b0c0d0e0f101112131415161718 22222222222222222222222222222222 bda298884f5c3a9eb7068aa7063a3b75
+
+File encryption
+---------------
+
+### encrypt_file
+
+Encrypts a file using the selected algorithm in the specified mode of
+operation.
+
+For example, to encrypt the plaintext from "input.txt"
+
+* using AES-128 in ECB mode
+* with key `0x11111111111111111111111111111111`
+* and write the ciphertext to "output.txt",
+
+run:
+
+    encrypt_file -a aes128 -m ecb -k 11111111111111111111111111111111 -i input.txt -o output.txt
+
+To encrypt the plaintext from "input.txt"
+
+* using AES-192 in OFB mode
+* with key `0x111111111111111111111111111111111111111111111111`
+* and initialization vector `0x22222222222222222222222222222222`
+* and write the ciphertext to "output.txt":
+
+run
+
+    encrypt_file -a aes192 -m ofb -k 111111111111111111111111111111111111111111111111 -v 22222222222222222222222222222222 -i input.txt -o output.txt
+
+### decrypt_file
+
+Decrypts a file using the selected algorithm in the specified mode of
+operation.
+
+To decrypt the ciphertext from "input.txt"
+
+* using AES-128 in ECB mode
+* with key `0x11111111111111111111111111111111`
+* and write the plaintext to "output.txt",
+
+run
+
+    decrypt_file -a aes128 -m ecb -k 11111111111111111111111111111111 -i input.txt -o output.txt
+
+To decrypt the ciphertext from "input.txt"
+
+* using AES-192 in OFB mode
+* with key `0x111111111111111111111111111111111111111111111111`
+* and initialization vector `0x22222222222222222222222222222222`
+* and write the plaintext to "output.txt",
+
+run
+
+    decrypt_file -a aes192 -m ofb -k 111111111111111111111111111111111111111111111111 -v 22222222222222222222222222222222 -i input.txt -o output.txt
+
+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).
+This can be explicitly shown using 8-bit-per-pixel bitmaps:
+
+| Plaintext BMP    | Encrypted in ECB mode | Encrypted in CBC mode
+| ---------------- | --------------------- | ---------------------
+| ![butterfly.bmp] | ![cipherfly_ecb.bmp]  | ![cipherfly_cbc.bmp]
+
+[butterfly.bmp]: bmp/butterfly.bmp
+[cipherfly_ecb.bmp]: bmp/cipherfly_ecb.bmp
+[cipherfly_cbc.bmp]: bmp/cipherfly_cbc.bmp
+
+### encrypt_bmp
+
+Encrypts the pixels in a BMP image file, preserving the header.
+Otherwise, it's used the same way [encrypt_file](#encrypt_file) is.
+
+### decrypt_bmp
+
+Decrypts the pixels in a BMP image file, preserving the header.
+Otherwise, it's used the same way [decrypt_file](#decrypt_file) is.
+
+See also
+--------
+
+* [Usage on older CPUs]
+* [License]
+
+[Usage on older CPUs]: ../../README.md#usage-on-older-cpus
+[License]: ../../README.md#license