adds ciphers docstrings

wolfcrypt/ciphers.py

@@ -41,11 +41,17 @@ _FEEDBACK_MODES = [MODE_ECB, MODE_CBC, MODE_CFB, MODE_OFB, MODE_CTR]
 
 
 class _Cipher(object):
+    """
+    A PEP 272 compliant Block Encryption Algorithm.
+    """
     def __init__(self, key, mode, IV=None):
         if mode not in _FEEDBACK_MODES:
             raise ValueError("this mode is not supported")
 
-        if mode != MODE_CBC:
+        if mode == MODE_CBC:
+            if IV is None:
+                raise ValueError("this mode requires an 'IV' string")
+        else:
             raise ValueError("this mode is not supported by this cipher")
 
         if self.key_size:
@@ -74,11 +80,27 @@ class _Cipher(object):
 
     @classmethod
     def new(cls, key, mode, IV=None, **kwargs):
-        # PEP 272 -- API for Block Encryption Algorithms
+        """
+        Returns a ciphering object, using the secret key contained in
+        the string 'key', and using the feedback mode 'mode', which
+        must be one of MODE_* defined in this module.
+
+        If 'mode' is MODE_CBC or MODE_CFB, 'IV' must be provided and
+        must be a string of the same length as the block size. Not
+        providing a value of 'IV' will result in a ValueError exception
+        being raised.
+        """
         return cls(key, mode, IV)
 
 
     def encrypt(self, string):
+        """
+        Encrypts a non-empty string, using the key-dependent data in
+        the object, and with the appropriate feedback mode. The
+        string's length must be an exact multiple of the algorithm's
+        block size or, in CFB mode, of the segment size. Returns a
+        string containing the ciphertext.
+        """
         string = t2b(string)
 
         if not string or len(string) % self.block_size:
@@ -100,6 +122,13 @@ class _Cipher(object):
 
 
     def decrypt(self, string):
+        """
+        Decrypts 'string', using the key-dependent data in the
+        object and with the appropriate feedback mode. The string's
+        length must be an exact multiple of the algorithm's block
+        size or, in CFB mode, of the segment size.  Returns a string
+        containing the plaintext.
+        """
         string = t2b(string)
 
         if not string or len(string) % self.block_size:
@@ -166,6 +195,8 @@ class Des3(_Cipher):
 
 
 class _Rsa(object):
+    RSA_MIN_PAD_SIZE = 11
+
     def __init__(self):
         self.native_object = _ffi.new("RsaKey *")
         ret = _lib.wc_InitRsaKey(self.native_object, _ffi.NULL)
@@ -199,6 +230,13 @@ class RsaPublic(_Rsa):
 
 
     def encrypt(self, plaintext):
+        """
+        Encrypts plaintext, using the public key data in the
+        object. The plaintext's length must not be greater than:
+            self.output_size - self.RSA_MIN_PAD_SIZE
+        Returns a string containing the ciphertext.
+        """
+
         plaintext = t2b(plaintext)
         ciphertext = t2b("\0" * self.output_size)
 
@@ -214,6 +252,12 @@ class RsaPublic(_Rsa):
 
 
     def verify(self, signature):
+        """
+        Verifies signature, using the public key data in the
+        object. The signature's length must be equal to:
+            self.output_size
+        Returns a string containing the plaintext.
+        """
         signature = t2b(signature)
         plaintext = t2b("\0" * self.output_size)
 
@@ -246,6 +290,12 @@ class RsaPrivate(RsaPublic):
 
 
     def decrypt(self, ciphertext):
+        """
+        Decrypts ciphertext, using the private key data in the
+        object. The ciphertext's length must be equal to:
+            self.output_size
+        Returns a string containing the plaintext.
+        """
         ciphertext = t2b(ciphertext)
         plaintext = t2b("\0" * self.output_size)
 
@@ -260,6 +310,12 @@ class RsaPrivate(RsaPublic):
 
 
     def sign(self, plaintext):
+        """
+        Signs plaintext, using the private key data in the object.
+        The plaintext's length must not be greater than:
+            self.output_size - self.RSA_MIN_PAD_SIZE
+        Returns a string containing the signature.
+        """
         plaintext = t2b(plaintext)
         signature = t2b("\0" * self.output_size)
 

wolfcrypt/hashes.py

@@ -24,6 +24,9 @@ from wolfcrypt.utils import t2b, b2h
 from wolfcrypt.exceptions import *
 
 class _Hash(object):
+    """
+    A PEP 247 compliant Cryptographic Hash Function.
+    """
     def __init__(self, string=None):
         self._native_object = _ffi.new(self._native_type)
         ret = self._init()
@@ -34,7 +37,7 @@ class _Hash(object):
     @classmethod
     def new(cls, string=None):
         """
-        Create a new hashing object and returns it. The optional
+        Creates a new hashing object and returns it. The optional
         'string' parameter, if supplied, will be immediately hashed
         into the object's starting state, as if obj.update(string)
         was called.
@@ -50,8 +53,8 @@ class _Hash(object):
 
     def copy(self):
         """
-        Return a separate copy of this hashing object. An update to
+        Returns a separate copy of this hashing object. An update
-        this copy won't affect the original object.
+        to this copy won't affect the original object.
         """
         copy = self.new("")
 
@@ -64,9 +67,9 @@ class _Hash(object):
 
     def update(self, string):
         """
-        Hash 'string' into the current state of the hashing object.
+        Hashes 'string' into the current state of the hashing
-        update() can be called any number of times during a hashing
+        object. update() can be called any number of times during
-        object's lifetime.
+        a hashing object's lifetime.
         """
         string = t2b(string)
 
@@ -77,7 +80,7 @@ class _Hash(object):
 
     def digest(self):
         """
-        Return the hash value of this hashing object as a string
+        Returns the hash value of this hashing object as a string
         containing 8-bit data. The object is not altered in any
         way by this function; you can continue updating the object
         after calling this function.
@@ -98,7 +101,7 @@ class _Hash(object):
 
     def hexdigest(self):
         """
-        Return the hash value of this hashing object as a string
+        Returns the hash value of this hashing object as a string
         containing hexadecimal digits. Lowercase letters are used
         for the digits 'a' through 'f'. Like the .digest() method,
         this method doesn't alter the object.
@@ -205,7 +208,7 @@ class _Hmac(_Hash):
     @classmethod
     def new(cls, key, string=None):
         """
-        Create a new hashing object and returns it. 'key' is a
+        Creates a new hashing object and returns it. 'key' is a
         required parameter containing a string giving the key
         to use. The optional 'string' parameter, if supplied, will
         be immediately hashed into the object's starting state, as