Add documentation for XOR cipher

4 files changed, 89 insertions, 3 deletions

diff --git a/lib/Crypto/Cipher/XOR.py b/lib/Crypto/Cipher/XOR.py
new file mode 100644
index 0000000..26ec1b1
--- /dev/null
+++ b/lib/Crypto/Cipher/XOR.py
@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+#
+#  Cipher/XOR.py : XOR
+#
+# ===================================================================
+# 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.
+# ===================================================================
+"""XOR toy cipher
+
+XOR is one the simplest stream ciphers. Encryption and decryption are
+performed by XOR-ing data with a keystream made by contatenating
+the key.
+
+Do not use it for real applications!
+
+:undocumented: __revision__, __package__
+"""
+
+__revision__ = "$Id$"
+
+from Crypto.Cipher import _XOR
+
+class XORCipher:
+    """XOR cipher object"""
+
+    def __init__(self, key, *args, **kwargs):
+        """Initialize a XOR cipher object
+        
+        See also `new()` at the module level."""
+        self._cipher = _XOR.new(key, *args, **kwargs)
+        self.block_size = self._cipher.block_size
+        self.key_size = self._cipher.key_size
+
+    def encrypt(self, plaintext):
+        """Encrypt a piece of data.
+
+        :Parameters:
+          plaintext : byte string
+            The piece of data to encrypt. It can be of any size.
+        :Return: the encrypted data (byte string, as long as the
+          plaintext).
+        """
+        return self._cipher.encrypt(plaintext)
+
+    def decrypt(self, ciphertext):
+        """Decrypt a piece of data.
+
+        :Parameters:
+          ciphertext : byte string
+            The piece of data to decrypt. It can be of any size.
+        :Return: the decrypted data (byte string, as long as the
+          ciphertext).
+        """
+        return self._cipher.decrypt(ciphertext)
+
+def new(key, *args, **kwargs):
+    """Create a new XOR cipher
+
+    :Parameters:
+      key : byte string
+        The secret key to use in the symmetric cipher.
+        Its length may vary from 1 to 32 bytes.
+
+    :Return: an `XORCipher` object
+    """
+    return XORCipher(key, *args, **kwargs)
+
+#: Size of a data block (in bytes)
+block_size = 1
+#: Size of a key (in bytes)
+key_size = xrange(1,32+1)
+
diff --git a/lib/Crypto/Cipher/__init__.py b/lib/Crypto/Cipher/__init__.py
index 0bb1ba5..5b7faaa 100644
--- a/lib/Crypto/Cipher/__init__.py
+++ b/lib/Crypto/Cipher/__init__.py
@@ -69,7 +69,7 @@ Crypto.Cipher.PKCS1_OAEP    PKCS#1 OAEP encryption, based on RSA key pairs
 ========================    =======================
 
 :undocumented: __revision__, __package__, _AES, _ARC2, _ARC4, _Blowfish
-               _CAST, _DES, _DES3
+               _CAST, _DES, _DES3, _XOR
 """
 
 __all__ = ['AES', 'ARC2', 'ARC4',
diff --git a/setup.py b/setup.py
index 704280e..daa3a4d 100644
--- a/setup.py
+++ b/setup.py
@@ -418,7 +418,7 @@ kw = {'name':"pycrypto",
             Extension("Crypto.Cipher._ARC4",
                       include_dirs=['src/'],
                       sources=["src/ARC4.c"]),
-            Extension("Crypto.Cipher.XOR",
+            Extension("Crypto.Cipher._XOR",
                       include_dirs=['src/'],
                       sources=["src/XOR.c"]),
 
diff --git a/src/XOR.c b/src/XOR.c
index 2e8594f..985e94f 100644
--- a/src/XOR.c
+++ b/src/XOR.c
@@ -26,7 +26,7 @@
 
 #include "Python.h"
 
-#define MODULE_NAME XOR
+#define MODULE_NAME _XOR
 #define BLOCK_SIZE 1
 #define KEY_SIZE 0