****** RPKI Relying Party Tools ******

This collection of tools implements the "relying party" role of the RPKI
system, that is, the entity which retrieves RPKI objects from repositories,
validates them, and uses the result of that validation process as input to
other processes, such as BGP security.

See the CA tools for programs to help you generate RPKI objects, if you need to
do that.

***** Overview of the tools *****

Here's a brief summary of the current relying party tools.

**** rcynic ****

rcynic is the primary validation tool. It does the actual work of RPKI
validation: checking syntax, signatures, expiration times, and conformance to
the profiles for RPKI objects. The other relying party programs take rcynic's
output as their input.

See the instructions for setting up and running rcynic.

**** rcynic-html ****

rcynic-html is a post-processor which converts rcyic's XML status output into a
set of HTML pages displaying status and history.

**** rcynic-cron ****

rcynic-cron is a small script to run the most common set of relying party tools
under cron. See the discussion of running relying party tools under cron for
further details.

**** rtr-origin ****

rtr-origin is an implementation of the rpki-rtr protocol, using rcynic's output
as its data source. rtr-origin includes the rpki-rtr server, a test client, and
a utiltity for examining the content of the database rtr-origin generates from
the data supplied by rcynic.

See the instructions for setting up rtr-origin for further details.

**** roa-to-irr ****

roa-to-irr is an experimental program for converting RPKI ROA data into IRR
data. Some operators have established procedures that depend heavily on IRR, so
being able to distribute validated RPKI data via IRR is somewhat useful to
these operators.

Opinions vary regarding exactly what the RPSL corresponding to a particular set
of ROAs should look like, so roa-to-irr is currently experimental code at best.
Operators who really care about this may well end up writing their own ROA to
IRR conversion tools.

roa-to-irr expects its output to be piped to the irr_rpsl_submit program.

roa-to-irr isn't really documented (yet?). If you care, see the code.

**** rpki-torrent ****

rpki-torrent is an experimental program for distributing unvalidated RPKI data
over the BitTorrent protocol. Such data still needs to be validated by the
relying party (rpki-torrent does this automatically), BitTorrent is just being
used as an alternative transport protocol.

rpki-torrent isn't really documented yet.

**** Utilities ****

You may also find some of the RPKI utility programs useful.

***** Running relying party tools under cron *****

rcynic is the primary relying party tool, and it's designed to run under the
cron daemon. Consequently, most of the other tools are also designed to run
under the cron daemon, so that they can make use of rcynic's output immediately
after rcynic finishes a validation run.

rcynic-cron runs the basic set of relying party tools (rcynic, rcynic-html, and
rtr-origin --cronjob); if this suffices for your purposes, you don't need to do
anything else. The rest of this section is a discussion of alternative
approaches.

Which tools you want to run depends on how you intend to use the relying party
tools. Here we assume a typical case in which you want to gather and validate
RPKI data and feed the results to routers using the rpki-rtr protocol. We also
assume that everything has been installed in the default locations.

The exact sequence for invoking rcynic itself varies depending both on whether
you're using a chroot jail or not and on the platform on which you're running
rcynic, as the chroot utilities on different platforms behave slightly
differently. Using a chroot jail used to be the default for rcynic, but it
turned out that many users found the setup involved to be too complex.

If you're not using rcynic-cron, it's probably simplest to generate a short
shell script which calls the tools you want in the correct order, so that's
what we show here.

Once you've written this script, install it in your crontab, running at some
appropriate interval: perhaps hourly, or perhaps every six hours, depending on
your needs. You should run it at least once per day, and probably should not
run it more frequently than once per hour unless you really know what you are
doing. Please do NOT just arrange for the script to run on the hour, instead
pick some random minute value within the hour as the start time for your
script, to help spread the load on the repository servers.

On FreeBSD or MacOSX, this script might look like this:

  #!/bin/sh -
  /usr/sbin/chroot -u rcynic -g rcynic /var/rcynic /bin/rcynic -c /etc/
  rcynic.conf || exit
  /var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /usr/local/www/data/
  rcynic
  cd /var/rcynic/rpki-rtr
  /usr/bin/su -m rcynic -c '/usr/local/bin/rtr-origin --cronjob /var/rcynic/
  data/authenticated'

This assumes that you have done

  mkdir /var/rcynic/rpki-rtr
  chown rcynic /var/rcynic/rpki-rtr

On GNU/Linux systems, the script might look like this if you use the chrootuid
program:

  #!/bin/sh -
  /usr/bin/chrootuid /var/rcynic rcynic /bin/rcynic -c /etc/rcynic.conf || exit
  /var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /var/www/rcynic
  cd /var/rcynic/rpki-rtr
  /usr/bin/su -m rcynic -c '/usr/local/bin/rtr-origin --cronjob /var/rcynic/
  data/authenticated'

If you use the chroot program instead of chrootuid, change the line that
invokes rcynic to:

  /usr/sbin/chroot --userspec rcynic:rcynic /var/rcynic /bin/rcynic -c /etc/
  rcynic.conf || exit

***** Running a hierarchical rsync configuration *****

Having every relying party on the Internet contact every publication service is
not terribly efficient. In many cases, it may make more sense to use a
hierarchical configuration in which a few "gatherer" relying parties contact
the publication servers directly, while a collection of other relying parties
get their raw data from the gatherers.

Note: The relying parties in this configuration still perform their own
validation, they just let the gatherers do the work of collecting the
unvalidated data for them.

A gatherer in a configuration like this would look just like a stand-alone
relying party as discussed above. The only real difference is that a gatherer
must also make its unauthenticated data collection available to other relying
parties. Assuming the standard configuration, this will be the directory /var/
rcynic/data/unauthenticated and its subdirectories.

There are two slightly different ways to do this with rsync:

  1. Via unauthenticated rsync, by configuring an rsyncd.conf "module", or
  2. Via rsync over a secure transport protocol such as ssh.

Since the downstream relying party performs its own validation in any case,
either of these will work, but using a secure transport such as ssh makes it
easier to track problems back to their source if a downstream relying party
concludes that it's been receiving bad data.

Script for a downstream relying party using ssh might look like this:

  #!/bin/sh -

  PATH=/usr/bin:/bin:/usr/local/bin
  umask 022
  eval `/usr/bin/ssh-agent -s` >/dev/null
  /usr/bin/ssh-add /root/rpki_ssh_id_rsa 2>&1 | /bin/fgrep -v 'Identity added:'
  hosts='larry.example.org moe.example.org curly.example.org'
  for host in $hosts
  do
    /usr/bin/rsync --archive --update --safe-links rpkisync@${host}:/var/
  rcynic/data/unauthenticated/ /var/rcynic/data/unauthenticated.${host}/
  done
  eval `/usr/bin/ssh-agent -s -k` >/dev/null
  for host in $hosts
  do
    /usr/sbin/chroot -u rcynic -g rcynic /var/rcynic /bin/rcynic -c /etc/
  rcynic.conf -u /data/unauthenticated.${host}
    /var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /usr/local/www/
  data/rcynic.${host}
  done
  cd /var/rcynic/rpki-rtr
  /usr/bin/su -m rcynic -c '/usr/local/bin/rtr-origin --cronjob /var/rcynic/
  data/authenticated'

where /root/rpki_ssh_id_rsa is an SSH private key authorized to log in as user
"rpkisync" on the gatherer machines. If you want to lock this down a little
tighter, you could use ssh's command="..." mechanism as described in the sshd
documentation to restrict the rpkisync user so that it can only run this one
rsync command.

If you prefer to use insecure rsync, perhaps to avoid allowing the downstream
relying parties any sort of login access at all on the gatherer machines, the
configuration would look more like this:

  #!/bin/sh -

  PATH=/usr/bin:/bin:/usr/local/bin
  umask 022
  hosts='larry.example.org moe.example.org curly.example.org'
  for host in $hosts
  do
    /usr/bin/rsync --archive --update --safe-links rsync://${host}/
  unauthenticated/ /var/rcynic/data/unauthenticated.${host}/
  done
  for host in $hosts
  do
    /usr/sbin/chroot -u rcynic -g rcynic /var/rcynic /bin/rcynic -c /etc/
  rcynic.conf -u /data/unauthenticated.${host}
    /var/rcynic/bin/rcynic-html /var/rcynic/data/rcynic.xml /usr/local/www/
  data/rcynic.${host}
  done
  cd /var/rcynic/rpki-rtr
  /usr/bin/su -m rcynic -c '/usr/local/bin/rtr-origin --cronjob /var/rcynic/
  data/authenticated'

where "unauthenticated" here is an rsync module pointing at /var/rcynic/data/
unauthenticated on each of the gatherer machines. Configuration for such a
module would look like:

  [unauthenticated]
      read only           = yes
      transfer logging    = yes
      path                = /var/rcynic/data/unauthenticated
      comment             = Unauthenticated RPKI data