Merge branch 'release-0.4' into develop

Author: Synss

README.rst

@@ -53,6 +53,12 @@ Building `python-mbedtls` requires Cython::
 
 then,
 
+::
+
+   python3 -m pip install python-mbedtls
+
+or
+
 ::
 
 	git clone https://github.com/Synss/python-mbedtls.git python-mbedtls.git
@@ -68,16 +74,70 @@ The unit tests further require `nose` and `pyCrypto`::
 Hashing module (`md.h`)
 -----------------------
 
-The hashing module is wrapped, which provides message, file, and HMAC
-with the following algorithms: MD5, SHA-1, SHA-2, and RIPEMD-160.
+Message digest algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `mbedtls.hash` module provides MD5, SHA-1, SHA-2, and RIPEMD-160 secure
+hashes and message digests.  The API follows the recommendations from PEP 452
+so that it can be used as a drop-in replacement to e.g. `hashlib` or
+`PyCrypto`.
+
+Here are the examples from `hashlib` executed with `python-mbedtls`::
+
+    >>> from mbedtls import hash as hashlib
+    >>> m = hashlib.md5()
+    >>> m.update(b"Nobody inspects")
+    >>> m.update(b" the spammish repetition")
+    >>> m.digest()
+    b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
+    >>> m.digest_size
+    16
+    >>> m.block_size
+    64
+
+More condensed::
+
+   >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
+   'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
+
+Using `new()`::
+
+   >>> h = hashlib.new('ripemd160')
+   >>> h.update(b"Nobody inspects the spammish repetition")
+   >>> h.hexdigest()
+   'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
+
 
-The API follows the recommendations from PEP 452.
+HMAC algorithm
+~~~~~~~~~~~~~~
+
+The `mbedtls.hmac` module computes HMAC.  The API follows the recommendations
+from PEP 452 as well.
+
+Example::
+
+   >>> from mbedtls import hmac
+   >>> m = hmac.new(b"This is my secret key", digestmod="md5")
+   >>> m.update(b"Nobody inspects")
+   >>> m.update(b" the spammish repetition")
+   >>> m.digest()
+   b'\x9d-/rj\\\x98\x80\xb1rG\x87\x0f\xe9\xe4\xeb'
+
+.. warning::
+
+   The message is cleared after calculation of the digest.  Only call
+   :meth:`mbedtls.hmac.Hmac.digest` or :meth:`mbedtls.hmac.Hmac.hexdigest` once
+   per message.
 
 
 Symmetric cipher module (`cipher.h`)
 ------------------------------------
 
-The symmetric cipher module is wrapped, which provides:
+The `mbedtls.cipher` module provides symmetric encryption.  The API follows the
+recommendations from PEP 272 so that it can be used as a drop-in replacement to
+e.g. `PyCrypto`.
+
+mbedtls provides the following algorithms:
 
 - Aes encryption/decryption (128, 192, and 256 bits) in ECB, CBC, CFB128,
   CTR, GCM, or CCM mode;
@@ -87,27 +147,60 @@ The symmetric cipher module is wrapped, which provides:
   CFB128, CTR, GCM, or CCM mode;
 - DES encryption/decryption in ECB, or CBC mode;
 
-The API follows the recommendations from PEP 272.
-
 Notes:
    - Tagging and padding are not wrapped.
    - The counter in CTR mode cannot be explicitly provided.
 
+Example::
+
+   >>> from mbedtls import cipher
+   >>> c = cipher.AES.new(b"My 16-bytes key.", cipher.MODE_CBC, b"CBC needs an IV.")
+   >>> enc = c.encrypt(b"This is a super-secret message!")
+   >>> enc
+   b'*`k6\x98\x97=[\xdf\x7f\x88\x96\xf5\t\x19J7\x93\xb5\xe0~\t\x9e\x968m\xcd\x
+   >>> c.decrypt(enc)
+   b'This is a super-secret message!'
+
 
 Public key module (`pk.h`)
 --------------------------
 
-The RSA cryptosystem is wrapped, which provides:
+The `mbedtls.pk` module provides the RSA cryptosystem.  This includes:
 
 - Public-private key generation and key import/export in PEM and DER
   formats;
 - Asymmetric encryption and decryption;
 - Message signature and verification.
 
-
-Contribution
-============
-
-`python-mbedtls` is in an early stage of development and contributions
-in any form is welcome.  Note, however, that bugs against mbed TLS
-should be reported upstream directly.
+Key generation, the default size is 2048 bits::
+
+   >>> from mbedtls import pk
+   >>> rsa = pk.RSA()
+   >>> rsa.has_private()
+   False
+   >>> rsa.generate()
+   >>> rsa.key_size
+   256
+   >>> rsa.has_private() and rsa.has_public()
+   True
+
+Message encryption and decryption::
+
+   >>> enc = rsa.encrypt(b"secret message")
+   >>> rsa.decrypt(enc)
+   b"secret message"
+
+Message signature and verification::
+
+   >>> sig = rsa.sign(b"Please sign here.")
+   >>> rsa.verify(b"Please sign here.", sig)
+   True
+   >>> rsa.verify(b"Sorry, wrong message.", sig)
+   False
+   >>> prv, pub = rsa.export(format="DER")
+   >>> other = pk.RSA()
+   >>> other.import_(pub)
+   >>> other.has_private()
+   False
+   >>> other.verify(b"Please sign here.", sig)
+   True

docs/conf.py

@@ -67,9 +67,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = '0.3'
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

mbedtls/__init__.pyx

@@ -0,0 +1,16 @@
+"""python-mbedtls is a this wrapper to ARM's mbed TLS library."""
+
+__author__ = "Mathias Laurin"
+__copyright__ = "Copyright 2015, Elaborated Networks GmbH"
+__license__ = "MIT License"
+
+
+import mbedtls.cipher as cipher
+import mbedtls.exceptions as exceptions
+import mbedtls.hash as hash
+import mbedtls.hmac as hmac
+import mbedtls.pk as pk
+import mbedtls.random as random
+
+
+__all__ = "cipher", "exceptions", "hash", "hmac", "pk", "random"

mbedtls/_md.pxd

@@ -56,7 +56,7 @@ cdef extern from "mbedtls/md.h":
     int mbedtls_md_hmac_finish(
         mbedtls_md_context_t *ctx,
         unsigned char *output)
-    # mbedtls_md_hmac_reset
+    int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx)
     # mbedtls_md_hmac
 
 

mbedtls/hmac.pyx

@@ -27,6 +27,10 @@ cdef class Hmac(_md.MDBase):
         key (bytes): The key to use.
         name (bytes): The MD name known to mbed TLS.
 
+    Warning:
+        The message is cleared after calculation of the digest.  Only
+        call :meth:`digest` or :meth:`hexdigest` once per message.
+
     Attributes:
         digest_size (int): The size of the message digest, in bytes.
         block_size (int): Not implemented.
@@ -46,7 +50,10 @@ cdef class Hmac(_md.MDBase):
 
     cdef _finish(self, unsigned char *output):
         """Return the HMAC of key and message."""
-        return _md.mbedtls_md_hmac_finish(&self._ctx, output)
+        ret = _md.mbedtls_md_hmac_finish(&self._ctx, output)
+        if ret != 0:
+            return ret
+        return _md.mbedtls_md_hmac_reset(&self._ctx)
 
     cpdef copy(self):
         """Return a copy ("clone") of the HMAC object.
@@ -70,45 +77,45 @@ def new(key, buffer=None, digestmod=None):
 
 def md2(key, buffer=None):
     """MD2 message-digest algorithm."""
-    return Hash(key, buffer, digestmod="md2")
+    return Hmac(key, "md2", buffer)
 
 
 def md4(key, buffer=None):
     """MD4 message-digest algorithm."""
-    return Hash(key, buffer, digestmod="md4")
+    return Hmac(key, "md4", buffer)
 
 
 def md5(key, buffer=None):
     """MD5 message-digest algorithm."""
-    return Hash(key, buffer, digestmod="md5")
+    return Hmac(key, "md5", buffer)
 
 
 def sha1(key, buffer=None):
-    """Secure Hash Algorithm 1 (SHA-1)."""
-    return Hash(key, buffer, digestmod="sha1")
+    """Secure Hmac Algorithm 1 (SHA-1)."""
+    return Hmac(key, "sha1", buffer)
 
 
 def sha224(key, buffer=None):
-    """Secure Hash Algorithm 2 (SHA-2) with 224 bits hash value."""
-    return Hash(key, buffer, digestmod="sha224")
+    """Secure Hmac Algorithm 2 (SHA-2) with 224 bits hash value."""
+    return Hmac(key, "sha224", buffer)
 
 
 def sha256(key, buffer=None):
-    """Secure Hash Algorithm 2 (SHA-2) with 256 bits hash value."""
-    return Hash(key, buffer, digestmod="sha256")
+    """Secure Hmac Algorithm 2 (SHA-2) with 256 bits hash value."""
+    return Hmac(key, "sha256", buffer)
 
 
 def sha384(key, buffer=None):
-    """Secure Hash Algorithm 2 (SHA-2) with 384 bits hash value."""
-    return Hash(key, buffer, digestmod="sha384")
+    """Secure Hmac Algorithm 2 (SHA-2) with 384 bits hash value."""
+    return Hmac(key, "sha384", buffer)
 
 
 def sha512(key, buffer=None):
-    """Secure Hash Algorithm 2 (SHA-2) with 512 bits hash value."""
-    return Hash(key, buffer, digestmod="sha512")
+    """Secure Hmac Algorithm 2 (SHA-2) with 512 bits hash value."""
+    return Hmac(key, "sha512", buffer)
 
 
 def ripemd160(key, buffer=None):
     """RACE Integrity Primitives Evaluation Message Digest (RIPEMD) with
     160 bits hash value."""
-    return Hash(key, buffer, digestmod="ripemd160")
+    return Hmac(key, "ripemd160", buffer)

setup.py

@@ -2,7 +2,7 @@
 from Cython.Build import cythonize
 
 
-version = "0.3"
+version = "0.4"
 download_url = "https://github.com/Synss/python-mbedtls/tarball/%s" % version
 
 
@@ -45,7 +45,7 @@
     ext_modules=cythonize(extensions),
     setup_requires=setup_requires,
     classifiers=[
-        "Development Status :: 3 - Alpha",
+        "Development Status :: 4 - Beta",
         "Programming Language :: Cython",
         "License :: OSI Approved :: MIT License",
         "Topic :: Security :: Cryptography",

tests/test_md.py

@@ -127,7 +127,7 @@ def test_check_against_hmac_buf():
         yield test
 
 
-def test_instantiation():
+def test_hash_instantiation():
     import inspect
 
     def check_instantiation(fun, name):
@@ -139,5 +139,22 @@ def check_instantiation(fun, name):
     for name, member in inspect.getmembers(md_hash):
         if name in md_hash.algorithms_available:
             test = partial(check_instantiation, member, name)
-            test.description = "check_instantiation(%s)" % name
+            test.description = "check_hash_instantiation(%s)" % name
+            yield test
+
+
+def test_hmac_instantiation():
+    import inspect
+
+    def check_instantiation(fun, name):
+        key = _rnd(16)
+        alg1 = fun(key)
+        alg2 = md_hmac.new(key, digestmod=name)
+        assert_equal(type(alg1), type(alg2))
+        assert_equal(alg1.name, alg2.name)
+
+    for name, member in inspect.getmembers(md_hmac):
+        if name in md_hmac.algorithms_available:
+            test = partial(check_instantiation, member, name)
+            test.description = "check_hmac_instantiation(%s)" % name
             yield test