Abstract

This document specifies a standard API for secret-key blockencryption algorithms such as DES or Rijndael, making it easier toswitch between different algorithms and implementations.

Introduction

Encryption algorithms transform their input data (calledplaintext) in some way that is dependent on a variable key,producing ciphertext. The transformation can easily be reversedif and only if one knows the key. The key is a sequence of bitschosen from some very large space of possible keys. There are twoclasses of encryption algorithms: block ciphers and stream ciphers.

Block ciphers encrypt multibyte inputs of a fixed size (frequently8 or 16 bytes long), and can be operated in various feedbackmodes. The feedback modes supported in this specification are:

These modes are to be implemented as described in NIST publicationSP 800-38A[1]. Descriptions of the first three feedback modes canalso be found in Bruce Schneier’s bookApplied Cryptography[2].

(The numeric value 4 is reserved for MODE_PGP, a variant of CFBdescribed inRFC 2440: “OpenPGP Message Format”. This modeisn’t considered important enough to make it worth requiring itfor all block encryption ciphers, though supporting it is a niceextra feature.)

In a strict formal sense, stream ciphers encrypt data bit-by-bit;practically, stream ciphers work on a character-by-characterbasis. This PEP only aims at specifying an interface for blockciphers, though stream ciphers can support the interface describedhere by fixing ‘block_size’ to 1. Feedback modes also don’t makesense for stream ciphers, so the only reasonable feedback modewould be ECB mode.

Specification

Encryption modules can add additional functions, methods, andattributes beyond those described in this PEP, but all of thefeatures described in this PEP must be present for a module toclaim compliance with it.

Secret-key encryption modules should define one function:

new(key,mode,[IV],**kwargs)

Returns a ciphering object, using the secret key contained in thestring ‘key’, and using the feedback mode ‘mode’, which must beone of the constants from the table above.

If ‘mode’ is MODE_CBC or MODE_CFB, ‘IV’ must be provided and mustbe a string of the same length as the block size. Not providing avalue of ‘IV’ will result in aValueError exception being raised.

Depending on the algorithm, a module may support additionalkeyword arguments to this function. Some keyword arguments arespecified by this PEP, and modules are free to add additionalkeyword arguments. If a value isn’t provided for a given keyword,a secure default value should be used. For example, if analgorithm has a selectable number of rounds between 1 and 16, and1-round encryption is insecure and 8-round encryption is believedsecure, the default value for ‘rounds’ should be 8 or more.(Module implementors can choose a very slow but secure value, too,such as 16 in this example. This decision is left up to theimplementor.)

The following table lists keyword arguments defined by this PEP:

The Counter feedback mode requires a sequence of input blocks,called counters, that are used to produce the output. When ‘mode’is MODE_CTR, the ‘counter’ keyword argument must be provided, andits value must be a callable object, such as a function or method.Successive calls to this callable object must return a sequence ofstrings that are of the length ‘block_size’ and that neverrepeats. (Appendix B of the NIST publication gives a way togenerate such a sequence, but that’s beyond the scope of thisPEP.)

The CFB mode operates on segments of the plaintext and ciphertextthat are ‘segment_size’ bits long. Therefore, when using thismode, the input and output strings must be a multiple of‘segment_size’ bits in length. ‘segment_size’ must be an integerbetween 1 and block_size*8, inclusive. (The factor of 8 comesfrom ‘block_size’ being measured in bytes and not in bits). Thedefault value for this parameter should be block_size*8.Implementors are allowed to constrain ‘segment_size’ to be amultiple of 8 for simplicity, but they’re encouraged to supportarbitrary values for generality.

Secret-key encryption modules should define two variables:

• block_size

  An integer value; the size of the blocks encrypted by thismodule, measured in bytes. For all feedback modes, the lengthof strings passed to the encrypt() and decrypt() must be amultiple of the block size.

• key_size

  An integer value; the size of the keys required by thismodule, measured in bytes. If key_size is None, then thealgorithm accepts variable-length keys. This may mean themodule accepts keys of any random length, or that there are afew different possible lengths, e.g. 16, 24, or 32 bytes. Youcannot pass a key of length 0 (that is, the null string ‘’) asa variable-length key.

Cipher objects should have two attributes:

• block_size

  An integer value equal to the size of the blocks encrypted bythis object. For algorithms with a variable block size, thisvalue is equal to the block size selected for this object.

• IV

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

Cipher objects require the following methods:

• decrypt(string)

  Decrypts ‘string’, using the key-dependent data in the objectand with the appropriate feedback mode. The string’s lengthmust be an exact multiple of the algorithm’s block size or, inCFB mode, of the segment size. Returns a string containingthe plaintext.

• encrypt(string)

  Encrypts a non-empty string, using the key-dependent data inthe object, and with the appropriate feedback mode. Thestring’s length must be an exact multiple of the algorithm’sblock size or, in CFB mode, of the segment size. Returns astring containing the ciphertext.

Here’s an example, using a module named ‘DES’:

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

References

Changes

2002-04: Removed references to stream ciphers; retitled PEP;prefixed feedback mode constants withMODE_; removed PGP feedbackmode; added CTR and OFB feedback modes; clarified where numbersare measured in bytes and where in bits.

2002-09: Clarified the discussion of key length by using“variable-length keys” instead of “arbitrary-length”.

Acknowledgements

Thanks to the readers of the python-crypto list for their comments onthis PEP.

Copyright

This document has been placed in the public domain.