Added documentation for AES and DES.

A new module (blockalgo) has been added. It contains a class (BlockAlgo)
all ciphers derive from. The only purpose of such base class
is to centralize all general documentation applicable to all block
ciphers (e.g. modes) into a single file.

6 files changed, 368 insertions, 4 deletions

diff --git a/lib/Crypto/Cipher/AES.py b/lib/Crypto/Cipher/AES.py
new file mode 100644
index 0000000..83ae7c5
--- /dev/null
+++ b/lib/Crypto/Cipher/AES.py
@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+#
+#  Cipher/AES.py : AES
+#
+# ===================================================================
+# The contents of this file are dedicated to the public domain.  To
+# the extent that dedication to the public domain is not available,
+# everyone is granted a worldwide, perpetual, royalty-free,
+# non-exclusive license to exercise all rights associated with the
+# contents of this file for any purpose whatsoever.
+# No rights are reserved.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ===================================================================
+"""AES symmetric cipher
+
+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.
+
+AES is very fast and secure, and it is the de facto standard for symmetric
+encryption.
+
+.. __: http://en.wikipedia.org/wiki/Advanced_Encryption_Standard
+.. _NIST: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
+
+:undocumented: __revision__, __package__
+"""
+
+__revision__ = "$Id$"
+
+from Crypto.Cipher import blockalgo
+from blockalgo import *
+from Crypto.Cipher import _AES
+
+class AESCipher (blockalgo.BlockAlgo):
+    """AES cipher object"""
+
+    def __init__(self, key, *args, **kwargs):
+        """Initialize an AES cipher object
+        
+        See also `new()` at the module level."""
+        blockalgo.BlockAlgo.__init__(self, _AES, key, *args, **kwargs)
+
+def new(key, *args, **kwargs):
+    """Create a new AES cipher
+
+    :Parameters:
+      key : byte string
+        The secret key to use in the symmetric cipher.
+        It must be 16 (*AES-128*), 24 (*AES-192), or 32 (*AES-256*) bytes long.
+    :Keywords:
+      mode : a *MODE_** constant
+        The chaining mode to use for encryption or decryption.
+        Default is `MODE_ECB`.
+      IV : byte string
+        The initialization vector to use for encryption or decryption.
+        It must be `block_size` bytes longs. Ignored for `MODE_ECB`
+        and `MODE_CTR`. The default value is all zeroes.
+      counter : callable
+        (*Only* `MODE_CTR`). A stateful function that returns the next
+        *counter block*, which is a byte string of `block_size` bytes.
+        For better performance, use `Crypto.Util.Counter`.
+      segment_size : integer
+        (*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext
+        are segmented in.
+        It must be a multiple of 8. If 0 or not specified, it will be assumed to be 8.
+
+    :Return: an `AESCipher` object
+    """
+    return AESCipher(key, *args, **kwargs)
+
+#: Electronic Code Book (ECB). See `blockalgo.MODE_ECB`.
+MODE_ECB = 1
+#: Cipher-Block Chaining (CBC). See `blockalgo.MODE_CBC`.
+MODE_CBC = 2
+#: Cipher FeedBack (CFB). See `blockalgo.MODE_CFB`.
+MODE_CFB = 3
+#: This mode should not be used.
+MODE_PGP = 4
+#: Output FeedBack (OFB). See `blockalgo.MODE_OFB`.
+MODE_OFB = 5
+#: CounTer Mode (CTR). See `blockalgo.MODE_CTR`.
+MODE_CTR = 6
+#: Size of a data block (in bytes)
+block_size = 16
+#: Size of a key (in bytes)
+key_size = { 16, 24, 32 }
+
diff --git a/lib/Crypto/Cipher/DES.py b/lib/Crypto/Cipher/DES.py
new file mode 100644
index 0000000..46862d7
--- /dev/null
+++ b/lib/Crypto/Cipher/DES.py
@@ -0,0 +1,84 @@
+#
+#  Cipher/DES.py : DES
+#
+# ===================================================================
+# The contents of this file are dedicated to the public domain.  To
+# the extent that dedication to the public domain is not available,
+# everyone is granted a worldwide, perpetual, royalty-free,
+# non-exclusive license to exercise all rights associated with the
+# contents of this file for any purpose whatsoever.
+# No rights are reserved.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ===================================================================
+"""DES symmetric cipher
+
+:undocumented: __revision__, __package__
+"""
+
+__revision__ = "$Id$"
+
+from Crypto.Cipher import blockalgo
+from blockalgo import *
+from Crypto.Cipher import _DES
+
+class DESCipher(blockalgo.BlockAlgo):
+    """DES cipher object"""
+
+    def __init__(self, key, *args, **kwargs):
+        """Initialize a DES cipher object
+        
+        See also `new()` at the module level."""
+        blockalgo.BlockAlgo.__init__(self, _DES, key, *args, **kwargs)
+
+def new(key, *args, **kwargs):
+    """Create a new DES cipher
+
+    :Parameters:
+      key : byte string
+        The secret key to use in the symmetric cipher.
+        It must be 8 byte long.
+    :Keywords:
+      mode : a *MODE_** constant
+        The chaining mode to use for encryption or decryption.
+        Default is `MODE_ECB`.
+      IV : byte string
+        The initialization vector to use for encryption or decryption.
+        It must be `block_size` bytes longs. Ignored for `MODE_ECB`
+        and `MODE_CTR`. The default value is all zeroes.
+      counter : callable
+        (*Only* `MODE_CTR`). A stateful function that returns the next
+        *counter block*, which is a byte string of `block_size` bytes.
+        For better performance, use `Crypto.Util.Counter`.
+      segment_size : integer
+        (*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext
+        are segmented in.
+        It must be a multiple of 8. If 0 or not specified, it will be assumed to be 8.
+
+    :Return: an `DESCipher` object
+    """
+    return DESCipher(key, *args, **kwargs)
+
+#: Electronic Code Book (ECB). See `blockalgo.MODE_ECB`.
+MODE_ECB = 1
+#: Cipher-Block Chaining (CBC). See `blockalgo.MODE_CBC`.
+MODE_CBC = 2
+#: Cipher FeedBack (CFB). See `blockalgo.MODE_CFB`.
+MODE_CFB = 3
+#: This mode should not be used.
+MODE_PGP = 4
+#: Output FeedBack (OFB). See `blockalgo.MODE_OFB`.
+MODE_OFB = 5
+#: CounTer Mode (CTR). See `blockalgo.MODE_CTR`.
+MODE_CTR = 6
+#: Size of a data block (in bytes)
+block_size = 8
+#: Size of a key (in bytes)
+key_size = 8
diff --git a/lib/Crypto/Cipher/blockalgo.py b/lib/Crypto/Cipher/blockalgo.py
new file mode 100644
index 0000000..70e8ca0
--- /dev/null
+++ b/lib/Crypto/Cipher/blockalgo.py
@@ -0,0 +1,184 @@
+# -*- coding: utf-8 -*-
+#
+#  Cipher/blockalgo.py 
+#
+# ===================================================================
+# The contents of this file are dedicated to the public domain.  To
+# the extent that dedication to the public domain is not available,
+# everyone is granted a worldwide, perpetual, royalty-free,
+# non-exclusive license to exercise all rights associated with the
+# contents of this file for any purpose whatsoever.
+# No rights are reserved.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ===================================================================
+"""Module with definitions commont to all block ciphers."""
+
+#: *Electronic Code Book (ECB)*.
+#: This is the simplest encryption mode. Each of the plaintext blocks
+#: is directly encrypted into a ciphertext block, independently of
+#: any other block. This mode exposes frequency of symbols
+#: in your plaintext. Other modes (e.g. *CBC*) should be used instead.
+#:
+#: See `NIST SP800-38A`_ , Section 6.1 .
+#:
+#: .. _`NIST SP800-38A` : http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+MODE_ECB = 1
+
+#: *Cipher-Block Chaining (CBC)*. Each of the ciphertext blocks depends
+#: on the current and all previous plaintext blocks. An Initialization Vector
+#: (*IV*) is required.
+#:
+#: The *IV* is a data block to be transmitted to the receiver.
+#: The *IV* can be made public, but it must be authenticated by the receiver and
+#: it should be picked randomly.
+#:
+#: See `NIST SP800-38A`_ , Section 6.2 .
+#:
+#: .. _`NIST SP800-38A` : http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+MODE_CBC = 2
+
+#: *Cipher FeedBack (CFB)*. This mode is similar to CBC, but it transforms
+#: the underlying block cipher into a stream cipher. Plaintext and ciphertext
+#: are processed in *segments* of **s** bits. The mode is therefore sometimes
+#: labelled **s**-bit CFB. An Initialization Vector (*IV*) is required.
+#:
+#: When encrypting, each ciphertext segment contributes to the encryption of
+#: the next plaintext segment.
+#:
+#: This *IV* is a data block to be transmitted to the receiver.
+#: The *IV* can be made public, but it should be picked randomly.
+#: Reusing the same *IV* for encryptions done with the same key lead to
+#: catastrophic cryptographic failures.
+#:
+#: See `NIST SP800-38A`_ , Section 6.3 .
+#:
+#: .. _`NIST SP800-38A` : http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+MODE_CFB = 3
+
+#: This mode should not be used.
+MODE_PGP = 4
+
+#: *Output FeedBack (OFB)*. This mode is very similar to CBC, but it
+#: transforms the underlying block cipher into a stream cipher.
+#: The keystream is the iterated block encryption of an Initialization Vector (*IV*).
+#:
+#: The *IV* is a data block to be transmitted to the receiver.
+#: The *IV* can be made public, but it should be picked randomly.
+#:
+#: Reusing the same *IV* for encryptions done with the same key lead to
+#: catastrophic cryptograhic failures.
+#:
+#: See `NIST SP800-38A`_ , Section 6.4 .
+#:
+#: .. _`NIST SP800-38A` : http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+MODE_OFB = 5
+
+#: *CounTeR (CTR)*. This mode is very similar to ECB, in that
+#: encryption of one block is done independently of all other blocks.
+#: Unlike ECB, the block *position* contributes to the encryption and no
+#: information leaks about symbol frequency.
+#:
+#: Each message block is associated to a *counter* which must be unique
+#: across all messages that get encrypted with the same key (not just within
+#: the same message). The counter is as big as the block size.
+#:
+#: Counters can be generated in several ways. The most straightword one is
+#: to choose an *initial counter block* (which can be made public, similarly
+#: to the *IV* for the other modes) and increment its lowest **m** bits by
+#: one (modulo *2^m*) for each block. In most cases, **m** is chosen to be half
+#: the block size.
+#: 
+#: Reusing the same *initial counter block* for encryptions done with the same
+#: key lead to catastrophic cryptograhic failures.
+#:
+#: See `NIST SP800-38A`_ , Section 6.5 (for the mode) and Appendix B (for how
+#: to manage the *initial counter block*).
+#:
+#: .. _`NIST SP800-38A` : http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+MODE_CTR = 6
+
+class BlockAlgo:
+    """Class modelling an abstract block cipher."""
+
+    def __init__(self, factory, key, *args, **kwargs):
+        self._cipher = factory.new(key, *args, **kwargs)
+        self.block_size = self._cipher.block_size
+        self.mode = self._cipher.mode
+        self.IV = self._cipher.IV
+
+    def encrypt(self, plaintext):
+        """Encrypt data with the key and the parameters set at initialization.
+        
+        The cipher object is stateful; encryption of a long block
+        of data can be broken up in two or more calls to `encrypt()`.
+        That is, the statement:
+            
+            >>> c.encrypt(a) + c.encrypt(b)
+
+        is always equivalent to:
+
+             >>> c.encrypt(a+b)
+
+        That also means that you cannot reuse an object for encrypting
+        or decrypting other data with the same key.
+
+        This function does not perform any padding.
+       
+         - For `MODE_ECB`, `MODE_CBC`, and `MODE_OFB`, *plaintext* length
+           (in bytes) must be a multiple of *block_size*.
+
+         - For `MODE_CFB`, *plaintext* length (in bytes) must be a multiple
+           of *segment_size*/8.
+
+         - For `MODE_CTR`, *plaintext* can be of any length.
+
+        :Parameters:
+          plaintext : byte string
+            The piece of data to encrypt.
+        :Return: the encrypted data (as a byte string, as long as the
+          plaintext)
+        """
+        return self._cipher.encrypt(plaintext)
+
+    def decrypt(self, ciphertext):
+        """Decrypt data with the key and the parameters set at initialization.
+        
+        The cipher object is stateful; decryption of a long block
+        of data can be broken up in two or more calls to `decrypt()`.
+        That is, the statement:
+            
+            >>> c.decrypt(a) + c.decrypt(b)
+
+        is always equivalent to:
+
+             >>> c.decrypt(a+b)
+
+        That also means that you cannot reuse an object for encrypting
+        or decrypting other data with the same key.
+
+        This function does not perform any padding.
+       
+         - For `MODE_ECB`, `MODE_CBC`, and `MODE_OFB`, *ciphertext* length
+           (in bytes) must be a multiple of *block_size*.
+
+         - For `MODE_CFB`, *ciphertext* length (in bytes) must be a multiple
+           of *segment_size*/8.
+
+         - For `MODE_CTR`, *ciphertext* can be of any length.
+
+        :Parameters:
+          ciphertext : byte string
+            The piece of data to decrypt.
+        :Return: the decrypted data (as a byte string, as long as the
+          ciphertext)
+        """
+        return self._cipher.decrypt(ciphertext)
+
diff --git a/setup.py b/setup.py
index dd05abc..8a22b6e 100644
--- a/setup.py
+++ b/setup.py
@@ -395,7 +395,7 @@ kw = {'name':"pycrypto",
                       define_macros=[endianness_macro()]),
 
             # Block encryption algorithms
-            Extension("Crypto.Cipher.AES",
+            Extension("Crypto.Cipher._AES",
                       include_dirs=['src/'],
                       sources=["src/AES.c"]),
             Extension("Crypto.Cipher.ARC2",
@@ -407,7 +407,7 @@ kw = {'name':"pycrypto",
             Extension("Crypto.Cipher.CAST",
                       include_dirs=['src/'],
                       sources=["src/CAST.c"]),
-            Extension("Crypto.Cipher.DES",
+            Extension("Crypto.Cipher._DES",
                       include_dirs=['src/', 'src/libtom/'],
                       sources=["src/DES.c"]),
             Extension("Crypto.Cipher.DES3",
diff --git a/src/AES.c b/src/AES.c
index b6a1726..0aeaeda 100644
--- a/src/AES.c
+++ b/src/AES.c
@@ -28,7 +28,7 @@
 #include <stdlib.h>
 #include "Python.h"
 
-#define MODULE_NAME AES
+#define MODULE_NAME _AES
 #define BLOCK_SIZE 16
 #define KEY_SIZE 0
 
diff --git a/src/DES.c b/src/DES.c
index 2bf3f84..ba63a09 100644
--- a/src/DES.c
+++ b/src/DES.c
@@ -102,7 +102,7 @@ static void block_decrypt(block_state *self, unsigned char *in, unsigned char *o
 # define BLOCK_SIZE 8       /* 64-bit block size */
 # define KEY_SIZE  0        /* variable key size (can be 128 or 192 bits (including parity) */
 #else
-# define MODULE_NAME DES    /* single DES */
+# define MODULE_NAME _DES   /* single DES */
 # define BLOCK_SIZE 8       /* 64-bit block size */
 # define KEY_SIZE  8        /* 64-bit keys (including parity) */
 #endif