Added example for all symmetric ciphers

7 files changed, 85 insertions, 3 deletions

diff --git a/lib/Crypto/Cipher/AES.py b/lib/Crypto/Cipher/AES.py
index 1538df2..a1b7bf4 100644
--- a/lib/Crypto/Cipher/AES.py
+++ b/lib/Crypto/Cipher/AES.py
@@ -23,11 +23,21 @@
 
 AES `(Advanced Encryption Standard)`__ is a symmetric block cipher standardized
 by NIST_ . It has a fixed data block size of 16 bytes.
-Its keys can be 128, 192, or 256 bit long.
+Its keys can be 128, 192, or 256 bits long.
 
 AES is very fast and secure, and it is the de facto standard for symmetric
 encryption.
 
+As an example, encryption can be done as follows:
+
+    >>> from Crypto.Cipher import AES
+    >>> from Crypto import Random
+    >>>
+    >>> key = b'Sixteen byte key'
+    >>> iv = Random.new().read(AES.block_size)
+    >>> cipher = AES.new(key, AES.MODE_CFB, iv)
+    >>> msg = iv + cipher.encrypt(b'Attack at dawn')
+
 .. __: http://en.wikipedia.org/wiki/Advanced_Encryption_Standard
 .. _NIST: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
 
diff --git a/lib/Crypto/Cipher/ARC2.py b/lib/Crypto/Cipher/ARC2.py
index 7393497..e9284a1 100644
--- a/lib/Crypto/Cipher/ARC2.py
+++ b/lib/Crypto/Cipher/ARC2.py
@@ -40,6 +40,16 @@ thoroughly as AES, which is also faster than RC2.
 
 New designs should not use RC2.
 
+As an example, encryption can be done as follows:
+
+    >>> from Crypto.Cipher import ARC2
+    >>> from Crypto import Random
+    >>>
+    >>> key = b'Sixteen byte key'
+    >>> iv = Random.new().read(ARC2.block_size)
+    >>> cipher = ARC2.new(key, ARC2.MODE_CFB, iv)
+    >>> msg = iv + cipher.encrypt(b'Attack at dawn')
+
 .. _RC2: http://en.wikipedia.org/wiki/RC2
 .. _RFC2268: http://tools.ietf.org/html/rfc2268
 
diff --git a/lib/Crypto/Cipher/ARC4.py b/lib/Crypto/Cipher/ARC4.py
index de5e4e8..b745e7c 100644
--- a/lib/Crypto/Cipher/ARC4.py
+++ b/lib/Crypto/Cipher/ARC4.py
@@ -44,6 +44,18 @@ concatenating key and nonce.
 New designs should not use ARC4. A good alternative is AES
 (`Crypto.Cipher.AES`) in any of the modes that turn it into a stream cipher (OFB, CFB, or CTR).
 
+As an example, encryption can be done as follows:
+
+    >>> from Crypto.Cipher import ARC4
+    >>> from Crypto.Hash import SHA
+    >>> from Crypto import Random
+    >>>
+    >>> key = b'Very long and confidential key'
+    >>> nonce = Random.new().read(16)
+    >>> tempkey = SHA.new(key+nonce).digest()
+    >>> cipher = ARC4.new(tempkey)
+    >>> msg = nonce + cipher.encrypt(b'Open the pod bay doors, HAL')
+
 .. _ARC4: http://en.wikipedia.org/wiki/RC4
 
 :undocumented: __revision__, __package__
diff --git a/lib/Crypto/Cipher/Blowfish.py b/lib/Crypto/Cipher/Blowfish.py
index 783a5a1..f060689 100644
--- a/lib/Crypto/Cipher/Blowfish.py
+++ b/lib/Crypto/Cipher/Blowfish.py
@@ -29,6 +29,22 @@ from 32 to 448 bits (4 to 56 bytes).
 Blowfish is deemed secure and it is fast. However, its keys should be chosen
 to be big enough to withstand a brute force attack (e.g. at least 16 bytes).
 
+As an example, encryption can be done as follows:
+
+    >>> from Crypto.Cipher import Blowfish
+    >>> from Crypto import Random
+    >>> from struct import pack
+    >>>
+    >>> bs = Blowfish.block_size
+    >>> key = b'An arbitrarily long key'
+    >>> iv = Random.new().read(bs)
+    >>> cipher = Blowfish.new(key, Blowfish.MODE_CBC, iv)
+    >>> plaintext = b'docendo discimus '
+    >>> plen = bs - divmod(len(plaintext),bs)[1]
+    >>> padding = [plen]*plen
+    >>> padding = pack('b'*plen, *padding)
+    >>> msg = iv + cipher.encrypt(plaintext + padding)
+
 .. _Blowfish: http://www.schneier.com/blowfish.html
 
 :undocumented: __revision__, __package__
diff --git a/lib/Crypto/Cipher/CAST.py b/lib/Crypto/Cipher/CAST.py
index 8a57548..f47e65b 100644
--- a/lib/Crypto/Cipher/CAST.py
+++ b/lib/Crypto/Cipher/CAST.py
@@ -30,6 +30,17 @@ CAST is deemed to be cryptographically secure, but its usage is not widespread.
 Keys of sufficient length should be used to prevent brute force attacks
 (128 bits are recommended).
 
+As an example, encryption can be done as follows:
+
+    >>> from Crypto.Cipher import CAST
+    >>> from Crypto import Random
+    >>>
+    >>> key = b'Sixteen byte key'
+    >>> iv = Random.new().read(CAST.block_size)
+    >>> cipher = CAST.new(key, CAST.MODE_OFB, iv)
+    >>> plaintext = b'sona si latine loqueris '
+    >>> msg = iv + cipher.encrypt(plaintext)
+
 .. _CAST-128: http://en.wikipedia.org/wiki/CAST-128
 .. _RFC2144: http://tools.ietf.org/html/rfc2144
 
diff --git a/lib/Crypto/Cipher/DES.py b/lib/Crypto/Cipher/DES.py
index a6fae5c..d4300c6 100644
--- a/lib/Crypto/Cipher/DES.py
+++ b/lib/Crypto/Cipher/DES.py
@@ -23,7 +23,7 @@
 
 DES `(Data Encryption Standard)`__ is a symmetric block cipher standardized
 by NIST_ . It has a fixed data block size of 8 bytes.
-Its keys are 64 bit long, even though 8 bits were used for integrity (now they
+Its keys are 64 bits long, even though 8 bits were used for integrity (now they
 are ignored) and do not contribute to securty.
 
 DES is cryptographically secure, but its key length is too short by nowadays
@@ -31,10 +31,20 @@ standards and it could be brute forced with some effort.
 
 DES should not be used for new designs. Use `AES`.
 
+As an example, encryption can be done as follows:
+
+    >>> from Crypto.Cipher import DES3
+    >>> from Crypto import Random
+    >>>
+    >>> key = b'Sixteen byte key'
+    >>> iv = Random.new().read(DES3.block_size)
+    >>> cipher = DES3.new(key, DES3.MODE_OFB, iv)
+    >>> plaintext = b'sona si latine loqueris '
+    >>> msg = iv + cipher.encrypt(plaintext)
+
 .. __: http://en.wikipedia.org/wiki/Data_Encryption_Standard
 .. _NIST: http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf
 
-
 :undocumented: __revision__, __package__
 """
 
diff --git a/lib/Crypto/Cipher/DES3.py b/lib/Crypto/Cipher/DES3.py
index 84492cf..39e726c 100644
--- a/lib/Crypto/Cipher/DES3.py
+++ b/lib/Crypto/Cipher/DES3.py
@@ -42,6 +42,19 @@ single `DES`.
 TDES is cryptographically secure, even though it is neither as secure nor as fast
 as `AES`.
 
+As an example, encryption can be done as follows:
+
+    >>> from Crypto.Cipher import DES
+    >>> from Crypto import Random
+    >>> from Crypto.Util import Counter
+    >>>
+    >>> key = b'-8B key-'
+    >>> nonce = Random.new().read(DES.block_size/2)
+    >>> ctr = Counter.new(DES.block_size*8/2, prefix=nonce)
+    >>> cipher = DES.new(key, DES.MODE_CTR, counter=ctr)
+    >>> plaintext = b'We are no longer the knights who say ni!'
+    >>> msg = nonce + cipher.encrypt(plaintext)
+
 .. __: http://en.wikipedia.org/wiki/Triple_DES
 .. _NIST: http://csrc.nist.gov/publications/nistpubs/800-67/SP800-67.pdf