path: root/myrpki.rototill/README

$Id$

INTRODUCTION

The design of rpkid and friends assumes that certain tasks can be
thrown over the wall to the registry's back end operation.  This was a
deliberate design decision to allow rpkid et al to remain independent
of existing database schema, business PKIs, and so forth that a
registry might already have.  All very nice, but it leaves someone who
just wants to test the tools or who has no existing back end with a
fairly large programming project.  The tools in this directory attempt
to fill that gap.

This is a basic implementation of what a registry back end would need
to use rpkid and friends.  These tools do not use every available
option, nor are they necessarily as efficient as possible.  Large
registries will almost certainly want to roll their own tools, perhaps
using these as a starting point.  Nevertheless, we hope that these
tools will at least provide a useful example.

The primary tool here is a single command line Python program:
myrpki.py.  myrpki has a number of commands, most of which are used
for initial setup, some of which are used on an ongoing basis.  myrpki
can be run either in an interactive mode or by passing a single
command on the command line when starting the program; the former mode
is intended to be somewhat human-friendly, the latter mode is useful
in scripting, cron jobs, and automated testing.

myrpki use has two distinct phases: setup and data maintenance.  The
setup phase is primarily about constructing the "business PKI" (BPKI)
certificates that the daemons use to authenticate CMS and HTTPS
messages and obtaining the service URLs needed to configure the
daemons.  The data maintenance phase is about configuring local data
into the daemons.

myrpki uses the OpenSSL command line tool for almost all operations on
keys and certificates; the one exception to this is the comamnd which
talks directly to the daemons, as this command uses the same
communication libraries as the daemons themselves do.  The intent
behind using the OpenSSL command line tool for everything else is to
allow all the other commands to be run without requiring all the
auxiliary packages upon which the daemons depend; this can be useful,
eg, if one wants to run the back-end on a laptop while running the
daemons on a server, in which case one might prefer not to have to
install a bunch of unnecessary packages on the laptop.

During setup phase myrpki generates and processes small XML messages
which it expects the user to ship to and from its parents, children,
etc via some out-of-band means (email, perhaps with PGP signatures,
USB stick, we really don't care).  During data maintenance phase,
myrpki does something similar with another XML file, to allow hosting
of RPKI services; in the degenerate case where an entity is just
self-hosting (ie, is running the daemons for itself, and only for
itself), this latter XML file need not be sent anywhere.

The basic idea here is that a user who has resources maintains a set
of .csv files containing a text representation of the data needed by
the back-end, along with a configuration file containing other
parameters.  The intent is that these be very simple files that are
easy to generate either by hand or as a dump from relational database,
spreadsheet, awk script, whatever works in your environment.  Given
these files, the user then runs myrpki to extract the relevant
information and encode everything about its back end state into an XML
file, which can then be shipped to the appropriate other party.

Many of the myrpki commands which process XML input write out a new
XML file, either in place or as an entirely new file; in general,
these files need to be sent back to the party that sent the original
file.  Think of all this as a very slow packet-based communication
channel, where each XML file is a single packet.  In setup phase,
there's generally a single round-trip per setup conversation; in the
data maintenance phase, the same XML file keeps bouncing back and
forth between hosted entity and hosting entity.

Note that, as certificates and CRLs have expiration and nextUpdate
values, a low-level cycle of updates passing between resource holder
and rpkid operator will be necessary as a part of steady state
operation.  [The current version of these tools does not yet
regenerate these expiring objects, but fixing this will be a
relatively minor matter.]

The third important kind of file in this system is the configuration
file for myrpki.  This contains a number of sections, some of which
are for myrpki, others of which are for the OpenSSL command line tool,
still others of which are for the various RPKI daemon programs.  The
examples/ subdirectory contains a commented version of the
configuration file that explains the various parameters.

The .csv files read by myrpki can be anything that the Python "csv"
library understands.  By default, they're in tab-delimited format
(because the author finds this easier to read than the comma-delimited
format), but this can be changed to fit local needs.

Please note: tab-delimited CSV is a format defined by a certain
popular spreadsheet program, and is *not* the same as
whitespace-separated text.  Tab characters are *punctuation*, and each
tab character indicates the division between two columns.  Two tab
characters in a row indicates a separator, a blank cell, and another
separator, not one separator.  The upshot of all this is that
attempting to make your columns line up prettily will not work as you
expect, you will end up with too many cells, some of them empty.

Keep reading, and don't panic.

The default configuration file name is myrpki.conf.  You can change
this using the "-c" option when invoking myrpki, or by setting the
environment variable MYRPKI_CONF.

See examples/myrpki.conf for details on the variables that you can
(and in some cases must) set.

See examples/*.csv for commented examples of the several CSV files.
Note that the comments themselves are not legal CSV, they're just
present to make it easier to understand the examples.


GETTING STARTED -- OVERVIEW

Which process you need to follow depends on whether you are running
rpkid yourself or will be hosted by somebody else.  We call the first
case "self-hosted", because the software treats running rpkid to
handle resources that you yourself hold as if you are an rpkid
operator who is hosting an entity that happens to be yourself.

"$top" in the following refers to wherever you put the
subvert-rpki.hactrn.net code.  Once we have autoconf and "make
install" targets, this will be some system directory or another; for
now, it's wherever you checked out a copy of the code from the
subversion repository or unpacked a tarball of the code.

Most of the setup process looks the same for any resource holder,
regardless of whether they are self-hosting or not.  The differences
come in the data maintenence phase.

The steps needed during setup phase are:

- Write a configuration file (copy $top/myrpki/examples/myrpki.conf
  and edit as needed).  You need to configure the [myrpki] section; in
  theory, the rest of the file should be ok as it is, at least for
  simple use.

- Initialization ("initialize" command).  This creates the local BPKI
  and other data structures that can be constructed just based on
  local data such as the config file.  Other than some internal data
  structures, the main output of this step is the "identity.xml" file,
  which is used as input to later stages.

  In theory it should be safe to run the "initialize" command more
  than once, in practice this has not (yet) been tested.

- Send (email, USB stick, carrier pigeon) identity.xml to each of your
  parents.  This tells each of your parents what you call yourself,
  and supplies each parent with a trust anchor for your
  resource-holding BPKI.

- Each of your parents runs the "configure_child" command, giving the
  identity.xml you supplied as input.  This registers your data with
  the parent, including BPKI cross-registration, and generates a
  return message containing your parent's BPKI trust anchors, a
  service URL for contacting your parent via the "up-down" protocol,
  and (usually) either an offer of publication service (if your parent
  operates a repository) or a referral from your parent to whatever
  publication service your parent does use.  Referrals include a
  CMS-signed authorization token that the repository operator can use
  to determine that your parent has given you permission to home
  underneath your parent in the publication tree.

- Each of your parents sends (...) back the response XML file
  generated by the "configure_child" command.

- You feed the response message you just got into myrpki using the
  "configure_parent" command.  This registers the parent's information
  in your database, including BPKI cross-certification, and processes
  the repository offer or referral to generate a publication request
  message.

- You send (...) the publication request message to the repository.
  The <contact_info/> element in the request message should (in
  theory) provide some clue as to where you should send this.

- The repository operator processes your request using myrpki's
  "configure_publication_client" command.  This registers your
  information, including BPKI cross-certification, and generates a
  response message containing the repository's BPKI trust anchor and
  service URL.

- Repository operator sends (...) the publication confirmation message
  back to you.

- You process the publication confirmation message using myrpki's
  "configure_repository" command.

At this point you should, in theory, have established relationships,
exchanged trust anchors, and obtained service URLs from all of your
parents and repositories.  The last setup step is establishing a
relationship with your RPKI service host, if you're not self-hosted,
but as this is really just the first message of an ongoing exchange
with your host, it's handled by the data maintenance commands.

The two commands used in data maintenence phase are
"configure_resources" and "configure_daemons".  The first is used by
the resource holder, the second is used by the host.  In the
self-hosted case, it is not necessary to run "configure_resources" at
all, myrpki will run it for you automatically.

GETTING STARTED -- CONFIGURATION FILE

The sample configuration file should, in theory, be much simpler to
use than in earlier versions of this code.  The sample configuration
uses a simple macro-expansion mechanism to place all of the
configuration data you need to touch into the [myrpki] section; the
rest of the configuration file is for the various other tools, and is
entirely configured via references to the values defined in the
[myrpki] section.



[[[[**** CONTINUE HERE ****]]]]



GETTING STARTED -- HOSTED CASE

The basic steps involved in getting started for a resource holder who
is being hosted by somebody else are:

1) Obtain contact information and BPKI trust anchors from RPKI parents
   and an RPKI publication service (see below for details).

2) Write a configuration file (copy $top/myrpki/examples/myrpki.conf
   and edit as needed).  You can skip the sections associated with the
   various daemons and their runtime control tools ([myirbe], [rpkid],
   [irdbd], [pubd], [rootd], [irbe_cli]).  You *do* need to configure
   the [myrpki] section.

3) Using $top/myrpki/examples/*.csv as a guide, create a set of CSV
   files representing RPKI parents, RPKI children, resources to be
   assigned to RPKI children, and ROAs to be generated once the
   necessary RPKI certificates are available.  Most of these CSV files
   can be empty while first getting started, the only file that
   absolutely must be populated is the file describing parents.

   You may choose to place your configuration file (which we will
   refer to here as myrpki.conf) and your CSV files in their own
   directory.  The software doesn't really care.  If you use absolute
   names for all the filename entries in the configuration file and
   CSV files, you can put the files wherever you like; if you use
   relative names, they will be interpreted relative to the directory
   in which you run the program that reads the file.

   [At some future date we may provide a default directory for
   relative filenames such as /usr/local/etc/rpki, but the above
   description holds for now.]

4) Run myrpki.py to generate a BPKI trust anchor and collect all the
   data from the configuration file, CSV files, and newly created BPKI
   into a single XML file which can be shipped to the rpkid operator
   who is hosting your resources.

5) Send the XML file generated in step (4) to your rpkid operator.

6) Wait for your rpkid operator to ship you back an updated XML file
   containing a PKCS #10 certificate request for the BPKI signing
   context (BSC) created by rpkid.

7) Run myrpki.py again with the XML file received in step (6), to
   issue the BSC certificate and update the XML file again to contain
   the newly issued BSC certificate.

8) Send the updated XML file back to your rpkid operator.

At this point you're done with initial setup.  You will need to run
myrpki.py again whenever you make any changes to your configuration
file or CSV files.  [Once myrpki.py knows how to update BPKI CRLs, you
will also need to run myrpki.py periodically to keep your BPKI CRLs up
to date.]  Any time you run myrpki.py, you should send the updated XML
file to your rpkid operator, who will [generally?] send you a further
updated XML file in response.

GETTING STARTED -- SELF-HOSTED CASE

The first few steps involved in getting started for a self-hosted
resource holder (that is, a resource holder that runs its own copy of
rpkid) are the same as in the hosted case above; after that the
process diverges.

[As of the time at which these instructions were written, it had
become clear that there really should be an additional setup script
which automates much of the following.  That script hasn't been
written yet, so for the moment this documents the setup process as it
stands now.  Once that setup script has been written, these
instructions will be updated to match.  In the meantime, please accept
the author's apologies for the tedious nature of the current setup
process.]

The [current] steps are:

1) Obtain contact information and BPKI trust anchors from RPKI parents
   and an RPKI publication service (see below for details).

2) Write a configuration file (copy examples/myrpki.conf and edit as
   needed).  You need to configure the [myrpki] and [myirbe] sections
   as well as the sections associated with the daemons you will be
   running ([rpkid], [irdbd], [irbe_cli]).  You only need to configure
   the [pubd] section if you intend to run your own publication
   service: in general this is not recommended, because each
   additional publication service in the RPKI universe places a small
   additional burden on every relying party, since every relying party
   has to download data from every publication service.  In general
   it's better to use an existing publication service operated by
   somebody else (eg, your RPKI parent) if you can.  In general most
   cases you can leave the [rootd] section alone, as in most cases you
   should not be running rootd.

3) Using $top/myrpki/examples/*.csv as a guide, create a set of CSV
   files representing RPKI parents, RPKI children, resources to be
   assigned to RPKI children, and ROAs to be generated once the
   necessary RPKI certificates are available.  Most of these CSV files
   can be empty while first getting started, the only file that
   absolutely must be populated is the file describing parents.

   You may choose to place your configuration file (which we will
   refer to here as myrpki.conf) and your CSV files in their own
   directory.  The software doesn't really care.  If you use absolute
   names for all the filename entries in the configuration file and
   CSV files, you can put the files wherever you like; if you use
   relative names, they will be interpreted relative to the directory
   in which you run the program that reads the file.

   [At some future date we may provide a default directory for
   relative filenames such as /usr/local/etc/rpki, but the above
   description holds for now.]

4) See rpkid/doc/Installation, and follow the basic installation
   instructions there to build the RFC-3779-aware OpenSSL code and
   associated Python extension module.

5) Next, you need to set up the MySQL databases that rpkid et al will
   use.  The MySQL database, username, and password values all need to
   match the ones you specified in myrpki.conf.  There are two
   different ways you can do this:

   a) You can use the setup-sql.py script, which prompts you for your
      MySQL root password then attempts to do everything else
      automatically using values from myrpki.conf; or

   b) You can do it manually.

   The first approach is simple:

   $ python setup-sql.py
   Please enter your MySQL root password:

   The script should tell you what databases it creates.  You can use
   the -v option if you want to see more details about what it's doing.

   If you'd prefer to do the SQL setup manually, perhaps because you
   have valuable data in other MySQL databases and you don't want to
   trust some random setup script with your MySQL root password,
   you'll need to use the MySQL command line tool, as follows:

   $ mysql -u root -p

   mysql> CREATE DATABASE irdb_database;
   mysql> GRANT all ON irdb_database.* TO irdb_user@localhost IDENTIFIED BY 'irdb_password';
   mysql> USE irdb_database;
   mysql> SOURCE $top/rpkid/irdbd.sql;
   mysql> CREATE DATABASE rpki_database;
   mysql> GRANT all ON rpki_database.* TO rpki_user@localhost IDENTIFIED BY 'rpki_password';
   mysql> USE rpki_database;
   mysql> SOURCE $top/rpkid/rpkid.sql;
   mysql> COMMIT;
   mysql> quit

   where "irdb_database", "irdb_user", "irdb_password",
   "rpki_database", "rpki_user", and "rpki_password" are the
   appropriate values from your configuration file.

   If you are running pubd and doing manual SQL setup, you'll also
   have to do:

   $ mysql -u root -p
   mysql> CREATE DATABASE pubd_database;
   mysql> GRANT all ON pubd_database.* TO pubd_user@localhost IDENTIFIED BY 'pubd_password';
   mysql> USE pubd_database;
   mysql> SOURCE $top/rpkid/pubd.sql;
   mysql> COMMIT;
   mysql> quit

6) Run myirbe.py -b to set up the initial BPKI structure needed to run
   your daemons:

   $ python $top/myrpki/myirbe.py -b

   The -b option tells myrpki.py that you want it to stop after the
   initial BPKI setup, regardless of whether it thinks this is
   necessary.  If you have not done this before it should tell you
   that it has updated the BPKI and that you need to (re)start daemons
   now.

7) If you are running your own publication repository (that is, if you
   are running pubd), you will also need to set up an rsyncd server or
   configure your existing one to serve pubd's output.  There's a
   sample configuration file in $top/myrpki/examples/rsyncd.conf, but
   you may need to do something more complicated if you are already
   running rsyncd for other purposes.  See the rsync(1) and
   rsyncd.conf(5) manual pages for more details.

8) Start the daemons.  You can use $top/myrpki/start-servers.py to do
   this, or write your own script.

   If you intend to run pubd, you should make sure that the directory
   you specified as publication-base in the [pubd] section exists and
   is writable by the userid that will be running pubd, and should
   also make sure to start rsyncd.

9) Run myirbe.py again, twice, this time with no arguments.

   $ python $top/myrpki/myirbe.py
   $ python $top/myrpki/myirbe.py

   The reason for running myirbe.py twice at this point is explained
   in the Introduction section, above; in brief, the first run sets up
   almost everything, but a second pass is required to generate the
   BSC certificate.

At this point, if everything went well, rpkid should be up,
configured, and starting to obtain resource certificates from its
parents, generate CRLs and manifests, and so forth.  At this point you
should go figure out how to use the relying party tool, rcynic: see
$top/rcynic/README if you haven't already done so.

If and when you change your CSV files, you should run myirbe.py again
to feed the changes into the daemons.

GETTING STARTED -- HOSTING CASE

If you are running rpkid not just for your own resources but also to
host other resource holders (see "HOSTED CASE" above), your setup will
be almost the same as in the self-hosted case (see "SELF-HOSTED CASE",
above), with one procedural change: you will need to tell myirbe.py to
process the XML files produced by the resource holders you are
hosting.  You do this by specifying the names of all those XML files
on myirbe's command line.  So, if you are hosting two friends, Alice
and Bob, then, everywhere the instructions for the self-hosted case
say to run myirbe.py with no arguments, you will instead run it with
the names of Alice's and Bob's XML files:

  $ python $top/myrpki/myirbe.py alice.xml bob.xml

Note that myirbe.py sometimes modifies these XML files, in which case
it will write them back to the same filenames.  While it is possible
to figure out the set of circumstances in which myirbe.py will modify
XML files (at present, this only happens when myirbe.py has to ask
rpkid to create a new BSC keypair and PKCS #10 certificate request),
it may be easiest just to ship back an updated copy of the XML file
after every you run myirbe.py.

GETTING STARTED -- "PURE" HOSTING CASE

In general we assume that anybody who bothers to run rpkid is also a
resource holder, but the software does not insist on this.  If you are
running rpkid solely for others and have no resources of your own, the
process is almost identical to the "HOSTING CASE", above.  The one
change is that you should *not* have a [myrpki] section in your
configuration file.

A (perhaps) slightly-more-plausible use for this capability would be
if you are an rpkid-running resource holder who wants for some reason
to keep the resource-holding side of your operation completely
separate from the rpkid-running side of your operation.  This is
essentially the pure-hosting model, just with an internal hosted
entity within a different part of your own organization.

DATA YOU NEED FROM YOUR RPKI PARENT AND PUBLICATION SERVICE

In order to connect to your RPKI parent, you will need to supply your
BPKI trust anchor to your parent and obtain four pieces of data from
your parent.

Assuming that you are using something resembling the default
configuration, your BPKI trust anchor will be bpki.myrpki/ca.cer.
This is an OpenSSL "PEM" format file.  You will need to provide this
to your RPKI parent.

The data you need from your parent are:

- The service URL for your entry point into your parent's rpkid.
  Typically this will be a URL of the form:

  https://example.org:port/up-down/parenthandle/myhandle

  where "example.org" and "port" are the DNS name and TCP port of your
  parent's rpkid service, "parenthandle" is your parent's name
  (handle) for itself, and "myhandle" is your parent's name (handle)
  for you;

- Your parent's BPKI trust anchor for its resource-holding persona
  (the entity represented by "parenthandle", above);

- Your parent's BPKI trust anchor for daemons it operates; and

- The handle by which your parent refers to you in its database,
  generally the same as "myhandle" in the service URL.

The need for two separate BPKI trust anchors for your parent is due to
a limitation of the HTTPS protocol; recent extensions to TLS provide a
way to work around this limitation, but at this point in time rpkid
can't assume support for the TLS extension in question.  Roughly
speaking, the first BPKI trust anchor corresponds to the your parent
as a resource-holding entity, while the second corresponds to your
parent as an rpkid-operating entity.

These four data correspond, in order, to the second, third, fourth,
and fifth columns in your parents.csv file.  In most cases you will
have only one parent, so there will be only one line in that file.

The first field in the parents.csv file is your name for your parent,
which can be any name you like so long as it doesn't conflict with
your name for another parent.

The sixth field in the parents.csv file determines the base rsync URI
for objects signed by certificates issued by this parent.  If you are
using an external publication service (recommended), your parent must
supply this URI as well; a typical value would be
rsync://example.org/Dad/Me/ or rsync://example.org/Grandma/Dad/Me/.

If you are running your own copy of pubd, this URI should point to the
directory that corresponds to the publication-base setting in the
[pubd] section of your configuration file.

If you are using an external publication service (which might be your
parent, grandparent, or any ancestor all the way up to the root), your
publication service will also need to tell you:

- The service URL for the publication service (pubd_base parameter in
  [myirbe] section of your configuration file);

- The publication service's name for you (repository_handle field in
  [myrpki] section of your configuration file); and

- The BPKI trust anchor for the publication service
  (repository_bpki_certificate field in [myrpki] section of your
  configuration file).

Note that the first of these three parameters only applies if you are
running rpkid, while the second and third apply even if your resources
are hosted on somebody else's rpkid.  In effect, this means that all
the entities sharing a single rpkid must also share a single
publication service.  This is a restriction of the myrpki/myirbe
software, not rpkid itself, so it could be removed if there were a
strong need to do so, but given that each additional publication
service imposes a small additional burden on every relying party in
the world, we do not view this restriction as a problem.

DATA YOU NEED TO GIVE YOUR RPKI CHILDREN AND USERS OF YOUR PUBLICATION SERVICE

First, read the previous section describing what children and
publication clients expect to receive.

- The service URL for your rpkid will be an HTTPS URL of the form 

  https://example.org:port/up-down/yourhandle/childhandle

  where "example.org" and "port" are the DNS name and TCP port of your
  rpkid service ([rpkid] section of your configuration file),
  "yourhandle" is the handle parameter from the [myrpki] section of
  your configuration file, and "childhandle" is this child's handle as
  it appears in the first columns of your children.csv, asns.csv, and
  prefixes.csv files;

- The BPKI trust anchor for your resource-holding persona is your
  bpki.myrpki/ca.cer;

- The BPKI trust anchor for daemons you operate is your
  bpki.myirbe/ca.cer; and

- The handle by which you refer to your child is the same as
  "childhandle", above.

If you are operating a publication service, you will also need to
supply:

- Your pubd service URL, which will be an HTTPS URL of the form

  https://example.org:port/

  where "example.org" and "port" are the server-host and server-port
  parameters from the [pubd] section of your configuration file;

- Your name for this publication client, which is the first column of
  your pubclients.csv file (note that this can be a structured name
  using "/" characters as a hierarchy delimiter); and

- The BPKI trust anchor for the daemons you operate
  (bpki.myirbe/ca.cer).

Note that, if you are operating pubd, it's best for relying parties if
your children's publication points are underneath yours within the
publication hierarchy, to allow rsync to check for updates as
efficiently as possible.  pubd's support for hierarchical client
handles is intended to simplify this: if you have a child Alice, who
has children Bob and Bill, and you, your children, and your
grandchildren will all be using your publication service, you might
assign <client_handle> and <sia_base> parameters (first and third
fields in pubclients.csv) as follows:

Me		rsync://rpki.example.org/Me/
Me/Alice	rsync://rpki.example.org/Me/Alice/
Me/Alice/Bob	rsync://rpki.example.org/Me/Alice/Bob/
Me/Alice/Bill	rsync://rpki.example.org/Me/Alice/Bill/

Note that you will need trust anchors for your children and any
publication clients.  In both cases the trust anchor you need is the
child's or client's resource-holding BPKI trust anchor
(bpki.myrpki/ca.cer); who operates the rpkid that host your children
or publication clients is not strictly relevant to the authorization
model, what matters is who holds the resources and is authorized to
request and publish RPKI data derived from them.

TROUBLESHOOTING

If you run into trouble setting up this package, the first thing to do
is categorize the kind of trouble you are having.  If you've gotten
far enough to be running the daemons, check their log files.  If
you're seeing Python exceptions, read the error messages.  If you're
getting TLS errors, check to make sure that you're using all the right
BPKI certificates and service contact URLs.

TLS configuration errors are, unfortunately, notoriously difficult to
debug, because connections due to misconfiguration usually fail early,
deep in the guts of the OpenSSL TLS code, where there isn't enough
application context available to provide useful error messages.

If you've completed the steps above, everything appears to have gone
OK, but nothing seems to be happening, the first thing to do is check
the logs to confirm that nothing is actively broken.  rpkid's log
should include messages telling you when it starts and finishes its
internal "cron" cycle.  It can take several cron cycles for resources
to work their way down from your parent into a full set of
certificates and ROAs, so have a little patience.  rpkid's log should
also include messages showing every time it contacts its parent(s) or
attempts to publish anything.

rcynic in fully verbose mode provides a fairly detailed explanation of
what it's doing and why objects that fail have failed.

You can use rsync (sic) to examine the contents of a publication
repository one directory at a time, without attempting validation, by
running rsync with just the URI of the directory on its command line:

  $ rsync rsync://rpki.example.org/where/ever/

[Maybe there should be something here explaining how to use
irbe_cli.py for debugging, but the syntax is fairly obscure as it's
just a command line interface to the left-right and publication
protocols -- almost certainly want a friendlier tool for
troubleshooting.]

KNOWN ISSUES

The lxml package provides a Python interface to the Gnome libxml2 and
libxslt C libraries.  This code has been quite stable for several
years, but initial testing with lxml compiled and linked against a
newer version of libxml2 ran into problems (specifically, gratuitous
RelaxNG schema validation failures).  libxml2 2.7.3 worked; libxml2
2.7.5 did not work on the test machine in question.  Reverting to
libxml2 2.7.3 fixed the problem.  Rewriting the two lines of Python
code that were triggering the lxml bug appears to have solved the
problem, so the code now works properly with libxml 2.7.5, but if you
start seeing weird XML validation failures, it might be another
variation of this lxml bug.

An earlier version of this code ran into problems with what appears to
be an implementation restriction in the the GNU linker ("ld") on
64-bit hardware, resulting in obscure build failures.  The workaround
for this required use of shared libraries and is somewhat less
portable than the original code, but without it the code simply would
not build in 64-bit environments with the GNU tools.  The current
workaround appears to behave properly, but the workaround requires
that the pathname to the RFC-3779-aware OpenSSL shared libraries be
built into the _POW.so Python extension module.  At the moment, in the
absence of "make install" targets for the Python code and libraries,
this means the build directory; eventually, once we're using autoconf
and installation targets, this will be the installation directory.  If
necessary, you can override this by setting the LD_LIBRARY_PATH
environment variable, see the ld.so man page for details.  This is a
relatively minor variation on the usual build issues for shared
libraries, it's just annoying because shared libraries should not be
needed here and would not be if not for this GNU linker issue.