python-aead is a implementation of an algorithm for authenticated encryption with associated data (AEAD). It uses the AES cipher in CBC mode and HMAC-SHA256 for message authentication. It is based on an [IETF Internet Draft] (http://tools.ietf.org/html/draft-mcgrew-aead-aes-cbc-hmac-sha2-05#page-31) from David McGrew.
python-aead aims to be opinionated about algorithm choice. It is essentially AES_128_CBC_HMAC_SHA_256. If more flexibility is required, I highly recommend using the PyCA cryptography library that provides the cryptographic primitives python-aead uses.
python-aead supports and is tested against Python versions 2.6 - 3.4 as well as PyPy.
python-aead aims to provide a very simple interface. The module contains a single class that can be imported.
from aead import AEADAn encryption key is required to initialize the object. The key has to be 32 bytes long and encoded with base64url as specified in RFC 4648. The library provides a convenient method for generating a random key but any key meeting the criteria can be used.
cryptor = AEAD(AEAD.generate_key())After initializing the object, encrypting data is a simple matter. The
.encrypt() method takes two parameters, the first being the data you want to
encrypt and the second being associated data that you want to authenticate but
not encrypt.
ct = cryptor.encrypt(b"Hello, World!", b"Additional Data").encrypt() returns a base64url encoded cipher text.
Decrypting the cipher text is a simple matter as well. The .decrypt() method
takes two parameters, the first being the cipher text that needs decrypting and
the second being the associated data that was authenticated.
cryptor.decrypt(ct, b"Additional Data")If the cipher text is corrupted or the associated data provided during the
decryption process does not match the associated data provided during
encryption, a ValueError is raised.
python-aead is made available under both the BSD and Apache Software License
Version 2.0 licenses. See the LICENSE.BSD and LICENSE.APACHE files for the
exact terms of the license.
python-aead welcomes any bug reports, fixes and suggestions. If an issue is security-sensitive, please email me directly at terrycwk1994@gmail.com.
If contributing a patch, please adhere to the following guidelines:
- Follow PEP 8. The test suite runs a flake8 lint to catch any issues.
- Keep patches small to ease the review process. Bigger patches can be broken up in logical chunks.
- Ensure that test coverage remains at 100%.