Package yawPyCrypto

yawPyCrypto
===========

yawPyCrypto, "yet another wrapper for PyCrypto", is a transparent and
secure way to protect python data using the cryptographic functionality
available through the PyCrypto library (available from http://www.amk.ca).

yawPyCrypto aims at giving the programmer a much higher-level interface to
cryptography than PyCrypto does, while still exposing as much as possible
of the powerful functionality the lowlevel crypto libraries offer.

yawPyCrypto is structured into the following modules:

Cipher
------

Cipher is the main interface to block and stream cipher algorithms present
in PyCrypto. All algorithms can be accessed using a single class by
passing appropriate parameters.

Instances of the encryption/decryption classes work as stream filters: you
can feed() data to a stream, and retrieve output using the instance's
property data. In case you override the method writeOutput() of one of the
classes, you can intercept any data output, and e.g. directly write it to
a disk or socket.

Cipher streams have an internal layout, which stores the cipher used, so
that decryption only needs the password used, and also a hash value of the
data, so that defective data/invalid password conditions can be detected
(but only after decrypting the whole stream first).

All meta-data of a stream is written out in cleartext serialized form. The
hash value of the data is computed in such a way that it is very unlikely
for equal messages to have the same hash value, as the hash value includes
random data written on initialization, which is also encrypted to
effectively randomize any IV that is chosen for chaining modes of an
algorithm.

If USE_ZLIB is set to True (default) in the Config.py file, classes are
defined which have the same functionality as the underlying cryptography
classes, but which feed all input through zlib on encryption (and also on
decryption), so that the actual data is "randomized" before being written
out.

AdvCipher
---------

Advanced cipher classes doing ASCII-armoring of the output data. Remains
to be included with yawPyCrypto (not stable at the moment).

The classes defined here are dropin replacements for the *Cipher classes.

Key
---

Key is the main interface to all public key cryptography algorithms
available in PyCrypto. All algorithms can be accessed using a single class
by passing appropriate parameters.

The Key class extends a PyCrypto key class by offering direct
serialization support (loadKey() and storeKey()) and key attributes. Key
attributes are a way of associating data elements with a key, such as
expiration time. These attributes are serialized (so they can be any valid
Python object, see the documentation of the Flatten library for more
information) and signed, if the key contains a private key. As Key
attributes are signed, any destination host can check for their validity,
even if they only received a public key copy of the key. In case
validation fails, the object is returned wrapped in an instance of the
class "Untrusted" (this behaviour is configurable in Config.py).

All data that is returned by the lowlevel PyCrypto functions is wrapped in
string form. This string form can be altered using (custom) wrapping
functions, there are several examples of this in the file AdvKey.py.

AdvKey
------

Advanced Key classes are two (important) examples of extending the
serialization and wrapping support of Key. One of these is the ability to
ASCII-wrap data in a format that is similar to GPG formatted packets, the
other is the ability to encrypt private keys using one of the lowlevel
block ciphers available through PyCrypto. These classes are called
AsciiKey and SecureKey. A combination of the two is present as
SecureAsciiKey, which wraps data as Ascii and secures private keys.

These classes are dropin replacements for the underlying Key class; they
offer equal functionality.

KeyCipher
---------

Implements a standard GPG-like block encryption cipher class, which uses
random session keys along with public key cryptography to secure long
streams of data using public key cryptography.

These classes work similar to the Cipher classes, but allow you to use
keys instead of passwords to secure the data. Signatures are appended to
the end of the encryption stream; there may be more than one signature
(more than one key may sign the stream). You can also encrypt the stream
for more than one destination.

Equally, you may pass several keys on decryption, which are checked
against the keys for which the stream was encrypted, and several keys
against which the appended signatures are checked.

AdvKeyCipher
------------

Advanced key cipher class which shows how to do wrapping and unwrapping of
key data in an Ascii block, similar to the wrapping functionality of the
AdvKey classes. Remains to be included in yawPyCrypto (not stable at the
moment).

The classes defined here are dropin replacements for the Key*Cipher
classes.

Config
======

Configuration information for PyCrypto. You should never need to change
this (under normal circumstances). See the file for more information on
what is configurable.

When you wish to change the defaults, change them before importing any of
the modules from yawPyCrypto. Do something like the following:

import yawPyCrypto.Config
yawPyCrypto.Config.WARN_ABOUT_UNTRUSTED_KEY_ARGUMENTS = 1
from yawPyCrypto.Key import Key
...

Constants
=========

All constants required in interaction with modules of PyCrypto is exposed
in this file. This includes the following:

HAVE_* - Constants which specify whether the algorithm that is passed as a
         name is available. Users can check this. Example: HAVE_AES
CIPHER_* - Constants for all stream ciphers. Only those constants for
           which the algorithm is available are defined.
           Example: CIPHER_AES
MODE_* - Constants for stream modes. Special mode for stream ciphers and
         for taking the default mode on block ciphers: MODE_NONE.
         Example: MODE_CBC.
HASH_* - Constants for all hash algorithms. Only those constants for which
         the algorithm is available are defined. Special constant to
         forbid hashing: HASH_NONE. Example: HASH_SHA.
PUBLICKEY_* - Constants for all public key algorithms. Only those
              constants for which the algorithm is available are defined.
              Example: PUBLICKEY_RSA

Another export is the yawPyCrypto random number pool. It is exported as
randpool, and has a member function called get_bytes, which returns a
stated number of random bytes.

It is safe to do a from Constants import * in your code.

Other modules
-------------

All other modules are private to yawPyCrypto, and should never be loaded
directly. They contain basic functionality, such as stream layout and
random data support.

Examples
========

You will find several examples of the functionality of yawPyCrypto in the
samples directory of the distribution. These show how to use the stream
encryption and public key encryption capabilities, and contain a small
test suite I use to check yawPyCrypto. (Not present at the moment, as
outdated, and I normally test using the Python interactive mode.

Copyright
=========

yawPyCrypto is copyright (C) 2002-3 by Heiko Wundram
<heiko@asta.uni-saarland.de>.

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at
your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library in the file "COPYLEFT"; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307  USA

Modules

• AdvKey: AdvKey.py =========
• Cipher: Stream encryption wrapper class.
• Config: This file defines several configuration defaults for yawPyCrypto.
• Constants: This file defines all constants used throughout the yawPyCrypto package.
• Key: Main class which wraps the PyCrypto public key functionality into an easier to use interface.
• KeyCipher: Key encryption wrapper class.