Skip to main content

mbed TLS (PolarSSL) wrapper

Project description

==========================
Python wrapper to mbed TLS
==========================

`python-mbedtls`_ is a thin wrapper to ARM's mbed TLS library.

According to the `official mbed TLS website`_

mbed TLS (formerly known as PolarSSL) makes it trivially easy for
developers to include cryptographic and SSL/TLS capabilities in their
(embedded) products, facilitating this functionality with a minimal
coding footprint.

.. _python-mbedtls: https://synss.github.io/python-mbedtls
.. _official mbed TLS website: https://tls.mbed.org


License
=======

`python-mbedtls` is licensed under the MIT License (see LICENSE.txt). This
enables the use of `python-mbedtls` in both open source and closed source
projects. The MIT License is compatible with both GPL and Apache 2.0 license
under which mbed TLS is distributed.


Installation
============

The wrapper is currently developed and tested on Debian Jessie and targets
Python 3.4. It probably works with earlier Python releases although this was
not tested.


mbed TLS
--------

`python-mbedtls` requires the mbed TLS library that can be installed
with::

git clone https://github.com/ARMmbed/mbedtls.git mbedtls.git
cd mbedtls.git
SHARED=1 make no_test
sudo make install


python-mbedtls
--------------

Building `python-mbedtls` requires Cython::

python3 -m pip install cython

then,

::

python3 -m pip install python-mbedtls

or

::

git clone https://github.com/Synss/python-mbedtls.git python-mbedtls.git
cd python-mbedtls.git
python3 setup.py build_ext

The unit tests further require `nose` and `pyCrypto`::

python3 -m pip install nose pycrypto
nosetests -v tests


Hashing module (`md.h`)
-----------------------

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'


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 `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;
- Arc4 encryption/decryption;
- Blowfish encryption/decryption in ECB, CBC, CFB64, or CTR mode;
- Camellia encryption/decryption (128, 192, and 256 bits) in ECB, CBC,
CFB128, CTR, GCM, or CCM mode;
- DES encryption/decryption in ECB, or CBC mode;

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 `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.

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-mbedtls-0.5.tar.gz (739.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page