diff options
| author | Rob Austein <sra@hactrn.net> | 2011-04-21 18:41:10 +0000 |
|---|---|---|
| committer | Rob Austein <sra@hactrn.net> | 2011-04-21 18:41:10 +0000 |
| commit | c6302a1ca9b991511a5fcb8bb47fbf96cb1491bc (patch) | |
| tree | 6e061357080a80ccb8a1f09f8966b0db27f202a4 /rpkid/rpki/__doc__.py | |
| parent | 8f9137522ccdc35ff95fbc893206261df7e0790b (diff) | |
Hack Doxygen IMAGE_PATH via Makefile and environment variable rather
than feeding doc source through autoconf.
svn path=/configure; revision=3781
Diffstat (limited to 'rpkid/rpki/__doc__.py')
| -rw-r--r-- | rpkid/rpki/__doc__.py | 2380 |
1 files changed, 2380 insertions, 0 deletions
diff --git a/rpkid/rpki/__doc__.py b/rpkid/rpki/__doc__.py new file mode 100644 index 00000000..de79980b --- /dev/null +++ b/rpkid/rpki/__doc__.py @@ -0,0 +1,2380 @@ +## @file +# @details +# Documentation sourc, expressed as Python comments to make Doxygen happy. +# +# $Id$ +# +# Copyright (C) 2009--2010 Internet Systems Consortium ("ISC") +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +# AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +# PERFORMANCE OF THIS SOFTWARE. +# +# Portions copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND ARIN DISCLAIMS ALL WARRANTIES WITH +# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +# AND FITNESS. IN NO EVENT SHALL ARIN BE LIABLE FOR ANY SPECIAL, DIRECT, +# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +# LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +# OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +# PERFORMANCE OF THIS SOFTWARE. + +## @mainpage RPKI Engine Reference Manual +# +# This collection of Python modules implements a prototype of the +# RPKI Engine. This is a work in progress. +# +# See http://viewvc.hactrn.net/subvert-rpki.hactrn.net/ for code and +# design documents. +# +# The RPKI Engine is an implementation of the production-side tools +# for generating certificates, CRLs, and ROAs. The +# <a href="http://viewvc.hactrn.net/subvert-rpki.hactrn.net/rcynic/">relying party tools</a> +# are a separate (and much simpler) package. +# +# The Subversion repository for the entire project is available for +# (read-only) anonymous access at http://subvert-rpki.hactrn.net/. +# +# The documentation you're reading is generated automatically by +# Doxygen from comments and documentation in +# <a href="http://viewvc.hactrn.net/subvert-rpki.hactrn.net/rpkid/rpki/">the code</a>. +# +# Besides the automatically-generated code documentation, this manual +# also includes documentation of the overall package: +# +# @li @subpage Overview "Overview of the tools" +# +# @li @subpage Installation "Installation instructions" +# +# @li @subpage Configuration "Configuration instructions" +# +# @li @subpage MySQL-Setup "MySQL setup instructions" +# +# @li The @subpage myrpki "myrpki tool" +# +# @li A description of the @subpage Left-Right "left-right protocol" +# +# @li A description of the @subpage Publication "publication protocol" +# +# @li A description of the @subpage bpki-model "BPKI model" +# used to secure the up-down, left-right, and %publication protocols +# +# @li A description of the several @subpage sql-schemas "SQL database schemas" +# +# This work was funded from 2006 through 2008 by <a +# href="http://www.arin.net/">ARIN</a>, in collaboration with the +# other Regional Internet Registries. Current work is funded by DHS. + +## @page Overview Overview +# +# @section Terminology Terminology +# +# A few special terms that appear often enough in code or +# documentation that they need explaining. +# +# @todo +# These explanations should be fleshed out properly. +# +# @par IRBE: +# Internet Registry Back End. +# +# @par IRDB: +# Internet Registry Data Base. +# +# @par BPKI: +# Business PKI. +# +# @par RPKI: +# Resource PKI. +# +# +# @section Programs Programs +# +# At present the package is intended to be run out of the @c rpkid/ +# directory. +# +# In addition to the library routines in the @c rpkid/rpki/ directory, +# the package includes the following programs: +# +# @li @ref rpkid "@c rpkid": +# The main RPKI engine daemon. +# +# @li @ref pubd "@c pubd": +# The publication engine daemon. +# +# @li @ref rootd "@c rootd" +# A separate daemon for handling the root of an RPKI +# certificate tree. This is essentially a stripped down +# version of rpkid with no SQL database, no left-right +# protocol implementation, and only the parent side of +# the up-down protocol. It's separate because the root +# is a special case in several ways and it was simpler +# to keep the special cases out of the main daemon. +# +# @li @ref irdbd "@c irdbd": +# A sample implementation of an IR database daemon. +# rpkid calls into this to perform lookups via the +# left-right protocol. +# +# @li @ref smoketest "@c smoketest": +# A test tool for running a collection of rpkid and irdb +# instances under common control, driven by a unified +# test script. +# +# @li @ref yamltest "@c yamltest": +# Another test tool which takes the same input format as +# @c smoketest.py, but with slightly different purpose. +# @c smoketest.py is intended to support regression tests, +# while @c yamltest.py is intended for automated testing +# of something closer to a real operational environment. +# There's a fair amount of code duplication between the +# two, and at some point they will probably be merged +# into a single program that supports both modes of +# operation. +# +# Most of these programs take configuration files in a common format +# similar to that used by the OpenSSL command line tool. The test +# programs also take input in YAML format to drive the tests. Runs of +# the @c yamltest test tool will generate a fairly complete set +# configuration files which may be useful as examples. +# +# Basic operation consists of creating the appropriate MySQL databases +# (see @ref MySQL-Setup "MySQL Setup"), configuring relationships +# between parents and children and between publication clients and +# repositories (see @ref MyRPKI "The myrpki tool"), starting @c rpkid, +# @c pubd, @c rootd, and @c irdbd, and using the left-right and +# publication control protocols (see @ref MyRPKI "The myrpki tool") to +# set up rpkid's and pubd's internal state. All other operations +# should occur either as a result of cron events or as a result of +# incoming left-right and up-down protocol requests. +# +# The core programs are all event-driven, and are (in theory) capable +# of supporting an arbitrary number of hosted RPKI engines to run in a +# single rpkid instance, up to the performance limits of the underlying +# hardware. +# +# At present the daemon programs all run in foreground, that is, the +# daemons themselves make no attempt to put themselves in background. +# The easiest way to run the servers is to run the @c start_servers +# script, which examines your @c rpki.conf file and starts the +# appropriate servers in background using @c rpki.conf as the +# configuration file for each server as well. +# +# If you prefer, you can run each server by hand instead of using the +# script, eg, using Bourne shell syntax to run rpkid in background: +# +# @verbatim +# $ python rpkid.py & +# $ echo >rpkid.pid "$!" +# @endverbatim +# +# All of the daemons use syslog by default. You can change this by +# running either the servers themselves or the @c start_servers script +# with the "-d" option. Used as an argument to a server directly, +# "-d" causes that server to log to @c stderr instead of to syslog. +# Used as an argument to @c start_servers, "-d" starts each of the +# servers with "-d" while redirecting @c stderr from each server to a +# separate log file. This is intended primarily for debugging. +# +# Some of the options that the several daemons take are common to all +# daemons. Which daemon they affect depends only on which sections of +# which config files they are in. See +# @ref CommonOptions "Common Options" +# for details. +# +# @subsection rpkid rpkid +# +# rpkid is the main RPKI engine daemon. Configuration of rpkid is a +# two step process: a %config file to bootstrap rpkid to the point +# where it can speak using the @ref Left-Right "left-right protocol", +# followed by dynamic configuration via the left-right protocol. The +# latter stage is handled by the @c myrpki tool. +# +# rpkid stores dynamic data in an SQL database, which must have been +# created for it, as explained in the +# @ref Installation "Installation Guide". +# +# +# @subsection pubd pubd +# +# pubd is the publication daemon. It implements the server side of +# the publication protocol, and is used by rpkid to publish the +# certificates and other objects that rpkid generates. +# +# pubd is separate from rpkid for two reasons: +# +# @li The hosting model allows entities which choose to run their own +# copies of rpkid to publish their output under a common +# publication point. In general, encouraging shared publication +# services where practical is a good thing for relying parties, +# as it will speed up rcynic synchronization time. +# +# @li The publication server has to run on (or at least close to) the +# publication point itself, which in turn must be on a publically +# reachable server to be useful. rpkid, on the other hand, need +# only be reachable by the IRBE and its children in the RPKI tree. +# rpkid is a much more complex piece of software than pubd, so in +# some situations it might make sense to wrap tighter firewall +# constraints around rpkid than would be practical if rpkid and +# pubd were a single program. +# +# pubd stores dynamic data in an SQL database, which must have been +# created for it, as explained in the +# @ref Installation "Installation Guide". pubd also +# stores the published objects themselves as disk files in a +# configurable location which should correspond to an appropriate +# module definition in rsync.conf; see the +# @ref Configuration "Configuration Guide" +# for details. +# +# +# @subsection rootd rootd +# +# rootd is a stripped down implmenetation of (only) the server side of +# the up-down protocol. It's a separate program because the root +# certificate of an RPKI certificate tree requires special handling +# and may also require a special handling policy. rootd is a simple +# implementation intended for test use, it's not suitable for use in a +# production system. All configuration comes via the %config file; +# see the +# @ref Configuration "Configuration Guide" +# for details. +# +# +# @subsection irdbd irdbd +# +# irdbd is a sample implemntation of the server side of the IRDB +# callback subset of the left-right protocol. In production use this +# service is a function of the IRBE stub; irdbd may be suitable for +# production use in simple cases, but an IR with a complex IRDB may need +# to extend or rewrite irdbd. +# +# irdbd requires a pre-populated database to represent the IR's +# customers. irdbd expects this database to use +# @ref irdbd-sql "the SQL schema defined in rpkid/irdbd.sql". +# Once this database has been populated, the IRBE stub needs to create +# the appropriate objects in rpkid's database via the control subset +# of the left-right protocol, and store the linkage handles (foreign +# keys into rpkid's database) in the IRDB. See the +# @ref Installation "Installation Guide" +# and the +# @ref MySQL-Setup "MySQL setup instructions" +# for details. +# +# +# @subsection smoketest smoketest +# +# smoketest is a test harness to set up and run a collection of rpkid and +# irdbd instances under scripted control. +# +# Unlike the programs described above, smoketest takes two configuration +# files in different languages. The first configuration file uses the +# same syntax as the above configuration files but is completely +# optional. The second configuration file is the test script, which is +# encoded using the YAML serialization language (see +# http://www.yaml.org/ for more information on YAML). The YAML script +# is not optional, as it describes the test layout. smoketest is designed +# to support running a fairly wide set of test configurations as canned +# scripts without writing any new control code. The intent is to make +# it possible to write meaningful regression tests. +# +# See @ref smoketestconf "smoketest.conf" for what can go into the +# (optional) first configuration file. +# +# See @ref smoketestyaml "smoketest.yaml" for what goes into the +# (required) second configuration file. +# +# +# @subsection yamltest yamltest +# +# yamltest is another test harness to set up and run a collection of +# rpkid and irdbd instances under scripted control. It is similar in +# many ways to @ref smoketest "@c smoketest", and in fact uses the +# same YAML test description language, but its purpose is different: +# @c smoketest runs a particular test scenario through a series of +# changes, then shuts it down; @c yamltest, on the other hand, sets up +# a test network using the same tools that a real user would +# (principally the @c myrpki tool), and leaves the test running +# indefinitely. +# +# @c yamltest grew out of @c smoketest and the two probably should be +# merged back into a single tool which supports both kinds of testing. +# +# +# @section further-reading Further Reading +# +# If you're interested in this package you might also be interested +# in: +# +# @li <a href="http://track-rpki.hactrn.net/browser/rcynic/">The rcynic validation tool</a> +# +# @li <a href="http://www.hactrn.net/opaque/rcynic.html">A live sample of rcynic's summary output</a> +# +# +# @section getting-started Getting Started +# +# The first step to bringing up rpkid and friends is installing the code, +# which is described in the @ref Installation "Installation Guide". + +## @page Installation Installation Guide +# +# Installation instructions for rpkid et al. These are the +# production-side RPKI tools, for Internet Registries (RIRs, LIRs, +# etc). See the "rcynic" program for relying party tools. +# +# rpkid is a set of Python modules supporting generation and maintenance +# of resource certificates. Most of the code is in the rpkid/rpki/ +# directory. rpkid itself is a relatively small program that calls the +# library modules. There are several other programs that make use of +# the same libraries, as well as a collection of test programs. +# +# At present the package is intended to be run out of its build +# directory. Setting up proper installation in a system area using the +# Python distutils package would likely not be very hard but has not yet +# been done. +# +# Note that initial development of this code has been on FreeBSD, so +# installation will probably be easiest on FreeBSD. +# +# Before attempting to build the package, you need to install any +# missing prerequisites. Note that the Python code requires Python +# version 2.5 or 2.6. rpkid et al are mostly self-contained, but do +# require a small number of external packages to run. +# +# <ul> +# <li> +# If your Python installation does not already include the sources +# files needed to compile new Python extension modules, you will +# need to install whatever package does include those source +# files. The need for and name of this package varies from system +# to system. On FreeBSD, the base Python interpreter package +# includes the development sources; on at least some Linux +# distributions, you have to install a separate "python-devel" +# package or something similar. If you get compilation errors +# trying to build the POW code (below) and the error message says +# something about the file "Python.h" being missing, this is +# almost certainly your problem. +# </li> +# +# <li> +# <a href="http://codespeak.net/lxml/">http://codespeak.net/lxml/</a>, +# a Pythonic interface to the Gnome LibXML2 libraries. +# lxml in turn requires the LibXML2 C libraries. +# <ul> +# <li>FreeBSD: /usr/ports/devel/py-lxml</li> +# <li>Fedora: python-lxml.i386</li> +# <li>Ubuntu: python-lxml</li> +# </ul> +# </li> +# +# <li> +# <a href="http://sourceforge.net/projects/mysql-python/">http://sourceforge.net/projects/mysql-python/</a>, +# the Python "db" interface to MySQL. MySQLdb in turn requires MySQL client and server. rpkid et al have +# been tested with MySQL 5.0 and 5.1. +# <ul> +# <li>FreeBSD: /usr/ports/databases/py-MySQLdb</li> +# <li>Fedora: MySQL-python.i386</li> +# <li>Ubuntu: python-mysqldb</li> +# </ul> +# </li> +# </ul> +# +# rpkid et al also make heavy use of a modified copy of the Python +# OpenSSL Wrappers (POW) package, but this copy has enough modifications +# and additions that it's included in the subversion tree. +# +# The next step is to build the OpenSSL and POW binaries. At present +# the OpenSSL code is just a snapshot of the OpenSSL development +# sources, compiled with special options to enable RFC 3779 support +# that ISC wrote under previous contract to ARIN. The POW (Python +# OpenSSL Wrapper) library is an extended copy of the stock POW +# release. +# +# To build these, cd to the top-level directory in the distribution, +# run the configure script, then run "make": +# +# @verbatim +# $ cd $top +# $ ./configure +# $ make +# @endverbatim +# +# This should automatically build everything, in the right order, +# including linking the POW extension module with the OpenSSL library +# to provide RFC 3779 support. If you get errors building POW, see +# the above discussion of Python development sources. +# +# The architecture is intended to support hardware signing modules +# (HSMs), but the code to support them has not been written. +# +# At this point, you should have all the necessary software installed +# to run the core programs, but you will probably want to test it. +# The test suite requires a few more external packages, only one of +# which is Python code. +# +# <ul> +# <li> +# <a href="http://pyyaml.org/">http://pyyaml.org/</a>. +# Several of the test programs use PyYAML to parse a YAML +# description of a simulated allocation hierarchy to test. +# <ul> +# <li>FreeBSD: /usr/ports/devel/py-yaml</li> +# <li>Ubuntu: python-yaml</li> +# </ul> +# </li> +# +# <li> +# <a href="http://xmlsoft.org/XSLT/">http://xmlsoft.org/XSLT/</a>. +# Some of the test code uses xsltproc, from the Gnome LibXSLT +# package. +# <ul> +# <li>FreeBSD: /usr/ports/textproc/libxslt</li> +# <li>Ubuntu: xsltproc</li> +# </ul> +# </li> +# </ul> +# +# All tests should be run from the rpkid/ directories. +# +# Some of the tests require MySQL databases to store their data. To +# set up all the databases that the tests will need, run the SQL +# commands in rpkid/tests/smoketest.setup.sql. The MySQL command line +# client is usually the easiest way to do this, eg: +# +# @verbatim +# $ cd $top/rpkid +# $ mysql -u root -p <tests/smoketest.setup.sql +# @endverbatim +# +# To run the tests, run "make all-tests": +# +# @verbatim +# $ cd $top/rpkid +# $ make all-tests +# @endverbatim +# +# If nothing explodes, your installation is probably ok. Any Python +# backtraces in the output indicate a problem. +# +# There's a last set of tools that only developers should need, as +# they're only used when modifying schemas or regenerating the +# documentation. These tools are listed here for completeness. +# +# <ul> +# <li> +# <a href="http://www.doxygen.org/">http://www.doxygen.org/</a>. +# Doxygen in turn pulls in several other tools, notably Graphviz, +# pdfLaTeX, and Ghostscript. +# <ul> +# <li>FreeBSD: /usr/ports/devel/doxygen</li> +# <li>Ubuntu: doxygen</li> +# </ul> +# </li> +# +# <li> +# <a href="http://www.mbayer.de/html2text/">http://www.mbayer.de/html2text/</a>. +# The documentation build process uses xsltproc and html2text to dump +# flat text versions of a few critical documentation pages. +# <ul> +# <li>FreeBSD: /usr/ports/textproc/html2text</li> +# </ul> +# </li> +# +# <li> +# <a href="http://www.thaiopensource.com/relaxng/trang.html">http://www.thaiopensource.com/relaxng/trang.html</a>. +# Trang is used to convert RelaxNG schemas from the human-readable +# "compact" form to the XML form that LibXML2 understands. Trang in +# turn requires Java. +# <ul> +# <li>FreeBSD: /usr/ports/textproc/trang</li> +# </ul> +# </li> +# +# <li> +# <a href="http://search.cpan.org/dist/SQL-Translator/">http://search.cpan.org/dist/SQL-Translator/</a>. +# SQL-Translator, also known as "SQL Fairy", includes code to parse +# an SQL schema and dump a description of it as Graphviz input. +# SQL Fairy in turn requires Perl. +# <ul> +# <li>FreeBSD: /usr/ports/databases/p5-SQL-Translator</li> +# </ul> +# </li> +# </ul> +# +# Once you've finished with installation, the next thing you should +# read is the @ref Configuration "Configuration Guide". + +## @page Configuration Configuration Guide +# +# This section describes the configuration file syntax and settings. +# +# Each of the programs that make up the RPKI tookit can potentially +# take its own configuration file, but for most uses this is +# unnecessarily complicated. The recommended approach is to use a +# single configuration file, and to put all of the parameters that a +# normal user might need to change into a single section of that +# configuration file, then reference these common settings from the +# program-specific sections of the configuration file via macro +# expansion. The configuration file parser supports a limited version +# of the macro facility used in OpenSSL's configuration parser. An +# expression such as @verbatim foo = ${bar::baz} @endverbatim sets foo +# to the value of the @c baz variable from section @c bar. The section +# name @c ENV is special: it refers to environment variables. +# +# @section rpkiconf rpki.conf +# +# The default name for the shared configuration file is @c rpki.conf. +# Unless you really know what you're doing, you should start by +# copying the @c rpki.conf from the @c rpkid/examples directory and +# modifying it, as the sample configuration file already includes all +# the additional settings necessary to use the simplified configuration. +# +# @dontinclude rpki.conf +# @skipline [myrpki] +# +# The @c [myrpki] section of @c rpki.conf contains all the +# parameters that you really need to configure. +# +# @skip # +# @until = +# +# Every resource-holding or server-operating entity needs a "handle", +# which is just an identifier by which the entity calls itself. +# Handles do not need to be globally unique, but should be chosen with +# an eye towards debugging operational problems: it's best if you use +# a handle that your parents and children will recognize as being you. +# +# @skip # +# @until bpki/servers +# +# The myrpki tool requires filenames for several input data files, the +# "business PKI" databases used to secure CMS and TLS communications, +# and the XML intermediate format that it uses. Rather than +# hardwiring the names into the code, they're configured here. You +# can change the names if you must, but the defaults should be fine in +# most cases. +# +# @skip # +# @until irdbd_server_port +# +# If you're hosting RPKI service for others, or are self-hosting, you +# want this on. If somebody else is running rpkid on your behalf and +# you're just shipping them your @c myrpki.xml file, you can turn this +# off. +# +# If you're running @c rpkid at all, you'll need to set at least the +# @c rpkid_server_host parameter here. You may be able to use the +# default port numbers, or may need to pick different ones. Unless +# you plan to run @c irdbd on a different machine from @c rpkid, you +# should leave @c irdbd_server_host alone. +# +# @skip # +# @until pubd_contact_info +# +# The myrpki tool will attempt to negotiate publication service for +# you with whatever publication service your parent is using, if you +# let it, so in most cases you should not need to run @c pubd unless +# you need to issue certificates for private IP address space or +# private Autononmous System Numbers. +# +# If you do run @c pubd, you will need to set @c pubd_server_host. +# You may also need to set @c pubd_server_port, and you should provide +# something helpful as contact information in @c pubd_contact_info if +# you plan to offer publication service to your RPKI children, so that +# grandchildren (or descendents even further down the tree) who +# receive referrals to your service will know how to contact you. +# +# @skip # +# @until rootd_server_port +# +# You shouldn't run rootd unless you're the root of an RPKI tree. Who +# gets to be the root of the public RPKI tree is a political issue +# outside the scope of this document. For everybody else, the only +# reason for running @c rootd (other than test purposes) would be to +# support certification of private IP addresses and ASNs. The core +# tools can do this without any problem, but the simplified +# configuration mechanism does not (yet) make this easy to do. +# +# @skip # +# @until publication_rsync_server +# +# These parameters control the mapping between the rsync URIs +# presented by @c rsyncd and the local filesystem on the machine where +# @c pubd and @c rsyncd run. Any changes here must also be reflected +# as changes in @c rsyncd.conf. In most cases you should not change +# the value of @c publication_rsync_module from the default; since +# pubd can't (and should not) rewrite @c rsyncd.conf, it's best to use +# a static rsync module name here and let @c pubd do its work +# underneath that name. In most cases @c publication_rsync_server +# should be the same as @c publication_rsync_server, which is what the +# macro invocation in the default setting does. @c +# publication_base_directory, like other pathnames in @c rpki.conf, +# can be either a relative or absolute pathname; if relative, it's +# interpreted with respect to the directory in which the programs in +# question were started. In this specific case, it's probably better +# to use an absolute pathname, since this pathname must also appear in +# @c rsyncd.conf. +# +# @skip # +# @until pubd_sql_password +# +# These settings control how @c rpkid, @c irdbd, and @c pubd talk to +# the MySQL server. At minimum, each daemon needs its own database; +# in the simplest configuration, the username and password can be +# shared, which is what the macro references in the default +# configuration does. If for some reason you need to set different +# usernames and passwords for different daemons, you can do so by +# changing the daemon-specific variables. +# +# @skip # +# @until = openssl +# +# The @c myrpki tool uses the @c openssl command line tool for most of +# its BPKI operations, for two reasons: +# +# @li To avoid duplicating CA-management functionality already +# provided by the command line tool, and +# +# @li To ease portability of the @c myrpki tool, so that a "hosted" +# resource holder can use it without needing to install entire toolkit. +# +# The @c myrpki tool's use of OpenSSL does not require exotic features +# like RFC 3779 support, but it does require a version of the tool +# recent enough to support CMS and the @c -ss_cert argument to the @c +# ca command. Depending on the platform on which you are running this +# code, you may or may not have a system copy of the @c openssl tool +# installed that meets these criteria; if not, the @c openssl binary +# built when you compile the toolkit will suffice. This parameter +# allows you to tell @c myrpki where to find the binary, if necessary; +# the default just uses the system search path. +# +# @section otherconf Other configuration files and options +# +# In most cases the simplified configuration in the @c [myrpki] +# section of @c rpki.conf should suffice, but in case you need to +# tinker, here are details on the the rest of the configuration +# options. In most cases the default name of the configuration file +# for a program is the name of the program followed by @c ".conf", and +# the section name is also named for the program, so that you can +# combine sections into a single configuration file as shown with @c +# rpki.conf. +# +# @li @subpage CommonOptions "Common configuration options" +# +# @li @subpage rpkidconf "rpkid configuration" +# +# @li @subpage irdbdconf "irdbd configuration" +# +# @li @subpage pubdconf "pubd configuration" +# +# @li @subpage rootdconf "rootd configuration" +# +# @li @subpage smoketestconf "configuration of the smoketest test harness" +# +# @li @subpage smoketestyaml "test description language for the smoketest test harness" +# +# Once you've finished with configuration, the next thing you should +# read is the @ref MySQL-Setup "MySQL setup instructions". + +## @page MySQL-Setup MySQL Setup +# +# You need to install MySQL and set up the relevant databases before +# starting @c rpkid, @c irdbd, or @c pubd. +# +# See the @ref Installation "Installation Guide" for details on where +# to download MySQL and find documentation on installing it. +# +# See the @ref Configuration "Configuration Guide" for details on the +# configuration file settings the daemons will use to find and +# authenticate themselves to their respective databases. +# +# Before you can (usefully) start any of the daemons, you will need to +# set up the MySQL databases they use. You can do this by hand, or +# you can use the @c rpki-sql-setup.py script, which prompts you for your +# MySQL root password then attempts to do everything else +# automatically using values from rpki.conf. +# +# Using the script is simple: +# +# @verbatim +# $ python rpki-sql-setup.py +# Please enter your MySQL root password: +# @endverbatim +# +# 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: +# +# @verbatim +# $ 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 +# @endverbatim +# +# where @c irdb_database, @c irdb_user, @c irdb_password, @c +# rpki_database, @c rpki_user, and @c rpki_password match the values +# you used in your configuration file. +# +# If you are running pubd and are doing manual SQL setup, you'll also +# have to do: +# +# @verbatim +# $ 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 +# @endverbatim +# +# where @c pubd_database, @c pubd_user @c pubd_password match the +# values you used in your configuration file. +# +# Once you've finished configuring MySQL, the next thing you should +# read is the instructions for the @ref MyRPKI "myrpki tool". + + +## @page MyRPKI The myrpki tool +# +# 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 @c myrpki tool +# attempts to fill that gap. +# +# @c myrpki is a basic implementation of what a registry back end +# would need to use rpkid and friends. @c myrpki does not use every +# available option in the other programs, nor is it 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 @c myrpki will at least provide a useful +# example, and may be adaquate for simple use. +# +# @c myrpki is (currently) implemented as a single command line Python +# program. It has a number of commands, most of which are used for +# initial setup, some of which are used on an ongoing basis. @c +# 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. +# +# @c 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 +# messages and obtaining the service URLs needed to configure +# the daemons. The data maintenance phase is about configuring local +# data into the daemons. +# +# @c 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 @c 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, @c 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 @c 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 @c 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 +# @ref Configuration "configuration file" +# for @c 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 are (now) misnamed: formerly, they +# used the "excel-tab" format from the Python csv library, but early +# users kept trying to make the colums line up, which didn't do what +# the users expected. So now these files are just +# whitespace-delimted, such as a program like "awk" would understand. +# +# Keep reading, and don't panic. +# +# The default configuration file name for @c myrpki is +# @ref Configuration "@c rpki.conf". +# You can change this using the "-c" option when invoking myrpki, or +# by setting the environment variable MYRPKI_CONF. +# +# 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. +# +# @section myrpkioverview myrpki 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: +# +# @li Write a configuration file (copy $top/rpkid/examples/rpki.conf +# and edit as needed). You need to configure the @c [myrpki] section; +# in theory, the rest of the file should be ok as it is, at least for +# simple use. You also need to create (either by hand or by dumping +# from a database, spreadsheet, whatever) the CSV files describing +# prefixes and ASNs you want to allocate to your children and ROAs +# you want created. +# +# @li 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. +# +# @li 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. +# +# @li 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. +# +# @li Each of your parents sends (...) back the response XML file +# generated by the "configure_child" command. +# +# @li 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. +# +# @li You send (...) the publication request message to the +# repository. The @c contact_info element in the request message +# should (in theory) provide some clue as to where you should send +# this. +# +# @li 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. +# +# @li Repository operator sends (...) the publication confirmation message +# back to you. +# +# @li 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. +# +# @section myrpkihosted Hosted case +# +# The basic steps involved in getting started for a resource holder who +# is being hosted by somebody else are: +# +# @li Run through steps listed in +# @ref myrpkioverview "the myrpki overview section". +# +# @li Run the configure_resources command to generate myrpki.xml. +# +# @li Send myrpki.xml to the rpkid operator who will be hosting you. +# +# @li 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. +# +# @li Run configure_resources again with the XML file you just +# received, to issue the BSC certificate and update the XML file +# again to contain the newly issued BSC certificate. +# +# @li Send the updated XML file back to your rpkid operator. +# +# At this point you're done with initial setup. You will need to run +# configure_resources again whenever you make any changes to your +# configuration file or CSV files. +# +# @warning Once myrpki knows how to update +# BPKI CRLs, you will also need to run configure_resources periodically +# to keep your BPKI CRLs up to date. +# +# Any time you run configure_resources myrpki, you should send the +# updated XML file to your rpkid operator, who should send you a +# further updated XML file in response. +# +# @section myrpkiselfhosted 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 @ref myrpkihosted "hosted case" +# above; after that the process diverges. +# +# The [current] steps are: +# +# @li Follow the basic installation instructions in +# @ref Installation "the Installation Guide" to build the +# RFC-3779-aware OpenSSL code and associated Python extension +# module. +# +# @li Run through steps listed in +# @ref myrpkioverview "the myrpki overview section". +# +# @li Set up the MySQL databases that rpkid et al will use. The +# package includes a tool to do this for you, you can use that or +# do the job by hand. See +# @ref MySQL-Setup "MySQL database setup" +# for details. +# +# @li 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/rpkid/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. +# +# @li Start the daemons. You can use $top/rpkid/rpki-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_directory exists and is writable by the userid +# that will be running pubd, and should also make sure to start +# rsyncd. +# +# @li Run myrpki's configure_daemons command, twice, with no +# arguments. You need to run the command twice because myrpki has +# to ask rpkid to create a keypair and generate a certification +# request for the BSC. The first pass does this, the second +# processes the certification request, issues the BSC, and loads +# the result into rpkid. [Yes, we could automate this somehow, if +# necessary.] +# +# 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 +# configure_daemons again to feed the changes into the daemons. +# +# @section myrpkihosting Hosting case +# +# If you are running rpkid not just for your own resources but also to +# host other resource holders (see @ref myrpkihosted "hosted case" +# above), your setup will be almost the same as in the self-hosted +# case (see @ref myrpkiselfhosted "self-hosted case", above), with one +# procedural change: you will need to tell @c configure_daemons 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 as arguments to the @c configure_daemons command. So, if you are +# hosting two friends, Alice and Bob, then, everywhere the +# instructions for the self-hosted case say to run @c +# configure_daemons with no arguments, you will instead run it with +# the names of Alice's and Bob's XML files as arguments. +# +# Note that @c configure_daemons 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 this +# will happen (at present, only when @c myrpki has to ask @c 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 @c configure_daemons. +# +# @section myrpkipurehosting "Pure" hosting case +# +# In general we assume that anybody who bothers to run @c rpkid is +# also a resource holder, but the software does not insist on this. +# +# @todo +# Er, well, rpkid doesn't, but myrpki now does -- "pure" hosting was an +# unused feature that fell by the wayside while simplifying the user +# interface. It would be relatively straightforward to add it back if +# we ever need it for anything, but the mechanism it used to use no +# longer exists -- the old [myirbe] section of the config file has been +# collapsed into the [myrpki] section, so testing for existance of the +# [myrpki] section no longer works. So we'll need an explicit +# configuration option, no big deal, just not worth chasing now. +# +# A (perhaps) 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. +# +# @section myrpkitroubleshooting 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 connection failures due to misconfiguration happen +# 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. @c +# 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. @c rpkid's +# log should also include messages showing every time it contacts its +# parent(s) or attempts to publish anything. +# +# @c 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 @c 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: +# +# @verbatim +# $ rsync rsync://rpki.example.org/where/ever/ +# @endverbatim +# +# @section myrpkiknownissues 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. + +## @page CommonOptions Common Configuration Options +# +# Some of the options that the several daemons take are common to all +# daemons. Which daemon they affect depends only on which sections of +# which config files they are in. +# +# The first group of options are debugging flags, which can be set to +# "true" or "false". If not specified, default values will be chosen +# (generally false). +# +# @par @c debug_http: +# Enable verbose http debug logging. +# +# @par @c debug_tls_certs: +# Enable verbose logging about tls certs. +# +# @par @c want_persistent_client: +# Enable http 1.1 persistence, client side. +# +# @par @c want_persistent_server: +# Enable http 1.1 persistence, server side. +# +# @par @c debug_cms_certs: +# Enable verbose logging about cms certs. +# +# @par @c sql_debug: +# Enable verbose logging about sql operations. +# +# @par @c gc_debug: +# Enable scary garbage collector debugging. +# +# @par @c timer_debug: +# Enable verbose logging of timer system. +# +# There are also a few options that allow you to save CMS messages for +# audit or debugging. The save format is a simple MIME encoding in a +# Maildir-format mailbox. The current options are very crude, at some +# point we may provide finer grain controls. +# +# @par @c dump_outbound_cms: +# Dump messages we send to this mailbox. +# +# @par @c dump_inbound_cms: +# Dump messages we receive to this mailbox. + +## @page rpkidconf rpkid.conf +# +# rpkid's default %config file is rpkid.conf, start rpkid with "-c +# filename" to choose a different %config file. All options are in +# the section "[rpkid]". Certificates, keys, and trust anchors may be +# in either DER or PEM format. +# +# %Config file options: +# +# @par @c startup-message: +# String to %log on startup, useful when +# debugging a collection of rpkid instances at +# once. +# +# @par @c sql-username: +# Username to hand to MySQL when connecting to +# rpkid's database. +# +# @par @c sql-database: +# MySQL's database name for rpkid's database. +# +# @par @c sql-password: +# Password to hand to MySQL when connecting to +# rpkid's database. +# +# @par @c bpki-ta: +# Name of file containing BPKI trust anchor. +# All BPKI certificate verification within rpkid +# traces back to this trust anchor. +# +# @par @c rpkid-cert: +# Name of file containing rpkid's own BPKI EE +# certificate. +# +# @par @c rpkid-key: +# Name of file containing RSA key corresponding +# to rpkid-cert. +# +# @par @c irbe-cert: +# Name of file containing BPKI certificate used +# by IRBE when talking to rpkid. +# +# @par @c irdb-cert: +# Name of file containing BPKI certificate used +# by irdbd. +# +# @par @c irdb-url: +# Service URL for irdbd. Must be a %http:// URL. +# +# @par @c server-host: +# Hostname or IP address on which to listen for +# HTTP connections. Current default is +# INADDR_ANY (IPv4 0.0.0.0); this will need to +# be hacked to support IPv6 for production. +# +# @par @c server-port: +# TCP port on which to listen for HTTP +# connections. + +## @page pubdconf pubd.conf +# +# pubd's default %config file is pubd.conf, start pubd with "-c +# filename" to choose a different %config file. All options are in +# the section "[pubd]". Certifiates, keys, and trust anchors may be +# either DER or PEM format. +# +# %Config file options: +# +# @par @c sql-username: +# Username to hand to MySQL when connecting to +# pubd's database. +# +# @par @c sql-database: +# MySQL's database name for pubd's database. +# +# @par @c sql-password: +# Password to hand to MySQL when connecting to +# pubd's database. +# +# @par @c bpki-ta: +# Name of file containing master BPKI trust +# anchor for pubd. All BPKI validation in pubd +# traces back to this trust anchor. +# +# @par @c irbe-cert: +# Name of file containing BPKI certificate used +# by IRBE when talking to pubd. +# +# @par @c pubd-cert: +# Name of file containing BPKI certificate used +# by pubd. +# +# @par @c pubd-key: +# Name of file containing RSA key corresponding +# to @c pubd-cert. +# +# @par @c server-host: +# Hostname or IP address on which to listen for +# HTTP connections. Current default is +# INADDR_ANY (IPv4 0.0.0.0); this will need to +# be hacked to support IPv6 for production. +# +# @par @c server-port: +# TCP port on which to listen for HTTP +# connections. +# +# @par @c publication-base: +# Path to base of filesystem tree where pubd +# should store publishable objects. Default is +# "publication/". + +## @page rootdconf rootd.conf +# +# rootd's default %config file is rootd.conf, start rootd with "-c +# filename" to choose a different %config file. All options are in +# the section "[rootd]". Certificates, keys, and trust anchors may be +# in either DER or PEM format. +# +# %Config file options: +# +# @par @c bpki-ta: +# Name of file containing BPKI trust anchor. All +# BPKI certificate validation in rootd traces +# back to this trust anchor. +# +# @par @c rootd-bpki-cert: +# Name of file containing rootd's own BPKI +# certificate. +# +# @par @c rootd-bpki-key: +# Name of file containing RSA key corresponding to +# rootd-bpki-cert. +# +# @par @c rootd-bpki-crl: +# Name of file containing BPKI CRL that would +# cover rootd-bpki-cert had it been revoked. +# +# @par @c child-bpki-cert: +# Name of file containing BPKI certificate for +# rootd's one and only child (RPKI engine to +# which rootd issues an RPKI certificate). +# +# @par @c server-host: +# Hostname or IP address on which to listen for +# HTTP connections. Default is localhost. +# +# @par @c server-port: +# TCP port on which to listen for HTTP +# connections. +# +# @par @c rpki-root-key: +# Name of file containing RSA key to use in +# signing resource certificates. +# +# @par @c rpki-root-cert: +# Name of file containing self-signed root +# resource certificate corresponding to +# rpki-root-key. +# +# @par @c rpki-root-dir: +# Name of directory where rootd should write +# RPKI subject certificate, manifest, and CRL. +# +# @par @c rpki-subject-cert: +# Name of file that rootd should use to save the +# one and only certificate it issues. +# Default is "Subroot.cer". +# +# @par @c rpki-root-crl: +# Name of file to which rootd should save its +# RPKI CRL. Default is "Root.crl". +# +# @par @c rpki-root-manifest: +# Name of file to which rootd should save its +# RPKI manifest. Default is "Root.mnf". +# +# @par @c rpki-subject-pkcs10: +# Name of file that rootd should use when saving +# a copy of the received PKCS #10 request for a +# resource certificate. This is only used for +# debugging. Default is not to save the PKCS +# #10 request. + +## @page irdbdconf irdbd.conf +# +# irdbd's default %config file is irdbd.conf, start irdbd with "-c +# filename" to choose a different %config file. All options are in the +# section "[irdbd]". Certificates, keys, and trust anchors may be in +# either DER or PEM format. +# +# %Config file options: +# +# @par @c startup-message: +# String to %log on startup, useful when +# debugging a collection of irdbd instances at +# once. +# +# @par @c sql-username: +# Username to hand to MySQL when connecting to +# irdbd's database. +# +# @par @c sql-database: +# MySQL's database name for irdbd's database. +# +# @par @c sql-password: +# Password to hand to MySQL when connecting to +# irdbd's database. +# +# @par @c bpki-ta: +# Name of file containing BPKI trust anchor. All +# BPKI certificate validation in irdbd traces +# back to this trust anchor. +# +# @par @c irdbd-cert: +# Name of file containing irdbd's own BPKI +# certificate. +# +# @par @c irdbd-key: +# Name of file containing RSA key corresponding +# to irdbd-cert. +# +# @par @c rpkid-cert: +# Name of file containing certificate used the +# one and only by rpkid instance authorized to +# contact this irdbd instance. +# +# @par @c http-url: +# Service URL for irdbd. Must be a %http:// URL. + +## @page smoketestconf smoketest.conf +# +# All of the options in smoketest's (optional) configuration file are +# overrides for wired-in default values. In almost all cases the +# defaults will suffice. There are a ridiculous number of options, +# most of which noone will ever need, see the code for details. The +# default name for this configuration file is smoketest.conf, run +# smoketest with "-c filename" to change it. + +## @page smoketestyaml smoketest.yaml +# +# smoketest's second configuration file is named smoketest.yaml by +# default, run smoketest with "-y filename" to change it. The YAML +# file contains multiple YAML "documents". The first document +# describes the initial test layout and resource allocations, +# subsequent documents describe modifications to the initial +# allocations and other parameters. Resources listed in the initial +# layout are aggregated automatically, so that a node in the resource +# hierarchy automatically receives the resources it needs to issue +# whatever its children are listed as holding. Actions in the +# subsequent documents are modifications to the current resource set, +# modifications to validity dates or other non-resource parameters, or +# special commands like "sleep". +# +# Here's an example of current usage: +# +# @verbatim +# name: Alice +# valid_for: 2d +# sia_base: "rsync://alice.example/rpki/" +# kids: +# - name: Bob +# kids: +# - name: Carol +# ipv4: 192.0.2.1-192.0.2.33 +# asn: 64533 +# --- +# - name: Carol +# valid_add: 10 +# --- +# - name: Carol +# add_as: 33 +# valid_add: 2d +# --- +# - name: Carol +# valid_sub: 2d +# --- +# - name: Carol +# valid_for: 10d +# @endverbatim +# +# This specifies an initial layout consisting of an RPKI engine named +# "Alice", with one child "Bob", which in turn has one child "Carol". +# Carol has a set of assigned resources, and all resources in the system +# are initially set to be valid for two days from the time at which the +# test is started. The first subsequent document adds ten seconds to +# the validity interval for Carol's resources and makes no other +# modifications. The second subsequent document grants Carol additional +# resources and adds another two days to the validity interval for +# Carol's resources. The next document subtracts two days from the +# validity interval for Carol's resources. The final document sets the +# validity interval for Carol's resources to ten days. +# +# Operators in subsequent (update) documents: +# +# @par @c add_as: +# Add ASN resources. +# +# @par @c add_v4: +# Add IPv4 resources. +# +# @par @c add_v6: +# Add IPv6 resources. +# +# @par @c sub_as: +# Subtract ASN resources. +# +# @par @c sub_v4: +# Subtract IPv4 resources. +# +# @par @c sub_v6: +# Subtract IPv6 resources. +# +# @par @c valid_until: +# Set an absolute expiration date. +# +# @par @c valid_for: +# Set a relative expiration date. +# +# @par @c valid_add: +# Add to validity interval. +# +# @par @c valid_sub: +# Subtract from validity interval. +# +# @par @c sleep [interval]: +# Sleep for specified interval, or until smoketest receives a SIGALRM signal. +# +# @par @c shell cmd...: +# Pass rest of line verbatim to /bin/sh and block until the shell returns. +# +# Absolute timestamps should be in the form shown (UTC timestamp format +# as used in XML). +# +# Intervals (@c valid_add, @c valid_sub, @c valid_for, @c sleep) are either +# integers, in which case they're interpreted as seconds, or are a +# string of the form "wD xH yM zS" where w, x, y, and z are integers and +# D, H, M, and S indicate days, hours, minutes, and seconds. In the +# latter case all of the fields are optional, but at least one must be +# specified. For example, "3D4H" means "three days plus four hours". + + +## @page Left-Right Left-Right Protocol +# +# The left-right protocol is really two separate client/server +# protocols over separate channels between the RPKI engine and the IR +# back end (IRBE). The IRBE is the client for one of the +# subprotocols, the RPKI engine is the client for the other. +# +# @section Operations initiated by the IRBE +# +# This part of the protcol uses a kind of message-passing. Each %object +# that the RPKI engine knows about takes five messages: "create", "set", +# "get", "list", and "destroy". Actions which are not just data +# operations on %objects are handled via an SNMP-like mechanism, as if +# they were fields to be set. For example, to generate a keypair one +# "sets" the "generate-keypair" field of a BSC %object, even though there +# is no such field in the %object itself as stored in SQL. This is a bit +# of a kludge, but the reason for doing it as if these were variables +# being set is to allow composite operations such as creating a BSC, +# populating all of its data fields, and generating a keypair, all as a +# single operation. With this model, that's trivial, otherwise it's at +# least two round trips. +# +# Fields can be set in either "create" or "set" operations, the +# difference just being whether the %object already exists. A "get" +# operation returns all visible fields of the %object. A "list" +# operation returns a %list containing what "get" would have returned on +# each of those %objects. +# +# Left-right protocol %objects are encoded as signed CMS messages +# containing XML as eContent and using an eContentType OID of @c id-ct-xml +# (1.2.840.113549.1.9.16.1.28). These CMS messages are in turn passed +# as the data for HTTP POST operations, with an HTTP content type of +# "application/x-rpki" for both the POST data and the response data. +# +# All operations allow an optional "tag" attribute which can be any +# alphanumeric token. The main purpose of the tag attribute is to allow +# batching of multiple requests into a single PDU. +# +# @subsection self_obj <self/> object +# +# A @c <self/> %object represents one virtual RPKI engine. In simple cases +# where the RPKI engine operator operates the engine only on their own +# behalf, there will only be one @c <self/> %object, representing the engine +# operator's organization, but in environments where the engine operator +# hosts other entities, there will be one @c @c <self/> %object per hosted +# entity (probably including the engine operator's own organization, +# considered as a hosted customer of itself). +# +# Some of the RPKI engine's configured parameters and data are shared by +# all hosted entities, but most are tied to a specific @c <self/> %object. +# Data which are shared by all hosted entities are referred to as +# "per-engine" data, data which are specific to a particular @c <self/> +# %object are "per-self" data. +# +# Since all other RPKI engine %objects refer to a @c <self/> %object via a +# "self_handle" value, one must create a @c <self/> %object before one can +# usefully configure any other left-right protocol %objects. +# +# Every @c <self/> %object has a self_handle attribute, which must be specified +# for the "create", "set", "get", and "destroy" actions. +# +# Payload data which can be configured in a @c <self/> %object: +# +# @par @c use_hsm (attribute): +# Whether to use a Hardware Signing Module. At present this option +# has no effect, as the implementation does not yet support HSMs. +# +# @par @c crl_interval (attribute): +# Positive integer representing the planned lifetime of an RPKI CRL +# for this @c <self/>, measured in seconds. +# +# @par @c regen_margin (attribute): +# Positive integer representing how long before expiration of an +# RPKI certificiate a new one should be generated, measured in +# seconds. At present this only affects the one-off EE +# certificates associated with ROAs. This parameter also controls +# how long before the nextUpdate time of CRL or manifest the CRL +# or manifest should be updated. +# +# @par @c bpki_cert (element): +# BPKI CA certificate for this @c <self/>. This is used as part of the +# certificate chain when validating incoming TLS and CMS messages, +# and should be the issuer of cross-certification BPKI certificates +# used in @c <repository/>, @c <parent/>, and @c <child/> %objects. If the +# bpki_glue certificate is in use (below), the bpki_cert certificate +# should be issued by the bpki_glue certificate; otherwise, the +# bpki_cert certificate should be issued by the per-engine bpki_ta +# certificate. +# +# @par @c bpki_glue (element): +# Another BPKI CA certificate for this @c <self/>, usually not needed. +# Certain pathological cross-certification cases require a +# two-certificate chain due to issuer name conflicts. If used, the +# bpki_glue certificate should be the issuer of the bpki_cert +# certificate and should be issued by the per-engine bpki_ta +# certificate; if not needed, the bpki_glue certificate should be +# left unset. +# +# Control attributes that can be set to "yes" to force actions: +# +# @par @c rekey: +# Start a key rollover for every RPKI CA associated with every +# @c <parent/> %object associated with this @c <self/> %object. This is the +# first phase of a key rollover operation. +# +# @par @c revoke: +# Revoke any remaining certificates for any expired key associated +# with any RPKI CA for any @c <parent/> %object associated with this +# @c <self/> %object. This is the second (cleanup) phase for a key +# rollover operation; it's separate from the first phase to leave +# time for new RPKI certificates to propegate and be installed. +# +# @par @c reissue: +# Not implemented, may be removed from protocol. Original theory +# was that this operation would force reissuance of any %object with +# a changed key, but as that happens automatically as part of the +# key rollover mechanism this operation seems unnecessary. +# +# @par @c run_now: +# Force immediate processing for all tasks associated with this +# @c <self/> %object that would ordinarily be performed under cron. Not +# currently implemented. +# +# @par @c publish_world_now: +# Force (re)publication of every publishable %object for this @c <self/> +# %object. Not currently implemented. Intended to aid in recovery +# if RPKI engine and publication engine somehow get out of sync. +# +# +# @subsection bsc_obj <bsc/> object +# +# The @c <bsc/> ("business signing context") %object represents all the BPKI +# data needed to sign outgoing CMS messages. Various other +# %objects include pointers to a @c <bsc/> %object. Whether a particular +# @c <self/> uses only one @c <bsc/> or multiple is a configuration decision +# based on external requirements: the RPKI engine code doesn't care, it +# just cares that, for any %object representing a relationship for which +# it must sign messages, there be a @c <bsc/> %object that it can use to +# produce that signature. +# +# Every @c <bsc/> %object has a bsc_handle, which must be specified for the +# "create", "get", "set", and "destroy" actions. Every @c <bsc/> also has a self_handle +# attribute which indicates the @c <self/> %object with which this @c <bsc/> +# %object is associated. +# +# Payload data which can be configured in a @c <isc/> %object: +# +# @par @c signing_cert (element): +# BPKI certificate to use when generating a signature. +# +# @par @c signing_cert_crl (element): +# CRL which would %list signing_cert if it had been revoked. +# +# Control attributes that can be set to "yes" to force actions: +# +# @par @c generate_keypair: +# Generate a new BPKI keypair and return a PKCS #10 certificate +# request. The resulting certificate, once issued, should be +# configured as this @c <bsc/> %object's signing_cert. +# +# Additional attributes which may be specified when specifying +# "generate_keypair": +# +# @par @c key_type: +# Type of BPKI keypair to generate. "rsa" is both the default and, +# at the moment, the only allowed value. +# +# @par @c hash_alg: +# Cryptographic hash algorithm to use with this keypair. "sha256" +# is both the default and, at the moment, the only allowed value. +# +# @par @c key_length: +# Length in bits of the keypair to be generated. "2048" is both the +# default and, at the moment, the only allowed value. +# +# Replies to "create" and "set" actions that specify "generate-keypair" +# include a <bsc_pkcs10/> element, as do replies to "get" and "list" +# actions for a @c <bsc/> %object for which a "generate-keypair" command has +# been issued. The RPKI engine stores the PKCS #10 request, which +# allows the IRBE to reuse the request if and when it needs to reissue +# the corresponding BPKI signing certificate. +# +# @subsection parent_obj <parent/> object +# +# The @c <parent/> %object represents the RPKI engine's view of a particular +# parent of the current @c <self/> %object in the up-down protocol. Due to +# the way that the resource hierarchy works, a given @c <self/> may obtain +# resources from multiple parents, but it will always have at least one; +# in the case of IANA or an RIR, the parent RPKI engine may be a trivial +# stub. +# +# Every @c <parent/> %object has a parent_handle, which must be specified for +# the "create", "get", "set", and "destroy" actions. Every @c <parent/> also has a +# self_handle attribute which indicates the @c <self/> %object with which this +# @c <parent/> %object is associated, a bsc_handle attribute indicating the @c <bsc/> +# %object to be used when signing messages sent to this parent, and a +# repository_handle indicating the @c <repository/> %object to be used when +# publishing issued by the certificate issued by this parent. +# +# Payload data which can be configured in a @c <parent/> %object: +# +# @par @c peer_contact_uri (attribute): +# HTTP URI used to contact this parent. +# +# @par @c sia_base (attribute): +# The leading portion of an rsync URI that the RPKI engine should +# use when composing the publication URI for %objects issued by the +# RPKI certificate issued by this parent. +# +# @par @c sender_name (attribute): +# Sender name to use in the up-down protocol when talking to this +# parent. The RPKI engine doesn't really care what this value is, +# but other implementations of the up-down protocol do care. +# +# @par @c recipient_name (attribute): +# Recipient name to use in the up-down protocol when talking to this +# parent. The RPKI engine doesn't really care what this value is, +# but other implementations of the up-down protocol do care. +# +# @par @c bpki_cms_cert (element): +# BPKI CMS CA certificate for this @c <parent/>. This is used as part +# of the certificate chain when validating incoming CMS messages If +# the bpki_cms_glue certificate is in use (below), the bpki_cms_cert +# certificate should be issued by the bpki_cms_glue certificate; +# otherwise, the bpki_cms_cert certificate should be issued by the +# bpki_cert certificate in the @c <self/> %object. +# +# @par @c bpki_cms_glue (element): +# Another BPKI CMS CA certificate for this @c <parent/>, usually not +# needed. Certain pathological cross-certification cases require a +# two-certificate chain due to issuer name conflicts. If used, the +# bpki_cms_glue certificate should be the issuer of the +# bpki_cms_cert certificate and should be issued by the bpki_cert +# certificate in the @c <self/> %object; if not needed, the +# bpki_cms_glue certificate should be left unset. +# +# Control attributes that can be set to "yes" to force actions: +# +# @par @c rekey: +# This is like the rekey command in the @c <self/> %object, but limited +# to RPKI CAs under this parent. +# +# @par @c reissue: +# This is like the reissue command in the @c <self/> %object, but limited +# to RPKI CAs under this parent. +# +# @par @c revoke: +# This is like the revoke command in the @c <self/> %object, but limited +# to RPKI CAs under this parent. +# +# @subsection child_obj <child/> object +# +# The @c <child/> %object represents the RPKI engine's view of particular +# child of the current @c <self/> in the up-down protocol. +# +# Every @c <child/> %object has a child_handle, which must be specified for the +# "create", "get", "set", and "destroy" actions. Every @c <child/> also has a +# self_handle attribute which indicates the @c <self/> %object with which this +# @c <child/> %object is associated. +# +# Payload data which can be configured in a @c <child/> %object: +# +# @par @c bpki_cert (element): +# BPKI CA certificate for this @c <child/>. This is used as part of +# the certificate chain when validating incoming TLS and CMS +# messages. If the bpki_glue certificate is in use (below), the +# bpki_cert certificate should be issued by the bpki_glue +# certificate; otherwise, the bpki_cert certificate should be issued +# by the bpki_cert certificate in the @c <self/> %object. +# +# @par @c bpki_glue (element): +# Another BPKI CA certificate for this @c <child/>, usually not needed. +# Certain pathological cross-certification cases require a +# two-certificate chain due to issuer name conflicts. If used, the +# bpki_glue certificate should be the issuer of the bpki_cert +# certificate and should be issued by the bpki_cert certificate in +# the @c <self/> %object; if not needed, the bpki_glue certificate +# should be left unset. +# +# Control attributes that can be set to "yes" to force actions: +# +# @par @c reissue: +# Not implemented, may be removed from protocol. +# +# @subsection repository_obj <repository/> object +# +# The @c <repository/> %object represents the RPKI engine's view of a +# particular publication repository used by the current @c <self/> %object. +# +# Every @c <repository/> %object has a repository_handle, which must be +# specified for the "create", "get", "set", and "destroy" actions. Every +# @c <repository/> also has a self_handle attribute which indicates the @c <self/> +# %object with which this @c <repository/> %object is associated. +# +# Payload data which can be configured in a @c <repository/> %object: +# +# @par @c peer_contact_uri (attribute): +# HTTP URI used to contact this repository. +# +# @par @c bpki_cms_cert (element): +# BPKI CMS CA certificate for this @c <repository/>. This is used as part +# of the certificate chain when validating incoming CMS messages If +# the bpki_cms_glue certificate is in use (below), the bpki_cms_cert +# certificate should be issued by the bpki_cms_glue certificate; +# otherwise, the bpki_cms_cert certificate should be issued by the +# bpki_cert certificate in the @c <self/> %object. +# +# @par @c bpki_cms_glue (element): +# Another BPKI CMS CA certificate for this @c <repository/>, usually not +# needed. Certain pathological cross-certification cases require a +# two-certificate chain due to issuer name conflicts. If used, the +# bpki_cms_glue certificate should be the issuer of the +# bpki_cms_cert certificate and should be issued by the bpki_cert +# certificate in the @c <self/> %object; if not needed, the +# bpki_cms_glue certificate should be left unset. +# +# At present there are no control attributes for @c <repository/> %objects. +# +# @subsection route_origin_obj <route_origin/> object +# +# This section is out-of-date. The @c <route_origin/> %object +# has been replaced by the @c <list_roa_requests/> IRDB query, +# but the documentation for that hasn't been written yet. +# +# The @c <route_origin/> %object is a kind of prototype for a ROA. It +# contains all the information needed to generate a ROA once the RPKI +# engine obtains the appropriate RPKI certificates from its parent(s). +# +# Note that a @c <route_origin/> %object represents a ROA to be generated on +# behalf of @c <self/>, not on behalf of a @c <child/>. Thus, a hosted entity +# that has no children but which does need to generate ROAs would be +# represented by a hosted @c <self/> with no @c <child/> %objects but one or +# more @c <route_origin/> %objects. While lumping ROA generation in with +# the other RPKI engine activities may seem a little odd at first, it's +# a natural consequence of the design requirement that the RPKI daemon +# never transmit private keys across the network in any form; given this +# requirement, the RPKI engine that holds the private keys for an RPKI +# certificate must also be the engine which generates any ROAs that +# derive from that RPKI certificate. +# +# The precise content of the @c <route_origin/> has changed over time as +# the underlying ROA specification has changed. The current +# implementation as of this writing matches what we expect to see in +# draft-ietf-sidr-roa-format-03, once it is issued. In particular, note +# that the exactMatch boolean from the -02 draft has been replaced by +# the prefix and maxLength encoding used in the -03 draft. +# +# Payload data which can be configured in a @c <route_origin/> %object: +# +# @par @c asn (attribute): +# Autonomous System Number (ASN) to place in the generated ROA. A +# single ROA can only grant authorization to a single ASN; multiple +# ASNs require multiple ROAs, thus multiple @c <route_origin/> %objects. +# +# @par @c ipv4 (attribute): +# %List of IPv4 prefix and maxLength values, see below for format. +# +# @par @c ipv6 (attribute): +# %List of IPv6 prefix and maxLength values, see below for format. +# +# Control attributes that can be set to "yes" to force actions: +# +# @par @c suppress_publication: +# Not implemented, may be removed from protocol. +# +# The lists of IPv4 and IPv6 prefix and maxLength values are represented +# as comma-separated text strings, with no whitespace permitted. Each +# entry in such a string represents a single prefix/maxLength pair. +# +# ABNF for these address lists: +# +# @verbatim +# +# <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ] +# ; Where <max_prefixlen> defaults to the same +# ; value as <prefixlen>. +# +# <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> ) +# +# @endverbatim +# +# For example, @c "10.0.1.0/24-32,10.0.2.0/24", which is a shorthand +# form of @c "10.0.1.0/24-32,10.0.2.0/24-24". +# +# @section irdb_queries Operations initiated by the RPKI engine +# +# The left-right protocol also includes queries from the RPKI engine +# back to the IRDB. These queries do not follow the message-passing +# pattern used in the IRBE-initiated part of the protocol. Instead, +# there's a single query back to the IRDB, with a corresponding +# response. The CMS encoding are the same as in the rest of +# the protocol, but the BPKI certificates will be different as the +# back-queries and responses form a separate communication channel. +# +# @subsection list_resources_msg <list_resources/> messages +# +# The @c <list_resources/> query and response allow the RPKI engine to ask +# the IRDB for information about resources assigned to a particular +# child. The query must include both a @c "self_handle" attribute naming +# the @c <self/> that is making the request and also a @c "child_handle" +# attribute naming the child that is the subject of the query. The +# query and response also allow an optional @c "tag" attribute of the +# same form used elsewhere in this protocol, to allow batching. +# +# A @c <list_resources/> response includes the following attributes, along +# with the @c tag (if specified), @c self_handle, and @c child_handle copied +# from the request: +# +# @par @c valid_until: +# A timestamp indicating the date and time at which certificates +# generated by the RPKI engine for these data should expire. The +# timestamp is expressed as an XML @c xsd:dateTime, must be +# expressed in UTC, and must carry the "Z" suffix indicating UTC. +# +# @par @c asn: +# A %list of autonomous sequence numbers, expressed as a +# comma-separated sequence of decimal integers with no whitespace. +# +# @par @c ipv4: +# A %list of IPv4 address prefixes and ranges, expressed as a +# comma-separated %list of prefixes and ranges with no whitespace. +# See below for format details. +# +# @par @c ipv6: +# A %list of IPv6 address prefixes and ranges, expressed as a +# comma-separated %list of prefixes and ranges with no whitespace. +# See below for format details. +# +# Entries in a %list of address prefixes and ranges can be either +# prefixes, which are written in the usual address/prefixlen notation, +# or ranges, which are expressed as a pair of addresses denoting the +# beginning and end of the range, written in ascending order separated +# by a single "-" character. This format is superficially similar to +# the format used for prefix and maxLength values in the @c <route_origin/> +# %object, but the semantics differ: note in particular that +# @c <route_origin/> %objects don't allow ranges, while @c <list_resources/> +# messages don't allow a maxLength specification. +# +# @section left_right_error_handling Error handling +# +# Error in this protocol are handled at two levels. +# +# Since all messages in this protocol are conveyed over HTTP +# connections, basic errors are indicated via the HTTP response code. +# 4xx and 5xx responses indicate that something bad happened. Errors +# that make it impossible to decode a query or encode a response are +# handled in this way. +# +# Where possible, errors will result in a @c <report_error/> message which +# takes the place of the expected protocol response message. +# @c <report_error/> messages are CMS-signed XML messages like the rest of +# this protocol, and thus can be archived to provide an audit trail. +# +# @c <report_error/> messages only appear in replies, never in queries. +# The @c <report_error/> message can appear on either the "forward" (IRBE +# as client of RPKI engine) or "back" (RPKI engine as client of IRDB) +# communication channel. +# +# The @c <report_error/> message includes an optional @c "tag" attribute to +# assist in matching the error with a particular query when using +# batching, and also includes a @c "self_handle" attribute indicating the +# @c <self/> that issued the error. +# +# The error itself is conveyed in the @c error_code (attribute). The +# value of this attribute is a token indicating the specific error that +# occurred. At present this will be the name of a Python exception; the +# production version of this protocol will nail down the allowed error +# tokens here, probably in the RelaxNG schema. +# +# The body of the @c <report_error/> element itself is an optional text +# string; if present, this is debugging information. At present this +# capabilty is not used, debugging information goes to syslog. + +## @page Publication Publication protocol +# +# The %publication protocol is really two separate client/server +# protocols, between different parties. The first is a configuration +# protocol for an IRBE to use to configure a %publication engine, +# the second is the interface by which authorized clients request +# %publication of specific objects. +# +# Much of the architecture of the %publication protocol is borrowed +# from the @ref Left-Right "left-right protocol": like the +# left-right protocol, the %publication protocol uses CMS-wrapped XML +# over HTTP with the same eContentType OID and the same HTTP +# content-type, and the overall style of the XML messages is very +# similar to the left-right protocol. All operations allow an +# optional "tag" attribute to allow batching. +# +# The %publication engine operates a single HTTP server which serves +# both of these subprotocols. The two subprotocols share a single +# server port, but use distinct URLs to allow demultiplexing. +# +# @section Publication-control Publication control subprotocol +# +# The control subprotocol reuses the message-passing design of the +# left-right protocol. Configured objects support the "create", "set", +# "get", "list", and "destroy" actions, or a subset thereof when the +# full set of actions doesn't make sense. +# +# @subsection config_obj <config/> object +# +# The <config/> %object allows configuration of data that apply to the +# entire %publication server rather than a particular client. +# +# There is exactly one <config/> %object in the %publication server, and +# it only supports the "set" and "get" actions -- it cannot be created +# or destroyed. +# +# Payload data which can be configured in a <config/> %object: +# +# @par @c bpki_crl (element): +# This is the BPKI CRL used by the %publication server when +# signing the CMS wrapper on responses in the %publication +# subprotocol. As the CRL must be updated at regular intervals, +# it's not practical to restart the %publication server when the +# BPKI CRL needs to be updated. The BPKI model doesn't require +# use of a BPKI CRL between the IRBE and the %publication server, +# so we can use the %publication control subprotocol to update the +# BPKI CRL. +# +# @subsection client_obj <client/> object +# +# The <client/> %object represents one client authorized to use the +# %publication server. +# +# The <client/> %object supports the full set of "create", "set", "get", +# "list", and "destroy" actions. Each client has a "client_handle" +# attribute, which is used in responses and must be specified in "create", "set", +# "get", or "destroy" actions. +# +# Payload data which can be configured in a <client/> %object: +# +# @par @c base_uri (attribute): +# This is the base URI below which this client is allowed to publish +# data. The %publication server may impose additional constraints in +# the case of a child publishing beneath its parent. +# +# @par @c bpki_cert (element): +# BPKI CA certificate for this <client/>. This is used as part of +# the certificate chain when validating incoming TLS and CMS +# messages. If the bpki_glue certificate is in use (below), the +# bpki_cert certificate should be issued by the bpki_glue +# certificate; otherwise, the bpki_cert certificate should be issued +# by the %publication engine's bpki_ta certificate. +# +# @par @c bpki_glue (element): +# Another BPKI CA certificate for this <client/>, usually not +# needed. Certain pathological cross-certification cases require a +# two-certificate chain due to issuer name conflicts. If used, the +# bpki_glue certificate should be the issuer of the bpki_cert +# certificate and should be issued by the %publication engine's +# bpki_ta certificate; if not needed, the bpki_glue certificate +# should be left unset. +# +# @section Publication-publication Publication subprotocol +# +# The %publication subprotocol is structured somewhat differently from +# the %publication control protocol. Objects in the %publication +# subprotocol represent objects to be published or objects to be +# withdrawn from %publication. Each kind of %object supports two actions: +# "publish" and "withdraw". In each case the XML element representing +# hte %object to be published or withdrawn has a "uri" attribute which +# contains the %publication URI. For "publish" actions, the XML element +# body contains the DER %object to be published, encoded in Base64; for +# "withdraw" actions, the XML element body is empty. +# +# In theory, the detailed access control for each kind of %object might +# be different. In practice, as of this writing, access control for all +# objects is a simple check that the client's @c "base_uri" is a leading +# substring of the %publication URI. Details of why access control might +# need to become more complicated are discussed in a later section. +# +# @subsection certificate_obj <certificate/> object +# +# The <certificate/> %object represents an RPKI certificate to be +# published or withdrawn. +# +# @subsection crl_obj <crl/> object +# +# The <crl/> %object represents an RPKI CRL to be published or withdrawn. +# +# @subsection manifest_obj <manifest/> object +# +# The <manifest/> %object represents an RPKI %publication %manifest to be +# published or withdrawn. +# +# Note that part of the reason for the batching support in the +# %publication protocol is because @em every %publication or withdrawal +# action requires a new %manifest, thus every %publication or withdrawal +# action will involve at least two objects. +# +# @subsection roa_obj <roa/> object +# +# The <roa/> %object represents a ROA to be published or withdrawn. +# +# @section publication_error_handling Error handling +# +# Error in this protocol are handled at two levels. +# +# Since all messages in this protocol are conveyed over HTTP +# connections, basic errors are indicated via the HTTP response code. +# 4xx and 5xx responses indicate that something bad happened. Errors +# that make it impossible to decode a query or encode a response are +# handled in this way. +# +# Where possible, errors will result in a <report_error/> message which +# takes the place of the expected protocol response message. +# <report_error/> messages are CMS-signed XML messages like the rest of +# this protocol, and thus can be archived to provide an audit trail. +# +# <report_error/> messages only appear in replies, never in +# queries. The <report_error/> message can appear in both the +# control and publication subprotocols. +# +# The <report_error/> message includes an optional @c "tag" attribute to +# assist in matching the error with a particular query when using +# batching. +# +# The error itself is conveyed in the @c error_code (attribute). The +# value of this attribute is a token indicating the specific error that +# occurred. At present this will be the name of a Python exception; the +# production version of this protocol will nail down the allowed error +# tokens here, probably in the RelaxNG schema. +# +# The body of the <report_error/> element itself is an optional text +# string; if present, this is debugging information. At present this +# capabilty is not used, debugging information goes to syslog. +# +# @section publication_access_control Additional access control considerations. +# +# As detailed above, the %publication protocol is trivially simple. This +# glosses over two bits of potential complexity: +# +# @li In the case where parent and child are sharing a repository, we'd +# like to nest child under parent, because testing has demonstrated +# that even on relatively slow hardware the delays involved in +# setting up separate rsync connections tend to dominate +# synchronization time for relying parties. +# +# @li The repository operator might also want to do some checks to +# assure itself that what it's about to allow the RPKI engine to +# publish is not dangerous toxic waste. +# +# The up-down protocol includes a mechanism by which a parent can +# suggest a %publication URI to each of its children. The children are +# not required to accept this hint, and the children must make separate +# arrangements with the repository operator (who might or might not be +# the same as the entity that hosts the children's RPKI engine +# operations) to use the suggested %publication point, but if everything +# works out, this allows children to nest cleanly under their parents +# %publication points, which helps reduce synchronization time for +# relying parties. +# +# In this case, one could argue that the %publication server is +# responsible for preventing one of its clients (the child in the above +# description) from stomping on data published by another of its clients +# (the parent in the above description). This goes beyond the basic +# access check and requires the %publication server to determine whether +# the parent has given its consent for the child to publish under the +# parent. Since the RPKI certificate profile requires the child's +# %publication point to be indicated in an SIA extension in a certificate +# issued by the parent to the child, the %publication engine can infer +# this permission from the parent's issuance of a certificate to the +# child. Since, by definition, the parent also uses this %publication +# server, this is an easy check, as the %publication server should +# already have the parent's certificate available by the time it needs +# to check the child's certificate. +# +# The previous paragraph only covers a "publish" action for a +# <certificate/> %object. For "publish" actions on other +# objects, the %publication server would need to trace permission back +# to the certificate issued by the parent; for "withdraw" actions, +# the %publication server would have to perform the same checks it +# would perform for a "publish" action, using the current published +# data before withdrawing it. The latter in turn implies an ordering +# constraint on "withdraw" actions in order to preserve the data +# necessary for these access control decisions; as this may prove +# impractical, the %publication server may probably need to make +# periodic sweeps over its published data looking for orphaned +# objects, but that's probably a good idea anyway. +# +# Note that, in this %publication model, any agreement that the +# repository makes to publish the RPKI engine's output is conditional +# upon the %object to be published passing whatever access control checks +# the %publication server imposes. + +## @page sql-schemas SQL database schemas +# +# @li @subpage rpkid-sql "rpkid database schema" +# @li @subpage pubd-sql "pubd database schema" +# @li @subpage irdbd-sql "irdbd database schema" + +## @page rpkid-sql rpkid SQL schema +# +# @image html rpkid.png "Diagram of rpkid.sql" +# @image latex rpkid.eps "Diagram of rpkid.sql" height=\textheight +# +# @verbinclude rpkid.sql + +## @page pubd-sql pubd SQL Schema +# +# @image html pubd.png "Diagram of pubd.sql" +# @image latex pubd.eps "Diagram of pubd.sql" width=\textwidth +# +# @verbinclude pubd.sql + +## @page irdbd-sql irdbd SQL Schema +# +# @image html irdbd.png "Diagram of irdbd.sql" +# @image latex irdbd.eps "Diagram of irdbd.sql" width=\textwidth +# +# @verbinclude irdbd.sql + +## @page bpki-model BPKI model +# +# The "business PKI" (BPKI) is the PKI used to authenticate +# communication on the up-down, left-right, and %publication protocols. +# BPKI certificates are @em not resource PKI (RPKI) certificates. The +# BPKI is a separate PKI that represents relationships between the +# various entities involved in the production side of the RPKI system. +# In most cases the BPKI tree will follow existing business +# relationships, hence the "B" (Business) in "BPKI". +# +# Setup of the BPKI is handled by the back end; for the most part, +# rpkid and pubd just use the result. The one place where the engines +# are directly involved in creation of new BPKI certificates is in the +# production of end-entity certificates for use by the engines. +# +# For the most part an ordinary user of this package need not worry +# about the details explained here, as the +# @ref MyRPKI "myrpki tool" +# takes care of all of this. However, users who want to understand +# what's going on behind the scenes or who have needs too complex for +# the myrpki tool to handle might want to understand the underlying +# model. +# +# There are a few design principals that underly the chosen BPKI model: +# +# @li Each engine should rely on a single BPKI trust anchor which is +# controlled by the back end entity that runs the engine; all +# other trust material should be cross-certified into the engine's +# BPKI tree. +# +# @li Private keys must never transit the network. +# +# @li Except for end entity certificates, the engine should only have +# access to the BPKI certificates; in particular, the private key +# for the BPKI trust anchor should not be accessible to the engine. +# +# @li The number of BPKI keys and certificates that the engine has to +# manage should be no larger than is necessary. +# +# rpkid's hosting model adds an additional constraint: rpkid's BPKI +# trust anchor belongs to the entity operating rpkid, but the entities +# hosted by rpkid should have control of their own BPKI private keys. +# This implies the need for an additional layer of BPKI certificate +# hierarchy within rpkid. +# +# Here is a simplified picture of what the BPKI might look like for an +# rpkid operator that hosts two entities, "Alice" and "Ellen": +# +# @image html rpkid-bpki.png +# @image latex rpkid-bpki.eps width=\textwidth +# +# Black objects belong to the hosting entity, blue objects belong to +# the hosted entities, red objects are cross-certified objects from +# the hosted entities' peers. The arrows indicate certificate +# issuance: solid arrows are the ones that rpkid will care about +# during certificate validation, dotted arrows show the origin of the +# EE certificates that rpkid uses to sign CMS and TLS messages. +# +# The certificate tree looks complicated, but the set of certificates +# needed to build any particular validation chain is obvious. +# +# Detailed instructions on how to build a BPKI are beyond the scope of +# this document, but one can handle simple cases using the OpenSSL +# command line tool and cross_certify; the latter is a tool +# designed specifically for the purpose of generating the +# cross-certification certificates needed to splice foreign trust +# material into a BPKI tree. +# +# The BPKI tree for a pubd instance is similar to to the BPKI tree for +# an rpkid instance, but is a bit simpler, as pubd does not provide +# hosting in the same sense that rpkid does: pubd is a relatively +# simple server that publishes objects as instructed by its clients. +# +# Here's a simplified picture of what the BPKI might look like for a +# pubd operator that serves two clients, "Alice" and "Bob": +# +# @image html pubd-bpki.png +# @image latex pubd-bpki.eps width=\textwidth +# +# While it is likely that RIRs (at least) will operate both rpkid and +# pubd instances, the two functions are conceptually separate. As far +# as pubd is concerned, it doesn't matter who operates the rpkid +# instance: pubd just has clients, each of which has trust material +# that has been cross-certified into pubd's BPKI. Similarly, rpkid +# doesn't really care who operates a pubd instance that it's been +# configured to use, it just treats that pubd as a foreign BPKI whose +# trust material has to be cross-certified into its own BPKI. Cross +# certification itself is done by the back end operator, using +# cross_certify or some equivalent tool; the resulting BPKI +# certificates are configured into rpkid and pubd via the left-right +# protocol and the control subprotocol of the publication protocol, +# respectively. +# +# Because the BPKI tree is almost entirely controlled by the operating +# entity, CRLs are not necessary for most of the BPKI. The one +# exception to this is the EE certificates issued under the +# cross-certification points. These EE certificates are generated by +# the peer, not the local operator, and thus require CRLs. Because of +# this, both rpkid and pubd require regular updates of certain BPKI +# CRLs, again via the left-right and publication control protocols. +# +# Because the left-right protocol and the publication control +# subprotocol are used to configure BPKI certificates and CRLs, they +# cannot themselves use certificates and CRLs configured in this way. +# This is why the configuration files for rpkid and pubd require +# static configuration of the left-right and publication control +# certificates. + +# Local Variables: +# mode:python +# compile-command: "cd ../.. && ./config.status && cd rpkid && make docs" +# End: |