This package provides support for SAML2 based on ``pyxb``; more
precisely the ``saml20`` bundle of ``pyxb``.

``pyxb`` (http://pypi.python.org/pypi/PyXB) generates a Python class
collection for an XML schema and provides means to convert between
associated Python instances and xml documents. It is used to generate
and parse SAML2 messages.

The package adds support for digital signatures and SAML2 bindings and
metadata management.


Dependencies
============

PyXB
----

This package's version has been tested with version 1.1.3 of ``pyxb``.
It may not work with other versions.

Class collections generated by ``pyxb`` tend to be very version dependent.
Thus, they must usually be regenerated when the ``pyxb`` version has changed.

The current package's version mostly uses class collections from
the ``wssplat`` and ``saml20`` bundles of ``pyxb``. Thus, they
have a good chance to be updated together with ``pyxb``.
However, the ``pyxb`` ``saml2`` bundle lacks support for
the so called SAML2 context classes. This package contains
class collections generated with ``pyxb==1.1.3``. They need to
be regenerated if the ``pyxb`` version changes (and you use those classes --
which is not very likely).
The ``gen.sh`` script in subpackage ``pyxb``
can provide glues how to regenerate them.

``PyXB`` currently does not support installation via ``easy_install``.
You must install it manually.
To avoid failure with an automated installation trial,
the ``PyXB`` dependency is not declared in ``setup.py``.


pyxmlsec
--------

The package uses ``pyxmlsec``, the Python binding to the ``xmlsec`` library,
for signature support.

Unfortunately, ``pyxmlsec`` is not well maintained. To allow it to handle
the digital signatures for SAML2, you must at least patch its source
with the patch you can find at
http://lists.labs.libre-entreprise.org/pipermail/pyxmlsec-devel/2010-November/000081.html
If you work on an 64bit architecture, you will likely also need the
patch at
http://lists.labs.libre-entreprise.org/pipermail/pyxmlsec-devel/2011-September/000082.html

Due to the necessary patching, the dependency on ``pyxmlsec`` is not
declared in ``setup.py``.


libxml2
-------

``pyxmlsec`` depends on ``libxml2``, one of the Python bindings
to the ``libxml2`` library. This binding is provided as ``libxml2-python``
by many package systems (for operating system distributions). Thus, you
may be able to install it easily for your system Python.

``libxml2`` is not registered with ``PyPI``
(the Python package index). Therefore, it cannot be installed automatically
(and we do not declare this dependency in ``setup.py``).
If you cannot use a system wide installed ``libxml2-python`` package,
you find its source at
ftp://xmlsoft.org/libxml2/python/.
Use the version which fits your Python version.


Notes
=====

Note that signature creation and verification will fail with an obscure
error message from ``xmlsec`` when ``xmlsec`` is not properly
initialized. If default initialization is sufficient for you, then
you can call ``dm.xmlsec.pyxb.util.default_init()`` for initialization.
