5.7 pisces.pwcrypt - Support for password-based cryptography (PKCS #5)

5.7 `pisces.pwcrypt` - Support for password-based cryptography (PKCS #5)

This module supports the use of password-based cryptography for encryption and message authentication using key derivation functions. This module is based on recommendations in PKCS #5 v2.0: Password-Based Crypotgraphy, RSA Laboratories, March 25, 1999. The recommendations are available from http://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html.

WARNING: It is not very practical to use Python for generating keys from passphrases; it is merely convenient. The key derivation process should take a long time, to thwart an attacker who attempts a dictionary attack on the password. But it can't take so long that the user grows impatient waiting for the key to be generated. The attacker could implement her brute force search in optimized C, which would be much faster than this Python implementation. Thus, this module provides much less security-for-the-wait that an optimized C version would.

KeyDerivationFactory (keylen, saltlen,[iterations], [hash], [labels])

A KeyDerivationFactory instance will generate keys that are keylen bytes long with saltlen bytes of salt. The optional arguments specify: the number of iterations of the the F function, the default value is 1000; the hash function to use, the default is SHA. The hash argument must support the interface implemented by Crypto.Hash hashes.

Labels are an optional feature. The labels argument accepts a sequence of strings. If several keys with the same generation parameters are going to be created, the salt should contain some text that identifies the particular use of the key. These are the labels. When createKey is called, it will check to see if the label used is valid.

The design of this class is explained carefully in the PKCS #5 document. The implementation uses HMAC plus a hash function as its pseudorandom function. The default hash is SHA.

createKey (password [, label]): Create a new key generated from the string password and optionally the string label. Returns the salt, the number of iterations of the F function, the name of the hash function, and the key itself. Raises ValueError if label is specified and does not match one of the labels specified in the constructor.

recreateKey (password, salt): Creates a key generated from the string password and the explicitly supplied salt string. Returns only the key. This method should only be used to recreate a key previously generated by createKey.