Python Cryptography Toolkit

Version 2.3

Version 2.7a1

The Python Cryptography Toolkit describes a package containing various cryptographic modules for the Python programming language. This documentation assumes you have some basic knowledge about the Python language, but not necessarily about cryptography.

Contents

Introduction

Introduction

Design Goals

Introduction

Design Goals

The Python cryptography toolkit is intended to provide a reliable and stable base for writing Python programs that require cryptographic functions.

@@ -379,9 +624,9 @@ PEP 272, "API for Block Encryption Algorithms".

This is intended to make it easy to replace old algorithms with newer, more secure ones. If you're given a bit of portably-written Python code that uses the DES encryption algorithm, you should be able to use -AES instead by simply changing from Crypto.Cipher import DES to -from Crypto.Cipher import AES, and changing all references to -DES.new() to AES.new(). It's also fairly simple to +AES instead by simply changing from Crypto.Cipher import DES to +from Crypto.Cipher import AES, and changing all references to +DES.new() to AES.new(). It's also fairly simple to write your own modules that mimic this interface, thus letting you use combinations or permutations of algorithms.

Some modules are implemented in C for performance; others are written @@ -418,9 +663,9 @@ just interested in keeping your co-workers or your relatives out of your files, any of the components here could be used.

This document is very much a work in progress. If you have any questions, comments, complaints, or suggestions, please send them to me.

Acknowledgements

+ +

Acknowledgements

Much of the code that actually implements the various cryptographic algorithms was not written by me. I'd like to thank all the people who implemented them, and released their work under terms which allowed me @@ -429,10 +674,10 @@ chapters of this documentation. Bruce Schneier's book Applied Cryptography was also very useful in writing this toolkit; I highly recommend it if you're interested in learning more about cryptography.

Good luck with your cryptography hacking!

Crypto.Hash: Hash Functions

+ + +

Crypto.Hash: Hash Functions

Hash functions take arbitrary strings as input, and produce an output of fixed size that is dependent on the input; it should never be possible to derive the input data given only the hash function's @@ -447,79 +692,116 @@ cryptographically secure hash functions include MD2, MD5, and SHA1.

Hash functions can be used simply as a checksum, or, in association with a public-key algorithm, can be used to implement digital signatures.

The hashing algorithms currently implemented are:

- +

--+++ - - - + + + + - - - + + + + - - + + + - - + + + - - + + + - - + + + - - + + +

Hash function	Digest length
Hash function	Digest length	Security
MD2	128 bits
MD2	128 bits	Insecure, do not use
MD4	128 bits
MD4	128 bits	Insecure, do not use
MD5	128 bits
MD5	128 bits	Insecure, do not use
RIPEMD	160 bits
RIPEMD160	160 bits	Secure.
SHA1	160 bits
SHA1	160 bits	SHA1 is shaky. Walk, do not run, away from SHA1.
SHA256	256 bits
SHA256	256 bits	Secure.

All hashing modules share the same interface. After importing a given -hashing module, call the new() function to create a new -hashing object. You can now feed arbitrary strings into the object -with the update() method, and can ask for the hash value at -any time by calling the digest() or hexdigest() -methods. The new() function can also be passed an optional +

Resources: +On SHA1 (in)security: http://www.schneier.com/blog/archives/2005/02/cryptanalysis_o.html +SHA1 phase-out by 2010: http://csrc.nist.gov/groups/ST/toolkit/documents/shs/hash_standards_comments.pdf +On MD5 insecurity: http://www.schneier.com/blog/archives/2008/12/forging_ssl_cer.html

Crypto.Hash.HMAC implements the RFC-2104 HMAC algorithm. The HMAC module is +a copy of Python 2.2's module, and works on Python 2.1 as well. +HMAC's security depends on the cryptographic strength of the key handed to it, +and on the underlying hashing method used. HMAC-MD5 and HMAC-SHA1 are used in +IPSEC and TLS.

All hashing modules with the exception of HMAC share the same interface. +After importing a given hashing module, call the new() function to create +a new hashing object. You can now feed arbitrary strings into the object +with the update() method, and can ask for the hash value at +any time by calling the digest() or hexdigest() +methods. The new() function can also be passed an optional string parameter that will be immediately hashed into the object's state.

To create a HMAC object, call HMAC's `new() function with the key (as +a string or bytes object) to be used, an optional message, and the hash +function to use. HMAC defaults to using MD5. This is not a secure default, +please use SHA256 or better instead in new implementations.

Hash function modules define one variable:

digest_size: An integer value; the size of the digest produced by the hashing objects. You could also obtain this value by creating a sample object, and taking the length of the digest string -it returns, but using digest_size is faster.

+it returns, but using digest_size is faster.

The methods for hashing objects are always the following:

copy(): -Return a separate copy of this hashing object. An update to +Return a separate copy of this hashing object. An update to this copy won't affect the original object.

digest(): Return the hash value of this hashing object, as a string containing 8-bit data. The object is not altered in any way by this function; -you can continue updating the object after calling this function.

+you can continue updating the object after calling this function. +Python 3.x: digest() returns a bytes object

hexdigest(): Return the hash value of this hashing object, as a string containing the digest data as hexadecimal digits. The resulting string will be -twice as long as that returned by digest(). The object is not +twice as long as that returned by digest(). The object is not altered in any way by this function; you can continue updating the object after calling this function.

update(arg): -Update this hashing object with the string arg.

Here's an example, using the MD5 algorithm:

->>> from Crypto.Hash import MD5
->>> m = MD5.new()
+Update this hashing object with the string arg.
+Python 3.x: The passed argument must be an object interpretable as
+a buffer of bytes
+Here's an example, using the SHA-256 algorithm:
+
+>>> from Crypto.Hash import SHA256
+>>> m = SHA256.new()
+>>> m.update('abc')
+>>> m.digest()
+'\xbax\x16\xbf\x8f\x01\xcf\xeaAA@\xde]\xae"#\xb0\x03a\xa3\x96\x17z\x9c\xb4\x10\xffa\xf2\x00\x15\xad'
+>>> m.hexdigest()
+'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
+
+
+Here's an example of using HMAC:
+
+>>> from Crypto.Hash import HMAC, SHA256
+>>> m = HMAC.new('Please do not use this key in your code, with sugar on top',
+                '', SHA256)
 >>> m.update('abc')
 >>> m.digest()
-'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
+'F\xaa\x83\t\x97<\x8c\x12\xff\xe8l\xca:\x1d\xb4\xfc7\xfa\x84tK-\xb0\x00v*\xc2\x90\x19\xaa\xfaz'
 >>> m.hexdigest()
-'900150983cd24fb0d6963f7d28e17f72'
+'46aa8309973c8c12ffe86cca3a1db4fc37fa84744b2db000762ac29019aafa7a'
 
-
-Security Notes
+
+
+Security Notes
 Hashing algorithms are broken by developing an algorithm to compute a
 string that produces a given hash value, or to find two messages that
 produce the same hash value. Consider an example where Alice and Bob
@@ -528,51 +810,51 @@ hash value of the text of the contract and signs the hash value with
 her private key.  Bob could then compute a different contract that has
 the same hash value, and it would appear that Alice signed that bogus
 contract; she'd have no way to prove otherwise.  Finding such a
-message by brute force takes pow(2, b-1) operations, where the
+message by brute force takes pow(2, b-1) operations, where the
 hash function produces b-bit hashes.
 If Bob can only find two messages with the same hash value but can't
 choose the resulting hash value, he can look for two messages with
 different meanings, such as "I will mow Bob's lawn for $10" and "I owe
 Bob $1,000,000", and ask Alice to sign the first, innocuous contract.
 This attack is easier for Bob, since finding two such messages by brute
-force will take pow(2, b/2) operations on average.  However,
+force will take pow(2, b/2) operations on average.  However,
 Alice can protect herself by changing the protocol; she can simply
 append a random string to the contract before hashing and signing it;
 the random string can then be kept with the signature.
-None of the algorithms implemented here have been completely broken.
-There are no attacks on MD2, but it's rather slow at 1250 K/sec.  MD4
-is faster at 44,500 K/sec but there have been some partial attacks on
-it.  MD4 makes three iterations of a basic mixing operation; two of
-the three rounds have been cryptanalyzed, but the attack can't be
-extended to the full algorithm.  MD5 is a strengthened version of MD4
-with four rounds; beginning in 2004, a series of attacks were
-discovered and it's now possible to create pairs of files that result
-in the same MD5 hash.  It's still supported for compatibility with
-existing protocols, but implementors should use SHA1 in new software
-because there are no known attacks against SHA1.  The MD5
+
Some of the algorithms implemented here have been completely broken.
+The MD2, MD4 and MD5 hash functions are widely considered insecure
+hash functions, as it has been proven that meaningful hash collisions
+can be generated for them, in the case of MD4 and MD5 in mere seconds.
+MD2 is rather slow at 1250 K/sec.  MD4 is faster at 44,500 K/sec.
+MD5 is a strengthened version of MD4 with four rounds; beginning in 2004,
+a series of attacks were discovered and it's now possible to create pairs
+of files that result in the same MD5 hash. The MD5
 implementation is moderately well-optimized and thus faster on x86
 processors, running at 35,500 K/sec.  MD5 may even be faster than MD4,
-depending on the processor and compiler you use.
-All the MD* algorithms produce 128-bit hashes; SHA1 produces a
-larger 160-bit hash, and there are no known attacks against it.  The
-first version of SHA had a weakness which was later corrected; the
-code used here implements the second, corrected, version.  It operates
-at 21,000 K/sec.  SHA256 is about as half as fast as SHA1.  RIPEMD has
-a 160-bit output, the same output size as SHA1, and operates at 17,600
+depending on the processor and compiler you use.
+MD5 is still supported for compatibility with existing protocols, but
+implementors should use SHA256 in new software because there are no known
+attacks against SHA256.
+All the MD* algorithms produce 128-bit hashes.
+SHA1 produces a 160-bit hash. Because of recent theoretical attacks against SHA1,
+NIST recommended phasing out use of SHA1 by 2010.
+SHA256 produces a larger 256-bit hash, and there are no known attacks against it.
+It operates at 10,500 K/sec.
+RIPEMD has a 160-bit output, the same output size as SHA1, and operates at 17,600
 K/sec.
-

Credits

+ +

Credits

The MD2 and MD4 implementations were written by A.M. Kuchling, and the MD5 code was implemented by Colin Plumb. The SHA1 code was originally written by -Peter Gutmann. The RIPEMD160 code as of version 2.1.0 was written by Dwayne +Peter Gutmann. The RIPEMD160 code as of version 2.1.0 was written by Darsey Litzenberger. The SHA256 code was written by Tom St. Denis and is part of the LibTomCrypt library (http://www.libtomcrypt.org/); it was adapted for the toolkit by Jeethu Rao and Taylor Boon.

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

Cipher	Key Size
Cipher	Key Size
ARC4	Variable
ARC4	Variable
XOR	Variable
XOR	Variable

Algorithm	Capabilities
Algorithm	Capabilities
RSA	Encryption, authentication/signatures
RSA	Encryption, authentication/signatures
ElGamal	Encryption, authentication/signatures
ElGamal	Encryption, authentication/signatures
DSA	Authentication/signatures
qNEW	Authentication/signatures
DSA	Authentication/signatures