Table of Contents
-----------------
1. Introduction
2. Release notes
3. License and source code
4. Dependencies
5. libaprutil versions
6. Python versions
7. Limitations
8. How to test python-aprmd5


Introduction
------------
The python-aprmd5 project provides the Python module "aprmd5", which in turn is
an interface to the MD5 routines of the Apache Portable Runtime (APR) Utility
Library (libaprutil).

The main purpose of python-aprmd5 is to expose a single function,
apr_md5_encode(), from among libaprutil's MD5 routines. That function is used to
generate salted crypt-style hashes using a version of the MD5 hash algorithm
that was modified for Apache. The resulting hashes always start with the prefix
characters "$apr1$" in order to distinguish them from the result of various
other crypt() variants, which use other prefixes. For instance, for input "foo"
and salt "mYJd83wW", apr_md5_encode() produces the following hash:

  $apr1$mYJd83wW$IO.6aK3G0d4mHxcImhPX50

Hashes like this are typically generated by the command line utility htpasswd,
which is part of the Apache HTTP server project. The hashes encrypt user
passwords that are used by the Apache HTTP server for basic user authentication.

In an attempt to earn its name, python-aprmd5 tries to expose most of the other
functions of libaprutil's MD5 routines as well. It doesn't try too hard, though,
since those functions are mostly concerned with the original, unmodified MD5
algorithm, and that algorithm can be easily obtained through the Python Standard
Library module "hashlib".


Release notes
-------------
This is python-aprmd5 0.1 (the initial release of the project).

For more details see the ChangeLog document.


License and source code
-----------------------
python-aprmd5 is licensed under the GNU General Public License (GPLv3). You
should have received a copy of the license along with the python-aprmd5 module
distribution (see the file COPYING inside the distribution). If not, see
<http://www.gnu.org/licenses/>.

The source code for python-aprmd5 can be downloaded from its website
http://www.herzbube.ch/python-aprmd5/. The source files are packaged into a tar
ball using the Distutils Python module. Alternatively you may also get the
source code (including project files to hack python-aprmd5 in Eclipse) from this
git respository: http://herzbube.ch/git/python-aprmd5/


Dependencies
------------
Obviously, python-aprmd5 depends on the presence of libaprutil. At compile time,
both the headers and the library file must be present. At runtime, the library
file is sufficient.


libaprutil versions
-------------------
No formal tests for compatibility with certain versions of libaprutil have been
performed. The earliest version that I have casually used on my system at home
(a Mac OS X box) is libaprutil 0.9. Another version that I have used for casual
testing on a Debian virtual box is libaprutil 1.3.5. As the interface of the
MD5 routines has not changed for a long time, and even across major versions of
libaprutil, it is reasonable to expect that python-aprmd5 will work with pretty
much all versions of libaprutil.

See the INSTALL document for details on how to build python-aprmd5 against
different versions of libaprutil.


Python versions
---------------
python-aprmd5 implements both the 2.x and the 3.x versions of Python's C-API,
so in theory it should work with all versions of Python 2.x and 3.x. In
practice, no formal tests have been performed to verify this statement. The
earliest version of Python that I have used to build python-aprmd5 with has been
2.5.1, and the latest version has been 3.1.1 (both on Mac OS X 10.5).


Limitations
-----------
python-aprmd5's treatment of libaprutil's MD5 routines other than the function
apr_md5_encode() is rather cursory.


How to test python-aprmd5
-------------------------
After performing a default build of python-aprmd5, the following command runs
all automated tests from the command line, from within the git working tree:

  ./setup.py test

To run tests from only one module (test_md5_encode.py in this example):

  setup.py test --suite=tests.test_md5_encode

To run the tests with a specific version of Python (version 2.6 in this example,
installed in /usr/bin such as on a Debian system):

  /usr/bin/python2.6 setup.py test