From 8d20b5bb5a0a0fe997affd5ad4d9ca8fedd4e9ef Mon Sep 17 00:00:00 2001
From: Egor Tensin <Egor.Tensin@gmail.com>
Date: Sat, 20 Jun 2015 17:19:55 +0300
Subject: utils: README update

---
 utils/README.md             |  87 ++++++++++++++++++++++++++++++++++++++++++++
 utils/bmp/butterfly.bmp     | Bin 0 -> 503370 bytes
 utils/bmp/cipherfly_cbc.bmp | Bin 0 -> 503382 bytes
 utils/bmp/cipherfly_ecb.bmp | Bin 0 -> 503382 bytes
 4 files changed, 87 insertions(+)
 create mode 100644 utils/README.md
 create mode 100644 utils/bmp/butterfly.bmp
 create mode 100644 utils/bmp/cipherfly_cbc.bmp
 create mode 100644 utils/bmp/cipherfly_ecb.bmp

(limited to 'utils')

diff --git a/utils/README.md b/utils/README.md
new file mode 100644
index 0000000..ec23774
--- /dev/null
+++ b/utils/README.md
@@ -0,0 +1,87 @@
+# Utilities
+
+Here are a couple of useful utilities built on top of the library.
+Each of the utilities accepts `--help` flag, which can be used to examine utility's usage info.
+
+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](https://github.com/egor-tensin/aesni#running-on-older-cpus).
+
+## File encryption
+
+### aes_encrypt_file.exe
+
+Encrypts a file using AES-128/192/256 in the specified mode of operation.
+
+#### Usage examples
+
+For example, to encrypt the plaintext `input.txt`
+
+* using AES-128 in ECB mode
+* with key `0x11111111111111111111111111111111`
+* and write the ciphertext to `output.txt`,
+
+run:
+
+    aes_encrypt_file.exe -a aes128 -m ecb 11111111111111111111111111111111 input.txt 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
+
+    aes_encrypt_file.exe -a aes192 -m ofb 111111111111111111111111111111111111111111111111 22222222222222222222222222222222 input.txt output.txt
+
+### aes_decrypt_file.exe
+
+Decrypts a file using AES-128/192/256 in the specified mode of operation.
+
+#### Usage examples
+
+To decrypt the ciphertext from `input.txt`
+
+* using AES-128 in ECB mode
+* with key `0x11111111111111111111111111111111`
+* and write the plaintext to `output.txt`,
+
+run
+
+    aes_decrypt_file.exe -a aes128 -m ecb 11111111111111111111111111111111 input.txt 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
+
+    aes_decrypt_file.exe -a aes192 -m ofb 111111111111111111111111111111111111111111111111 22222222222222222222222222222222 input.txt 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
+------------- | --------------------- | ---------------------
+![Plaintext butterfly](bmp/butterfly.bmp?raw=true) | ![Ciphertext butterfly in ECB mode](bmp/cipherfly_ecb.bmp?raw=true) | ![Ciphertext butterfly in CBC mode](bmp/cipherfly_cbc.bmp?raw=true)
+
+### aes_encrypt_bmp.exe
+
+Encrypts the pixels in a BMP image file, preserving the header.
+The usage is the same as for [aes_encrypt_file.exe](#aes_encrypt_fileexe).
+
+### aes_decrypt_bmp.exe
+
+Decrypts the pixels in a BMP image file, preserving the header.
+The usage is the same as for [aes_decrypt_file.exe](#aes_decrypt_fileexe).
diff --git a/utils/bmp/butterfly.bmp b/utils/bmp/butterfly.bmp
new file mode 100644
index 0000000..105a55a
Binary files /dev/null and b/utils/bmp/butterfly.bmp differ
diff --git a/utils/bmp/cipherfly_cbc.bmp b/utils/bmp/cipherfly_cbc.bmp
new file mode 100644
index 0000000..664b557
Binary files /dev/null and b/utils/bmp/cipherfly_cbc.bmp differ
diff --git a/utils/bmp/cipherfly_ecb.bmp b/utils/bmp/cipherfly_ecb.bmp
new file mode 100644
index 0000000..78de9a8
Binary files /dev/null and b/utils/bmp/cipherfly_ecb.bmp differ
-- 
cgit v1.2.3