3 Crypto.Cipher: Encryption Algorithms

Encryption algorithms transform their input data, or plaintext, in some way that is dependent on a variable key, producing ciphertext. This transformation can easily be reversed, if (and, hopefully, only if) one knows the key. The key can be varied by the user or application and chosen from some very large space of possible keys.

For a secure encryption algorithm, it should be very difficult to determine the original plaintext without knowing the key; usually, no clever attacks on the algorithm are known, so the only way of breaking the algorithm is to try all possible keys. Since the number of possible keys is usually of the order of 2 to the power of 56 or 128, this is not a serious threat, although 2 to the power of 56 is now considered insecure in the face of custom-built parallel computers and distributed key guessing efforts.

Block ciphers take multibyte inputs of a fixed size (frequently 8 or 16 bytes long) and encrypt them. Block ciphers can be operated in various modes. The simplest is Electronic Code Book (or ECB) mode. In this mode, each block of plaintext is simply encrypted to produce the ciphertext. This mode can be dangerous, because many files will contain patterns greater than the block size; for example, the comments in a C program may contain long strings of asterisks intended to form a box. All these identical blocks will encrypt to identical ciphertext; an adversary may be able to use this structure to obtain some information about the text.

To eliminate this weakness, there are various feedback modes in which the plaintext is combined with the previous ciphertext before encrypting; this eliminates any repetitive structure in the ciphertext.

One mode is Cipher Block Chaining (CBC mode); another is Cipher FeedBack (CFB mode). CBC mode still encrypts in blocks, and thus is only slightly slower than ECB mode. CFB mode encrypts on a byte-by-byte basis, and is much slower than either of the other two modes. The chaining feedback modes require an initialization value to start off the encryption; this is a string of the same length as the ciphering algorithm's block size, and is passed to the new() function. There is also a special PGP mode, which is an oddball variant of CFB used by the PGP program. While you can use it in non-PGP programs, it's quite non-standard.

The currently available block ciphers are listed in the following table, and are in the Crypto.Cipher package:

Cipher  Key Size/Block Size 
AES 16, 24, or 32 bytes/16 bytes
ARC2 Variable/8 bytes
Blowfish Variable/8 bytes
CAST Variable/8 bytes
DES 8 bytes/8 bytes
DES3 (Triple DES) 16 bytes/8 bytes
IDEA 16 bytes/8 bytes
RC5 Variable/8 bytes

In a strict formal sense, stream ciphers encrypt data bit-by-bit; practically, stream ciphers work on a character-by-character basis. Stream ciphers use exactly the same interface as block ciphers, with a block length that will always be 1; this is how block and stream ciphers can be distinguished. The only feedback mode available for stream ciphers is ECB mode.

The currently available stream ciphers are listed in the following table:

Cipher  Key Size 
Cipher Key Size
ARC4 Variable
XOR Variable

ARC4 is short for `Alleged RC4'. In September of 1994, someone posted C code to both the Cypherpunks mailing list and to the Usenet newsgroup sci.crypt, claiming that it implemented the RC4 algorithm. This claim turned out to be correct. Note that there's a damaging class of weak RC4 keys; this module won't warn you about such keys.

A similar anonymous posting was made for Alleged RC2 in January, 1996.

An example usage of the DES module:

>>> from Crypto.Cipher import DES
>>> obj=DES.new('abcdefgh', DES.MODE_ECB)
>>> plain="Guido van Rossum is a space alien."
>>> len(plain)
34
>>> obj.encrypt(plain)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: Strings for DES must be a multiple of 8 in length
>>> ciph=obj.encrypt(plain+'XXXXXX')
>>> ciph
'\021,\343Nq\214DY\337T\342pA\372\255\311s\210\363,\300j\330\250\312\347\342I\3215w\03561\303dgb/\006'
>>> obj.decrypt(ciph)
'Guido van Rossum is a space alien.XXXXXX'

All cipher algorithms share a common interface. After importing a given module, there is exactly one function and two variables available.

new(key, mode[, IV])
Returns a ciphering object, using key and feedback mode mode. If mode is MODE_CBC or MODE_CFB, IV must be provided, and must be a string of the same length as the block size. Some algorithms support additional keyword arguments to this function; see the "Algorithm-specific Notes for Encryption Algorithms" section below for the details.

block_size
An integer value; the size of the blocks encrypted by this module. Strings passed to the encrypt and decrypt functions must be a multiple of this length. For stream ciphers, block_size will be 1.

key_size
An integer value; the size of the keys required by this module. If key_size is zero, then the algorithm accepts arbitrary-length keys. You cannot pass a key of length 0 (that is, the null string '' as such a variable-length key.

All cipher objects have at least three attributes:

block_size
An integer value equal to the size of the blocks encrypted by this object. Identical to the module variable of the same name.

IV
Contains the initial value which will be used to start a cipher feedback mode. After encrypting or decrypting a string, this value will reflect the modified feedback text; it will always be one block in length. It is read-only, and cannot be assigned a new value.

key_size
An integer value equal to the size of the keys used by this object. If key_size is zero, then the algorithm accepts arbitrary-length keys. For algorithms that support variable length keys, this will be 0. Identical to the module variable of the same name.

All ciphering objects have the following methods:

decrypt(string)
Decrypts string, using the key-dependent data in the object, and with the appropriate feedback mode. The string's length must be an exact multiple of the algorithm's block size. Returns a string containing the plaintext.

encrypt(string)
Encrypts a non-null string, using the key-dependent data in the object, and with the appropriate feedback mode. The string's length must be an exact multiple of the algorithm's block size; for stream ciphers, the string can be of any length. Returns a string containing the ciphertext.


Subsections