updates docs with hashes and random

docs/asymmetric.rst

@@ -0,0 +1,2 @@
+Asymmetric Key Algorithms
+=========================

docs/ciphers/aes.rst

@@ -1,2 +0,0 @@
-AES
-===

docs/ciphers/asymmetric.rst

@@ -1,7 +0,0 @@
-Symmetric Key Algorithms
-========================
-
-.. toctree::
-   :maxdepth: 1
-
-   rsa

docs/ciphers/des3.rst

@@ -1,2 +0,0 @@
-DES3
-====

docs/ciphers/rsa.rst

@@ -1,2 +0,0 @@
-RSA
-===

docs/ciphers/symmetric.rst

@@ -1,8 +0,0 @@
-Symmetric Key Algorithms
-========================
-
-.. toctree::
-   :maxdepth: 1
-
-   aes
-   des3

docs/conf.py

@@ -294,3 +294,6 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# Preserves the order of the members, doesn't sorts them alphabetically.
+autodoc_member_order = 'bysource'

docs/digest.rst

@@ -0,0 +1,71 @@
+Message Digests
+===============
+
+.. module:: wolfcrypt.hashes
+
+A **message digest** is the output of a **cryptographic hash function**
+containing a string of bytes created by a **one-way formula** using the
+original message as input.
+
+Message digests are designed to protect the integrity of a piece of data or
+media to detect changes and alterations to any part of a message.
+
+
+Hashing Classes
+---------------
+
+Interface
+~~~~~~~~~
+
+All Hashing Functions available in this module implements the following
+interface:
+
+.. autoclass:: _Hash
+    :members:
+
+SHA-1
+~~~~~
+
+.. attention::
+
+    NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications
+    are strongly suggested to use SHA-2 over SHA-1.
+
+.. autoclass:: Sha
+
+SHA-2 family
+~~~~~~~~~~~~
+
+.. autoclass:: Sha256
+
+
+.. autoclass:: Sha384
+
+
+.. autoclass:: Sha512
+
+
+Example
+-------
+
+.. doctest::
+
+    >>> from wolfcrypt.hashes import Sha256
+    >>>
+    >>> s = Sha256()
+    >>> s.update(b'wolf')
+    >>> s.update(b'crypt')
+    >>> s.digest()
+    b'\x96\xe0.{\x1c\xbc\xd6\xf1\x04\xfe\x1f\xdbFR\x02zU\x05\xb6\x86R\xb7\x00\x95\xc61\x8f\x9d\xce\r\x18D'
+    >>> s.hexdigest()
+    b'96e02e7b1cbcd6f104fe1fdb4652027a5505b68652b70095c6318f9dce0d1844'
+    >>>
+    >>> s.update(b'rocks')
+    >>> s.hexdigest()
+    b'e1a50df419d65715c48316bdc6a6f7f0485f4b26c1b107228faf17988b61c83f'
+    >>>
+    >>> Sha256(b'wolfcryptrocks').hexdigest()
+    b'e1a50df419d65715c48316bdc6a6f7f0485f4b26c1b107228faf17988b61c83f'
+    >>>
+    >>> Sha256.new(b'wolfcryptrocks').hexdigest()
+    b'e1a50df419d65715c48316bdc6a6f7f0485f4b26c1b107228faf17988b61c83f'

docs/hashes/hmac.rst

@@ -1,2 +0,0 @@
-Hmac
-====

docs/hashes/index.rst

@@ -1,11 +0,0 @@
-Hashing Functions
-=================
-
-
-.. toctree::
-   :maxdepth: 1
-
-   sha
-   sha256
-   sha384
-   sha512

docs/hashes/sha.rst

@@ -1,2 +0,0 @@
-SHA
-===

docs/hashes/sha256.rst

@@ -1,2 +0,0 @@
-SHA256
-======

docs/hashes/sha384.rst

@@ -1,2 +0,0 @@
-SHA384
-======

docs/hashes/sha512.rst

@@ -1,2 +0,0 @@
-SHA512
-======

docs/index.rst

@@ -1,7 +1,8 @@
-wolfcrypt Python Documentation
-==============================
+wolfCrypt Python Documentation
+==================================
 
-**wolfcrypt** is a Python library that encapsulates **wolfSSL's wolfCrypt API**.
+**wolfCrypt Python**, a.k.a. ``wolfcrypt`` is a Python library that encapsulates
+**wolfSSL's wolfCrypt API**.
 
 **wolfCrypt** is a lightweight, portable, C-language-based crypto library
 targeted at IoT, embedded, and RTOS environments primarily because of its size,
@@ -9,22 +10,37 @@ speed, and feature set. It works seamlessly in desktop, enterprise, and cloud
 environments as well.
 
 Summary
-=======
+-------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   symmetric
+   asymmetric
+   digest
+   mac
    random
-   hashes/index
-   hashes/hmac
-   ciphers/symmetric
-   ciphers/asymmetric
 
+Licensing
+---------
 
+wolfSSL’s software is available under two distinct licensing models:
+open source and standard commercial licensing. Please see the relevant
+section below for information on each type of license.
 
-Indices and tables
-==================
+Open Source
+~~~~~~~~~~~
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+wolfCrypt and wolfSSL software are free software downloads and may be modified
+to the needs of the user as long as the user adheres to version two of the GPL
+License. The GPLv2 license can be found on the `gnu.org website
+<http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_.
+
+Commercial Licensing
+~~~~~~~~~~~~~~~~~~~~
+
+Businesses and enterprises who wish to incorporate wolfSSL products into
+proprietary appliances or other commercial software products for
+re-distribution must license commercial versions. Licenses are generally issued
+for one product and include unlimited royalty-free distribution. Custom
+licensing terms are also available at licensing@wolfssl.com.

docs/mac.rst

@@ -0,0 +1,74 @@
+Message Authentication Codes
+============================
+
+.. module:: wolfcrypt.hashes
+
+A **message authentication code** (MAC) is a short piece of information used
+to authenticate a message — in other words, to confirm that the message came
+from the stated sender (its authenticity) and has not been changed in transit
+(its integrity).
+
+``wolfcrypt`` implements the **Hash-based message authentication code** (HMAC),
+which uses a cryptographic hash function coupled with a secret key to produce
+**message authentication codes**.
+
+
+Hmac Classes
+------------
+
+Interface
+~~~~~~~~~
+
+All Hmac classes available in this module implements the following
+interface:
+
+.. autoclass:: _Hmac
+    :members:
+    :inherited-members:
+
+SHA-1
+~~~~~
+
+.. attention::
+
+    NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications
+    are strongly suggested to use SHA-2 over SHA-1.
+
+.. autoclass:: HmacSha
+
+SHA-2 family
+~~~~~~~~~~~~
+
+.. autoclass:: HmacSha256
+
+
+.. autoclass:: HmacSha384
+
+
+.. autoclass:: HmacSha512
+
+
+Example
+-------
+
+.. doctest::
+
+    >>> from wolfcrypt.hashes import HmacSha256
+    >>>
+    >>> h = HmacSha256('secret')
+    >>> h.update("wolf")
+    >>> h.update("crypt")
+    >>> h.digest()
+    b'\x18\xbf*\t9\xa2o\xdf\\\xc8\xe0\xc2U\x94,\x8dY\x02;\x1c<Q\xdf\x8d\xdb\x863\xfb\xc1f#o'
+    >>> h.hexdigest()
+    b'18bf2a0939a26fdf5cc8e0c255942c8d59023b1c3c51df8ddb8633fbc166236f'
+    >>>
+    >>> h.update("rocks")
+    >>> h.hexdigest()
+    b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e'
+    >>>
+    >>> HmacSha256('secret', 'wolfcryptrocks').hexdigest()
+    b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e'
+    >>>
+    >>> HmacSha256.new('secret', 'wolfcryptrocks').hexdigest()
+    b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e'

docs/random.rst

@@ -1,2 +1,30 @@
 Random Number Generation
 ========================
+
+A **cryptographically secure pseudo-random number generator** (CSPRNG) is a
+**pseudo-random number generator** (PRNG) with properties that make it suitable
+for use in cryptography.
+
+Using the standard random module APIs for cryptographic keys or initialization
+vectors can result in major security issues depending on the algorithms in use.
+
+``wolfcrypt`` provides the following CSPRNG implementation:
+
+.. module:: wolfcrypt.random
+
+.. autoclass:: Random
+    :members:
+
+
+Example
+-------
+
+.. doctest::
+
+    >>> from wolfcrypt.random import Random
+    >>>
+    >>> r = Random()
+    >>> r.byte()
+    b'\x8c'
+    >>> r.bytes(16)
+    b']\x93nk\x95\xbc@\xffX\xab\xdcB\xda\x11\xf7\x03'

docs/symmetric.rst

@@ -0,0 +1,7 @@
+Symmetric Key Algorithms
+========================
+
+**Symmetric key algorithms** are encryption algorithms that use the **same
+cryptographic keys** for both encryption and decryption of data.
+This operation is also known as **Symmetric Key Encryption**.
+``wolfcrypt`` algorithms:

wolfcrypt/hashes.py

@@ -25,7 +25,8 @@ from wolfcrypt.exceptions import *
 
 class _Hash(object):
     """
-    A PEP 247 compliant Cryptographic Hash Function.
+    A **PEP 247: Cryptographic Hash Function** compliant
+    **Hash Function Interface**.
     """
     def __init__(self, string=None):
         self._native_object = _ffi.new(self._native_type)
@@ -33,22 +34,19 @@ class _Hash(object):
         if ret < 0:
             raise WolfCryptError("Hash init error (%d)" % ret)
 
+        if (string):
+            self.update(string)
+
 
     @classmethod
     def new(cls, string=None):
         """
         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.
+        **string** parameter, if supplied, will be immediately
+        hashed into the object's starting state, as if
+        obj.update(string) was called.
         """
-        self = cls(string)
-
-        if (string):
-            self.update(string)
-
-        return self
-
+        return cls(string)
 
 
     def copy(self):
@@ -110,6 +108,11 @@ class _Hash(object):
 
 
 class Sha(_Hash):
+    """
+    **SHA-1** is a cryptographic hash function standardized by **NIST**.
+
+    It produces an [ **160-bit | 20 bytes** ] message digest.
+    """
     digest_size  = 20
     _native_type = "Sha *"
     _native_size = _ffi.sizeof("Sha")
@@ -128,6 +131,12 @@ class Sha(_Hash):
 
 
 class Sha256(_Hash):
+    """
+    **SHA-256** is a cryptographic hash function from the **SHA-2 family** and
+    is standardized by **NIST**.
+
+    It produces a [ **256-bit | 32 bytes** ] message digest.
+    """
     digest_size  = 32
     _native_type = "Sha256 *"
     _native_size = _ffi.sizeof("Sha256")
@@ -146,6 +155,12 @@ class Sha256(_Hash):
 
 
 class Sha384(_Hash):
+    """
+    **SHA-384** is a cryptographic hash function from the **SHA-2 family** and
+    is standardized by **NIST**.
+
+    It produces a [ **384-bit | 48 bytes** ] message digest.
+    """
     digest_size  = 48
     _native_type = "Sha384 *"
     _native_size = _ffi.sizeof("Sha384")
@@ -164,6 +179,12 @@ class Sha384(_Hash):
 
 
 class Sha512(_Hash):
+    """
+    **SHA-512** is a cryptographic hash function from the **SHA-2 family** and
+    is standardized by **NIST**.
+
+    It produces a [ **512-bit | 64 bytes** ] message digest.
+    """
     digest_size  = 64
     _native_type = "Sha512 *"
     _native_size = _ffi.sizeof("Sha512")
@@ -191,12 +212,16 @@ _HMAC_TYPES = [_TYPE_SHA, _TYPE_SHA256, _TYPE_SHA384, _TYPE_SHA512]
 
 
 class _Hmac(_Hash):
+    """
+    A **PEP 247: Cryptographic Hash Function** compliant
+    **Keyed Hash Function Interface**.
+    """
     digest_size  = None
     _native_type = "Hmac *"
     _native_size = _ffi.sizeof("Hmac")
 
 
-    def __init__(self, key):
+    def __init__(self, key, string=None):
         key = t2b(key)
 
         self._native_object = _ffi.new(self._native_type)
@@ -204,22 +229,21 @@ class _Hmac(_Hash):
         if ret < 0:
             raise WolfCryptError("Hmac init error (%d)" % ret)
 
+        if (string):
+            self.update(string)
+
+
 
     @classmethod
     def new(cls, key, string=None):
         """
-        Creates 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
-        if obj.update(string) was called.
+        to use. The optional **string** parameter, if supplied,
+        will be immediately hashed into the object's starting
+        state, as if obj.update(string) was called.
         """
-        self = cls(key)
-
-        if (string):
-            self.update(string)
-
-        return self
+        return cls(key, string)
 
 
     def _init(self, type, key):
@@ -235,20 +259,40 @@ class _Hmac(_Hash):
 
 
 class HmacSha(_Hmac):
+    """
+    A HMAC function using **SHA-1** as it's cryptographic hash function.
+
+    It produces a [ **512-bit | 64 bytes** ] message digest.
+    """
     _type = _TYPE_SHA
     digest_size = Sha.digest_size
 
 
 class HmacSha256(_Hmac):
+    """
+    A HMAC function using **SHA-256** as it's cryptographic hash function.
+
+    It produces a [ **512-bit | 64 bytes** ] message digest.
+    """
     _type = _TYPE_SHA256
     digest_size = Sha256.digest_size
 
 
 class HmacSha384(_Hmac):
+    """
+    A HMAC function using **SHA-384** as it's cryptographic hash function.
+
+    It produces a [ **512-bit | 64 bytes** ] message digest.
+    """
     _type = _TYPE_SHA384
     digest_size = Sha384.digest_size
 
 
 class HmacSha512(_Hmac):
+    """
+    A HMAC function using **SHA-512** as it's cryptographic hash function.
+
+    It produces a [ **512-bit | 64 bytes** ] message digest.
+    """
     _type = _TYPE_SHA512
     digest_size = Sha512.digest_size