diff options
author | Egor Tensin <Egor.Tensin@gmail.com> | 2015-07-07 17:04:48 +0300 |
---|---|---|
committer | Egor Tensin <Egor.Tensin@gmail.com> | 2015-07-07 17:04:48 +0300 |
commit | 1bafa86f2f7b1019314b5629f4fd80c7cf9c837c (patch) | |
tree | 9601e8dcc4b3b7d9e76fe398c3d0aa61325ee1bb /utils/README.md | |
parent | code style (diff) | |
download | aes-tools-1bafa86f2f7b1019314b5629f4fd80c7cf9c837c.tar.gz aes-tools-1bafa86f2f7b1019314b5629f4fd80c7cf9c837c.zip |
utils: rearrange files
Diffstat (limited to 'utils/README.md')
-rw-r--r-- | utils/README.md | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/utils/README.md b/utils/README.md new file mode 100644 index 0000000..47db570 --- /dev/null +++ b/utils/README.md @@ -0,0 +1,144 @@ +# Utilities + +Here are a couple of useful utilities built on top of the library. +Each of the utilities accepts the `--help` flag, which can be used to examine utility's usage info. + +The included utilities are: + +* [block encryption](#block-encryption) utilities, +* [file encryption](#file-encryption) utilities, +* and [bitmap encryption](#bitmap-encryption) utilities. + +## Block encryption + +On older CPUs, you can run the utilities [using Intel SDE](https://github.com/egor-tensin/aesni#running-on-older-cpus). + +### aes_encrypt_block.exe + +Encrypts 16-byte blocks using AES-128/192/256 in the specified mode of operation. + +#### Usage examples + +For example, to encrypt + +* the plaintext block `0x00112233445566778899aabbccddeeff` +* using AES-128 in ECB mode +* with key `0x000102030405060708090a0b0c0d0e0f`, + +run: + + aes_encrypt_block.exe -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: + + aes_encrypt_block.exe -a aes192 -m ofb 000102030405060708090a0b0c0d0e0f101112131415161718 22222222222222222222222222222222 00112233445566778899aabbccddeeff + +### aes_decrypt_block.exe + +Decrypts 16-byte blocks using AES-128/192/256 in the specified mode of operation. + +#### Usage examples + +For example, to decrypt + +* the ciphertext block `0x69c4e0d86a7b0430d8cdb78070b4c55a` +* using AES-128 in ECB mode +* with key `0x000102030405060708090a0b0c0d0e0f`, + +run: + + aes_decrypt_block.exe -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: + + aes_decrypt_block.exe -a aes192 -m ofb 000102030405060708090a0b0c0d0e0f101112131415161718 22222222222222222222222222222222 bda298884f5c3a9eb7068aa7063a3b75 + +## 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). |