xxtea 1.3.0

Installation

$ pip install xxtea -U

Usage

This module provides four functions: encrypt(), decrypt(), encrypt_hex(), and decrypt_hex().

Python 2:

>>> import os
>>> import xxtea
>>>
>>> key = os.urandom(16)  # Key must be a 16-byte string.
>>> s = "xxtea is good"
>>>
>>> enc = xxtea.encrypt(s, key)
>>> dec = xxtea.decrypt(enc, key)
>>> s == dec
True
>>>
>>> hexenc = xxtea.encrypt_hex(s, key)
>>> hexenc
'd1d8e82461dd5828397c32ad265ee225'
>>> s == xxtea.decrypt_hex(hexenc, key)
True
>>>
>>> enc.encode('hex') == hexenc
True

Python 3:

>>> import os
>>> import xxtea
>>> import binascii
>>>
>>> key = os.urandom(16)  # Key must be a 16-byte string.
>>> s = b"xxtea is good"
>>>
>>> enc = xxtea.encrypt(s, key)
>>> dec = xxtea.decrypt(enc, key)
>>> s == dec
True
>>>
>>> hexenc = xxtea.encrypt_hex(s, key)
>>> hexenc
b'7ad85672d770fb5cf636c49d57e732ae'
>>> s == xxtea.decrypt_hex(hexenc, key)
True
>>>
>>> binascii.hexlify(enc) == hexenc
True

encrypt_hex() and decrypt_hex() operate on ciphertext in a hexadecimal representation. They are exactly equivalent to:

Python 2:

>>> hexenc = xxtea.encrypt(s, key).encode('hex')
>>> s == xxtea.decrypt(hexenc.decode('hex'), key)
True

Python 3:

>>> hexenc = binascii.hexlify(xxtea.encrypt(s, key))
>>> s == xxtea.decrypt(binascii.unhexlify(hexenc), key)
True

Padding

Padding is enabled by default, in this case you can encode any bytes of any length.

>>> xxtea.encrypt_hex('', key)
'd63256eb59134f1f'
>>> xxtea.decrypt_hex(_, key)
''
>>> xxtea.encrypt_hex(' ', key)
'97009bd24074a7a5'
>>> xxtea.decrypt_hex(_, key)
' '

You can disable padding by setting padding parameter to False. In this case data will not be padded, so data length must be a multiple of 4 bytes and must not be less than 8 bytes. Otherwise ValueError will be raised.

>>> xxtea.encrypt_hex('', key, padding=False)
ValueError: Data length must be a multiple of 4 bytes and must not be less than 8 bytes
>>> xxtea.encrypt_hex('xxtea is good', key, padding=False)
ValueError: Data length must be a multiple of 4 bytes and must not be less than 8 bytes
>>> xxtea.encrypt_hex('12345678', key, padding=False)
'64f4e969ba90d386'
>>> xxtea.decrypt_hex(_, key, padding=False)
'12345678'

Rounds

By default xxtea manipulates the input data for 6 + 52 / n rounds, where n denotes how many 32-bit integers data can fit in. We can specify it manually by setting rounds parameter.

Python2:

>>> import xxtea
>>> import string
>>> data = string.digits
>>> key = string.ascii_letters[:16]
>>> xxtea.encrypt_hex(data, key)
'5b80b08a5d1923e4cd992dd5'
>>> xxtea.encrypt_hex(data, key, rounds=23)
'5b80b08a5d1923e4cd992dd5'
>>> xxtea.encrypt_hex(data, key, rounds=1024)
'1577bbf28c43ced93bd50720'

Python3:

>>> import xxtea
>>> import string
>>> data = string.digits
>>> key = string.ascii_letters[:16]
>>> xxtea.encrypt_hex(data, key)
b'5b80b08a5d1923e4cd992dd5'
>>> xxtea.encrypt_hex(data, key, rounds=23)
b'5b80b08a5d1923e4cd992dd5'
>>> xxtea.encrypt_hex(data, key, rounds=1024)
b'1577bbf28c43ced93bd50720'

Catching Exceptions

It is possible to throw a ValueError or a TypeError during calling decrypt() and decrypt_hex(). Better to catch them, or your program will exit.

>>> from __future__ import print_function
>>> import xxtea
>>>
>>> def try_catch(func, *args, **kwargs):
...     try:
...         func(*args, **kwargs)
...     except Exception as e:
...         print(e.__class__.__name__, ':', e)
...
...
...
>>> try_catch(xxtea.decrypt, '', key='')
ValueError : Need a 16-byte key.
>>> try_catch(xxtea.decrypt, '', key=' '*16)
ValueError : Invalid data, data length is not a multiple of 4, or less than 8.
>>> try_catch(xxtea.decrypt, ' '*8, key=' '*16)
ValueError : Invalid data, illegal PKCS#7 padding. Could be using a wrong key.
>>> try_catch(xxtea.decrypt_hex, ' '*8, key=' '*16)
TypeError : Non-hexadecimal digit found
>>> try_catch(xxtea.decrypt_hex, 'abc', key=' '*16)
TypeError : Odd-length string
>>> try_catch(xxtea.decrypt_hex, 'abcd', key=' '*16)
ValueError : Invalid data, data length is not a multiple of 4, or less than 8.

CHANGELOG