diff options
Diffstat (limited to 'rpkid/rpki/__init__.py')
| -rw-r--r-- | rpkid/rpki/__init__.py | 3262 |
1 files changed, 1614 insertions, 1648 deletions
diff --git a/rpkid/rpki/__init__.py b/rpkid/rpki/__init__.py index 38220ba6..98687221 100644 --- a/rpkid/rpki/__init__.py +++ b/rpkid/rpki/__init__.py @@ -20,1660 +20,1626 @@ # since its existance defines the package, it's as sensible a place as # any to put the Doxygen mainpage. -# The "usage" text in the OPERATIONS section is a pain to keep -# syncrhonized with programs like irbe-cli.py which generate their -# usage dynamically. In theory we could address this by running each -# of these programs with the --help option, saving the resulting usage -# message to a file, and including it here using Doxygen's -# "verbinclude" command. There's a similar problem with config files, -# though, and I see no obvious way to automate them. Keeping the -# documentation with the config file options would be nice. Someday. +# The "usage" text for irbe-cli in the OPERATIONS section is generated +# automatically by running the program with its --help command. +# Should do the same with the other programs. Don't yet have a sane +# way to automate options in config files, though. Would be nice. ## @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, -## design documents, a text mirror of portions of APNIC's Wiki, etc. -## -## 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>. -## -## This work is funded by <a href="http://www.arin.net/">ARIN</a>, in -## collaboration with the other RIRs. If you're interested in this -## package you might also be interested in: -## -## @li <a href="http://viewvc.hactrn.net/subvert-rpki.hactrn.net/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> -## @li <a href="http://mirin.apnic.net/resourcecerts/wiki/">APNIC's Wiki</a> -## @li <a href="http://mirin.apnic.net/trac/">APNIC's project Trac instance</a> -## -## Besides the automatically-generated code documentation, this manual -## also includes several sections documenting the overall package: -## -## @li The @subpage Installation "installation instructions" -## @li The @subpage Operation "operation instructions" -## @li A description of the @subpage Left-right "left-right protocol" -## @li A description of the @subpage Publication "publication protocol" +# +# 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, +# design documents, a text mirror of portions of APNIC's Wiki, etc. +# +# 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>. +# +# This work is funded by <a href="http://www.arin.net/">ARIN</a>, in +# collaboration with the other RIRs. If you're interested in this +# package you might also be interested in: +# +# @li <a href="http://viewvc.hactrn.net/subvert-rpki.hactrn.net/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> +# @li <a href="http://mirin.apnic.net/resourcecerts/wiki/">APNIC's Wiki</a> +# @li <a href="http://mirin.apnic.net/trac/">APNIC's project Trac instance</a> +# +# Besides the automatically-generated code documentation, this manual +# also includes several sections documenting the overall package: +# +# @li The @subpage Installation "installation instructions" +# @li The @subpage Operation "operation instructions" +# @li A description of the @subpage Left-right "left-right protocol" +# @li A description of the @subpage Publication "publication protocol" ## @page Installation Installation -## -## Preliminary installation instructions for rpkid et al. These are the -## production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). -## See ../rcynic/README 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. -## -## The first step to running the code is to build the OpenSSL and POW -## binaries. At present the OpenSSL code is just a copy of the stock -## OpenSSL 0.9.8g release, 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 and -## type "make". -## -## @verbatim -## $ cd $top -## $ make -## @endverbatim -## -## This should automatically build everything, in the right order, -## including staticly linking the POW extension module with the OpenSSL -## library to provide RFC 3779 support. -## -## Next, see the %list of required Python modules in rpkid/README. Note -## that the Python code requires Python version 2.5. Install any modules -## that might be missing. -## -## You will also need a MySQL installation. This code was developed -## using MySQL 5.1 and has been tested with MySQL 5.0 and 5.1. -## -## 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. -## You will probably want to test it. All tests should be run from the -## rpkid/ directory. -## -## 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/testbed.sql. The MySQL command line client is usually the -## easiest way to do this, eg: -## -## @verbatim -## $ cd $top/rpkid -## $ mysql -u root -p <testbed.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. +# +# Preliminary installation instructions for rpkid et al. These are the +# production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). +# See ../rcynic/README 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. +# +# The first step to running the code is to build the OpenSSL and POW +# binaries. At present the OpenSSL code is just a copy of the stock +# OpenSSL 0.9.8g release, 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 and +# type "make". +# +# @verbatim +# $ cd $top +# $ make +# @endverbatim +# +# This should automatically build everything, in the right order, +# including staticly linking the POW extension module with the OpenSSL +# library to provide RFC 3779 support. +# +# Next, see the %list of required Python modules in rpkid/README. Note +# that the Python code requires Python version 2.5. Install any modules +# that might be missing. +# +# You will also need a MySQL installation. This code was developed +# using MySQL 5.1 and has been tested with MySQL 5.0 and 5.1. +# +# 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. +# You will probably want to test it. All tests should be run from the +# rpkid/ directory. +# +# 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/testbed.sql. The MySQL command line client is usually the +# easiest way to do this, eg: +# +# @verbatim +# $ cd $top/rpkid +# $ mysql -u root -p <testbed.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. ## @page Operation Operation -## -## Preliminary operation instructions for rpkid et al. These are the -## production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). -## See ../rcynic/README for relying party tools. -## -## @warning -## rpkid is still in development, and the code changes more often than -## the hand-maintained portions of this documentation. The following -## text was reasonably accurate at the time it was written but may be -## obsolete by the time you read it. -## -## 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 @c rpkid.py: -## The main RPKI engine daemon. -## -## @li @c pubd.py: -## The publication engine daemon. -## -## @li @c rootd.py: -## 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 @c irdbd.py: -## A sample implementation of an IR database daemon. -## rpkid calls into this to perform lookups via the -## left-right protocol. -## -## @li @c irbe-cli.py: -## A command-line client for the left-right control -## protocol. -## -## @li @c irbe-setup.py: -## An example of a script to set up the mappings between -## the IRDB and rpkid's own database, using the -## left-right control protocol. -## -## @li @c cronjob.py: -## A trivial HTTP client used to drive rpkid cron events. -## -## @li @c testbed.py: -## A test tool for running a collection of rpkid and irdb -## instances under common control, driven by a unified -## test script. -## -## @li @c testpoke.py: -## A simple client for the up-down protocol, mostly -## compatable with APNIC's rpki_poke.pl tool. -## -## 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 testbed.py 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, -## starting rpkid, rootd, and irdbd, using the left-right control -## protocol to set up rpkid's internal state, and setting up a cron job -## to invoke rpkid's cron action at regular intervals. 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. -## -## Note that the publication protocol isn't fully specified yet, much -## less implmenented. At the moment rpkid just writes its outputs to a -## local directory tree. -## -## Note that the full event-driven model for rpkid hasn't yet been -## implemented. The design is intended to allow an arbitrary number of -## hosted RPKI engines to run in a single rpkid instance, but without the -## event-driven tasking model one has to set up a separate rpkid instance -## for each hosted RPKI engine. -## -## At present the daemon programs all run in foreground, that is, if one -## wants them to run in background one must do so manually, eg, using -## Bourne shell syntax: -## -## @verbatim -## $ python whatever.py & -## $ echo >whatever.pid "$!" -## @endverbatim -## -## All of the daemons use syslog. At present they all set LOG_PERROR, so -## all logging also goes to stderr. -## -## -## @section rpkid rpkid.py -## -## 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 left-right protocol, followed by dynamic -## configuration via the left-right protocol. In production use the -## latter stage would be handled by the IRBE stub; for test and -## develoment purposes it's handled by the irbe-cli.py command line -## interface or by the testbed.py test framework. -## -## rpkid stores dynamic data in an SQL database, which must have been -## created for it, as explained in the installation guide. -## -## The 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: -## -## @li @c startup-message: -## String to %log on startup, useful when -## debugging a collection of rpkid instances at -## once. -## -## @li @c sql-username: -## Username to hand to MySQL when connecting to -## rpkid's database. -## -## @li @c sql-database: -## MySQL's database name for rpkid's database. -## -## @li @c sql-password: -## Password to hand to MySQL when connecting to -## rpkid's database. -## -## @li @c cms-ta-irdb: -## Name of file containing CMS trust anchor to -## use when authenticating messages from irdbd. -## -## @li @c cms-ta-irbe: -## Name of file containing CMS trust anchor to -## use when authenticating control messages from -## IRBE. -## -## @li @c cms-key: -## Name of file containing RSA key to use when -## signing CMS messages to IRBE or irdbd. -## -## @li @c cms-cert: -## Name(s) of file(s) containing certificate(s) -## to include in CMS wrapper when signing -## messages to IRBE or irdbd. You can specify -## more than one certificate using OpenSSL-style -## subscripts: cms-cert.0, cms-cert.1, etc. -## -## @li @c https-key: -## Name of file containing RSA key to use, both -## in the HTTPS server role (for both up-down and -## left-right protocols) and in the HTTPS client -## role (left-right protocol only). -## -## @li @c https-cert: -## Name(s) of file(s) containing certificate(s) -## to use in same contexts where https-key is -## used. You can specify more than one -## certificate using OpenSSL-style subscripts: -## https-cert.0, https-cert.1, etc. -## -## @li @c https-ta: -## Name of file containing trust anchor to use -## when verifying irdbd's HTTPS server -## certificate. -## -## @li @c irdb-url: -## Service URL for irdbd. Must be a %https:// URL. -## -## @li @c https-server-host: -## Hostname or IP address on which to listen for -## HTTPS connections. Current default is -## INADDR_ANY (IPv4 0.0.0.0); this will need to -## be hacked to support IPv6 for production. -## -## @li @c https-server-port: -## TCP port on which to listen for HTTPS -## connections. -## -## -## @section pubd pubd.py -## -## 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 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. -## -## The 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: -## -## @li @c sql-username: -## Username to hand to MySQL when connecting to -## pubd's database. -## -## @li @c sql-database: -## MySQL's database name for pubd's database. -## -## @li @c sql-password: -## Password to hand to MySQL when connecting to -## pubd's database. -## -## @li @c bpki-ta: -## Name of file containing master BPKI trust -## anchor for pubd. All BPKI validation in pubd -## traces back to this trust anchor. -## -## @li @c irbe-cert: -## Name of file containing BPKI certificate used -## by IRBE when talking to pubd. -## -## @li @c pubd-cert: -## Name of file containing BPKI certificate used -## by pubd. -## -## @li @c pubd-key: -## Name of file containing RSA key corresponding -## to @c pubd-cert. -## -## @li @c server-host: -## Hostname or IP address on which to listen for -## HTTPS connections. Current default is -## INADDR_ANY (IPv4 0.0.0.0); this will need to -## be hacked to support IPv6 for production. -## -## @li @c server-port: -## TCP port on which to listen for HTTPS -## connections. -## -## @li @c publication-base: -## Path to base of filesystem tree where pubd -## should store publishable objects. Default is -## "publication/". -## -## -## @section rootd rootd.py -## -## 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. -## -## The 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: -## -## @li @c cms-ta: -## Name of file containing trust anchor to use -## when verifying CMS up-down queries. -## -## @li @c cms-key: -## Name of file containing RSA key to use when -## signing CMS up-down replies. -## -## @li @c cms-cert: -## Name(s) of file(s) containing certificate(s) -## to include in CMS wrapper when signing up-down -## replies. You can specify more than one -## certificate using OpenSSL-style subscripts: -## cms-cert.0, cms-cert.1, etc. -## -## @li @c https-key: -## Name of file containing RSA key to use in the -## HTTPS server role for the up-down protocol. -## -## @li @c https-cert: -## Name(s) of file(s) containing certificate(s) -## to use in the HTTPS server role for the -## up-down protocol. You can specify more than -## one certificate using OpenSSL-style -## subscripts: https-cert.0, https-cert.1, -## etc. -## -## @li @c https-server-host: -## Hostname or IP address on which to listen for -## HTTPS connections. Default is localhost. -## -## @li @c https-server-port: -## TCP port on which to listen for HTTPS -## connections. -## -## @li @c rpki-key: -## Name of file containing RSA key to use in -## signing resource certificates. -## -## @li @c rpki-issuer: -## Name of file containing self-signed root -## resource certificate corresponding to -## rpki-key. -## -## @li @c rpki-subject-filename: -## Name of file that rootd should use to save the -## one and only certificate it issues. -## -## @li @c rpki-pkcs10-filename: -## 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. -## -## -## @section irdbd irdbd.py -## -## 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 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 IDs (foreign keys into rpkid's database, basicly) in the -## IRDB. The irbe-setup.py program shows an example of how to do this. -## -## 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: -## -## @li @c startup-message: -## String to %log on startup, useful when -## debugging a collection of irdbd instances at -## once. -## -## @li @c sql-username: -## Username to hand to MySQL when connecting to -## irdbd's database. -## -## @li @c sql-database: -## MySQL's database name for irdbd's database. -## -## @li @c sql-password: -## Password to hand to MySQL when connecting to -## irdbd's database. -## -## @li @c cms-ta: -## Name of file containing CMS trust anchor to -## use when authenticating messages from rpkid. -## -## @li @c cms-key: -## Name of file containing RSA key to use when -## signing CMS messages to rpkid. -## -## @li @c cms-cert: -## Name(s) of file(s) containing certificate(s) -## to include in CMS wrapper when signing -## messages to rpkid. You can specify more than -## one certificate using OpenSSL-style -## subscripts: cms-cert.0, cms-cert.1, etc. -## -## @li @c https-key: -## Name of file containing RSA key to use in the -## HTTPS server role when listening for -## connections from rpkid. -## -## @li @c https-cert: -## Name(s) of file(s) containing certificate(s) -## to use in the HTTPS server role when listening -## for connections from rpkid. You can specify -## more than one certificate using OpenSSL-style -## subscripts: https-cert.0, https-cert.1, etc. -## -## @li @c https-url: -## Service URL for irdbd. Must be a %https:// URL. -## -## -## @section irdbd_cli irbe-cli.py -## -## irbe-cli is a simple command line client for the control subset of the -## left-right protocol. In production use this functionality would be -## part of the IRBE stub. -## -## Basic configuration of irbe-cli is handled via a %config file. The -## specific action or actions to be performed are specified on the -## command line, and map closely to the left-right protocol itself. -## -## At present the user is assumed to be able to read the (XML) left-right -## protocol messages, and with one exception, no attempt is made to -## interpret the responses other than to check for errors. The one -## exception is that, if the @c --pem_out option is specified on the command -## line, any PKCS \#10 requests received from rpkid will be written in PEM -## format to that file; this makes it easier to hand these requests off -## to the business PKI in order to issue signing certs corresponding to -## newly generated business keys. -## -## @verbatim -## Usage: irbe-cli.py --config= --help --pem_out= -## -## parent --action= --tag= --self_id= --parent_id= -## --bsc_id= --repository_id= --peer_contact_uri= -## --sia_base= --sender_name= --recipient_name= -## --bpki_cms_cert= --bpki_cms_glue= -## --bpki_https_cert= --bpki_https_glue= -## --rekey --reissue --revoke -## -## repository --action= --tag= --self_id= --repository_id= -## --bsc_id= --peer_contact_uri= -## --bpki_cms_cert= --bpki_cms_glue= -## --bpki_https_cert= --bpki_https_glue= -## -## self --action= --tag= --self_id= --crl_interval= -## --bpki_cert= --bpki_glue= -## --rekey --reissue --revoke -## --run_now --publish_world_now -## -## child --action= --tag= --self_id= --child_id= -## --bsc_id= --bpki_cms_cert= --bpki_cms_glue= --reissue -## -## route_origin --action= --tag= --self_id= --route_origin_id= -## --as_number= --ipv4= --ipv6= --suppress_publication -## -## bsc --action= --tag= --self_id= --bsc_id= -## --key_type= --hash_alg= --key_length= --signing_cert= -## --signing_cert_crl= --generate_keypair -## @endverbatim -## -## Global options (@c --config, @c --help, @c --pem_out) come first, then zero or -## more commands (parent, repository, self, child, route_origin, bsc), -## each followed by its own set of options. The commands map to -## elements in the left-right protocol, and the command-specific options -## map to attributes or subelements for those commands. -## -## @c --action is one of @c create, @c set, @c get, @c %list, or @c -## destroy; exactly one of these must be specified for each command. -## -## @c --type is @c query or @c reply; since irbe-cli is a client, -## @c query is the default. -## -## @c --tag is an optional arbitrary tag (think IMAP) to simplify -## matching up replies with batched queries. -## -## @c --*_id options refer to the primary keys of previously created -## objects. -## -## The remaining options are specific to the particular commands, and -## follow directly from the left-right protocol specification. -## -## A trailing "=" in the above option summary indicates that an option -## takes a value, eg, "--action create" or "--action=create". Options -## without a trailing "=" correspond to boolean control attributes. -## -## The default %config file for irbe-cli is irbe.conf, start rpkid with -## "-c filename" (or "--config filename") to choose a different %config -## file. All options are in the section "[irbe-cli]". Certificates, -## keys, and trust anchors may be in either DER or PEM format. -## -## %Config file options: -## -## @li @c cms-ta: -## Name of file containing CMS trust anchor to -## use when authenticating messages from rpkid. -## -## @li @c cms-key: -## Name of file containing RSA key to use when -## signing CMS messages to rpkid. -## -## @li @c cms-cert: -## Name(s) of file(s) containing certificate(s) -## to include in CMS wrapper when signing -## messages to rpkid. You can specify more than -## one certificate using OpenSSL-style -## subscripts: cms-cert.0, cms-cert.1, etc. -## -## @li @c https-key: -## Name of file containing RSA key to use in the -## HTTPS client role when contacting rpkid. -## -## @li @c https-cert: -## Name(s) of file(s) containing certificate(s) -## to use in the HTTPS client role when -## contacting rpkid. You can specify more than -## one certificate using OpenSSL-style -## subscripts: https-cert.0, https-cert.1, -## etc. -## -## @li @c https-ta: -## Name of file containing trust anchor to use -## when verifying rpkid's HTTPS server -## certificate. -## -## @li @c https-url: -## Service URL for rpkid. Must be a %https:// URL. -## -## -## @section irbe_setup irbe-setup.py config file -## -## The default %config file is irbe.conf, start rpkid with "-c filename" -## to choose a different %config file. Most options are in the section -## "[irbe-cli]", but a few are in the section "[irdbd]". Certificates, -## keys, and trust anchors may be in either DER or PEM format. -## -## Options in the "[irbe-cli]" section: -## -## @li @c cms-ta: -## Name of file containing CMS trust anchor to -## use when authenticating messages from rpkid. -## -## @li @c cms-key: -## Name of file containing RSA key to use when -## signing CMS messages to rpkid. -## -## @li @c cms-cert: -## Name(s) of file(s) containing certificate(s) -## to include in CMS wrapper when signing -## messages to rpkid. You can specify more than -## one certificate using OpenSSL-style -## subscripts: cms-cert.0, cms-cert.1, etc. -## -## @li @c https-key: -## Name of file containing RSA key to use in the -## HTTPS client role when contacting rpkid. -## -## @li @c https-cert: -## Name(s) of file(s) containing certificate(s) -## to use in the HTTPS client role when -## contacting rpkid. You can specify more than -## one certificate using OpenSSL-style -## subscripts: https-cert.0, https-cert.1, -## etc. -## -## @li @c https-ta: -## Name of file containing trust anchor to use -## when verifying rpkid's HTTPS server -## certificate. -## -## @li @c https-url: -## Service URL for rpkid. Must be a %https:// URL. -## -## Options in the "[irdbd]" section: -## -## @li @c sql-username: -## Username to hand to MySQL when connecting to -## irdbd's database. -## -## @li @c sql-database: -## MySQL's database name for irdbd's database. -## -## @li @c sql-password: -## Password to hand to MySQL when connecting to -## irdbd's database. -## -## -## @section cronjob cronjob.py -## -## This is a trivial program to trigger a cron run within rpkid. Once -## rpkid has been converted to the planned event-driven model, this -## function will be handled internally, but for now it has to be -## triggered by an external program. For pseudo-production use one would -## run this program under the system cron daemon. For scripted testing -## it happens to be useful to be able to control when cron cycles occur, -## so at the current stage of code development use of an external trigger -## is a useful feature. -## -## The default %config file is cronjob.conf, start cronjob with "-c -## filename" to choose a different %config file. All options are in the -## section "[cronjob]". Certificates, keys, and trust anchors may be in -## either DER or PEM format. -## -## %Config file options: -## -## @li @c https-key: -## Name of file containing RSA key to use in the -## HTTPS client role when contacting rpkid. -## -## @li @c https-cert: -## Name(s) of file(s) containing certificate(s) -## to use in the HTTPS client role when -## contacting rpkid. You can specify more than -## one certificate using OpenSSL-style -## subscripts: https-cert.0, https-cert.1, -## etc. -## -## @li @c https-ta: -## Name of file containing trust anchor to use -## when verifying rpkid's HTTPS server -## certificate. -## -## @li @c https-url: -## Service URL for rpkid. Must be a %https:// URL. -## -## -## @section testbed testbed.py: -## -## testbed is a test harness to set up and run a collection of rpkid and -## irdbd instances under scripted control. testbed is a very recent -## addition to the toolset and is still evolving rapidly. -## -## Unlike the programs described above, testbed 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. testbed 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. -## -## All of the options in in the first (optional) configuration file are -## just overrides for wired-in default values. In most cases the -## defaults will suffice, and the set of options is still in flux, so -## only a few of the options are described here. The default name for -## this configuration file is testbed.conf, run testbed with "-c -## filename" to change it. -## -## testbed.conf options: -## -## @li @c testbed_dir: -## Working directory into which testbed should write the -## (many) files it generates. Default is "testbed.dir". -## -## @li @c irdb_db_pass: -## MySQL password for the "irdb" user. Default is -## "fnord". You may want to override this. -## -## @li @c rpki_db_pass: -## MySQL password for the "rpki" user. Default is -## "fnord". You may want to override this. -## -## @li @c rootd_sia: -## rsync URI naming a (perhaps fictious) directory to use -## as the id-ad-caRepository SIA value in the generated -## root resource certificate. Default is -## "rsync://wombat.invalid/". You may want to override -## this if you intend to run an rsync server and test -## against the generated results using rcynic. This -## default will likely change if and when testbed learns -## how to run rcynic itself as part of the test suite. -## -## The second configuration file is named testbed.yaml by default, run -## testbed 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". The -## details are still evolving, but here's an example of current usage: -## -## @verbatim -## name: RIR -## valid_for: 2d -## sia_base: "rsync://wombat.invalid/" -## kids: -## - name: LIR0 -## kids: -## - name: Alice -## ipv4: 192.0.2.1-192.0.2.33 -## asn: 64533 -## --- -## - name: Alice -## valid_add: 10 -## --- -## - name: Alice -## add_as: 33 -## valid_add: 2d -## --- -## - name: Alice -## valid_sub: 2d -## --- -## - name: Alice -## valid_for: 10d -## @endverbatim -## -## This specifies an initial layout consisting of an RPKI engine named -## "RIR", with one child "LIR0", which in turn has one child "Alice". -## Alice 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 Alice's resources and makes no other -## modifications. The second subsequent document grants Alice additional -## resources and adds another two days to the validity interval for -## Alice's resources. The next document subtracts two days from the -## validity interval for Alice's resources. The final document sets the -## validity interval for Alice's resources to ten days. -## -## Operators in subsequent (update) documents: -## -## @li @c add_as, @c add_v4, @c add_v6: -## These add ASN, IPv4, or IPv6 resources, respectively. -## -## @li @c sub_as, @c sub_v4, @c sub_v6: -## These subtract resources. -## -## @li @c valid_until: -## Set an absolute expiration date. -## -## @li @c valid_for: -## Set a relative expiration date. -## -## @li @c valid_add, @c valid_sub: -## Add to or subtract from validity interval. -## -## @li @c sleep [interval]: -## Sleep for specified interval, or until testbed receives a SIGALRM signal. -## -## 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". -## -## -## @section testpoke testpoke.py -## -## This is a command-line client for the up-down protocol. Unlike all of -## the above programs, testpoke does not accept a %config file in -## OpenSSL-compatable format at all. Instead, it is configured -## exclusively by a YAML script. testpoke's design was constrained by a -## desire to have it be compatable with APNIC's rpki_poke.pl tool, so -## that the two tools could use a common configuration language to -## simplify scripted testing. There are minor variations due to slightly -## different feature sets, but YAML files intended for one program will -## usually work with the other. -## -## README for APNIC's tool describing the input language can be found at -## http://mirin.apnic.net/svn/rpki_engine/branches/gary-poker/client/poke/README -## -## testpoke.py takes a simplified command line and uses only one YAML -## input file. -## -## @verbatim -## Usage: python testpoke.py [ { -y | --yaml } configfile ] -## [ { -r | --request } requestname ] -## [ { -h | --help } ] -## @endverbatim -## -## Default configuration file is testpoke.yaml, override with --yaml -## option. -## -## The --request option specifies the specific command within the YAML -## file to execute. -## -## Sample configuration file: -## -## @verbatim -## --- -## # Sample YAML configuration file for testpoke.py -## -## version: 1 -## posturl: https://localhost:4433/up-down/1 -## recipient-id: wombat -## sender-id: "1" -## -## cms-cert-file: biz-certs/Frank-EE.cer -## cms-key-file: biz-certs/Frank-EE.key -## cms-ca-cert-file: biz-certs/Bob-Root.cer -## cms-cert-chain-file: [ biz-certs/Frank-CA.cer ] -## -## ssl-cert-file: biz-certs/Frank-EE.cer -## ssl-key-file: biz-certs/Frank-EE.key -## ssl-ca-cert-file: biz-certs/Bob-Root.cer -## -## requests: -## list: -## type: list -## issue: -## type: issue -## class: 1 -## sia: [ "rsync://bandicoot.invalid/some/where/" ] -## revoke: -## type: revoke -## class: 1 -## ski: "CB5K6APY-4KcGAW9jaK_cVPXKX0" -## @endverbatim -## -## testpoke adds one extension to the language described in APNIC's -## README: the cms-cert-chain-* and ssl-cert-chain-* options, which allow -## one to specify a chain of intermediate certificates to be presented in -## the CMS or TLS protocol. APNIC's initial implementation required -## direct knowledge of the issuing certificate (ie, it supported a -## maximum chain length of one); subsequent APNIC code changes have -## probably relaxed this restriction, and with luck APNIC has copied -## testpoke's syntax to express chains of intermediate certificates. +# +# Preliminary operation instructions for rpkid et al. These are the +# production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). +# See ../rcynic/README for relying party tools. +# +# @warning +# rpkid is still in development, and the code changes more often than +# the hand-maintained portions of this documentation. The following +# text was reasonably accurate at the time it was written but may be +# obsolete by the time you read it. +# +# 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 @c rpkid.py: +# The main RPKI engine daemon. +# +# @li @c pubd.py: +# The publication engine daemon. +# +# @li @c rootd.py: +# 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 @c irdbd.py: +# A sample implementation of an IR database daemon. +# rpkid calls into this to perform lookups via the +# left-right protocol. +# +# @li @c irbe-cli.py: +# A command-line client for the left-right control +# protocol. +# +# @li @c irbe-setup.py: +# An example of a script to set up the mappings between +# the IRDB and rpkid's own database, using the +# left-right control protocol. +# +# @li @c cronjob.py: +# A trivial HTTP client used to drive rpkid cron events. +# +# @li @c testbed.py: +# A test tool for running a collection of rpkid and irdb +# instances under common control, driven by a unified +# test script. +# +# @li @c testpoke.py: +# A simple client for the up-down protocol, mostly +# compatable with APNIC's rpki_poke.pl tool. +# +# 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 testbed.py 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, +# starting rpkid, rootd, and irdbd, using the left-right control +# protocol to set up rpkid's internal state, and setting up a cron job +# to invoke rpkid's cron action at regular intervals. 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. +# +# Note that the publication protocol isn't fully specified yet, much +# less implmenented. At the moment rpkid just writes its outputs to a +# local directory tree. +# +# Note that the full event-driven model for rpkid hasn't yet been +# implemented. The design is intended to allow an arbitrary number of +# hosted RPKI engines to run in a single rpkid instance, but without the +# event-driven tasking model one has to set up a separate rpkid instance +# for each hosted RPKI engine. +# +# At present the daemon programs all run in foreground, that is, if one +# wants them to run in background one must do so manually, eg, using +# Bourne shell syntax: +# +# @verbatim +# $ python whatever.py & +# $ echo >whatever.pid "$!" +# @endverbatim +# +# All of the daemons use syslog. At present they all set LOG_PERROR, so +# all logging also goes to stderr. +# +# +# @section rpkid rpkid.py +# +# 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 left-right protocol, followed by dynamic +# configuration via the left-right protocol. In production use the +# latter stage would be handled by the IRBE stub; for test and +# develoment purposes it's handled by the irbe-cli.py command line +# interface or by the testbed.py test framework. +# +# rpkid stores dynamic data in an SQL database, which must have been +# created for it, as explained in the installation guide. +# +# The 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: +# +# @li @c startup-message: +# String to %log on startup, useful when +# debugging a collection of rpkid instances at +# once. +# +# @li @c sql-username: +# Username to hand to MySQL when connecting to +# rpkid's database. +# +# @li @c sql-database: +# MySQL's database name for rpkid's database. +# +# @li @c sql-password: +# Password to hand to MySQL when connecting to +# rpkid's database. +# +# @li @c cms-ta-irdb: +# Name of file containing CMS trust anchor to +# use when authenticating messages from irdbd. +# +# @li @c cms-ta-irbe: +# Name of file containing CMS trust anchor to +# use when authenticating control messages from +# IRBE. +# +# @li @c cms-key: +# Name of file containing RSA key to use when +# signing CMS messages to IRBE or irdbd. +# +# @li @c cms-cert: +# Name(s) of file(s) containing certificate(s) +# to include in CMS wrapper when signing +# messages to IRBE or irdbd. You can specify +# more than one certificate using OpenSSL-style +# subscripts: cms-cert.0, cms-cert.1, etc. +# +# @li @c https-key: +# Name of file containing RSA key to use, both +# in the HTTPS server role (for both up-down and +# left-right protocols) and in the HTTPS client +# role (left-right protocol only). +# +# @li @c https-cert: +# Name(s) of file(s) containing certificate(s) +# to use in same contexts where https-key is +# used. You can specify more than one +# certificate using OpenSSL-style subscripts: +# https-cert.0, https-cert.1, etc. +# +# @li @c https-ta: +# Name of file containing trust anchor to use +# when verifying irdbd's HTTPS server +# certificate. +# +# @li @c irdb-url: +# Service URL for irdbd. Must be a %https:// URL. +# +# @li @c https-server-host: +# Hostname or IP address on which to listen for +# HTTPS connections. Current default is +# INADDR_ANY (IPv4 0.0.0.0); this will need to +# be hacked to support IPv6 for production. +# +# @li @c https-server-port: +# TCP port on which to listen for HTTPS +# connections. +# +# +# @section pubd pubd.py +# +# 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 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. +# +# The 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: +# +# @li @c sql-username: +# Username to hand to MySQL when connecting to +# pubd's database. +# +# @li @c sql-database: +# MySQL's database name for pubd's database. +# +# @li @c sql-password: +# Password to hand to MySQL when connecting to +# pubd's database. +# +# @li @c bpki-ta: +# Name of file containing master BPKI trust +# anchor for pubd. All BPKI validation in pubd +# traces back to this trust anchor. +# +# @li @c irbe-cert: +# Name of file containing BPKI certificate used +# by IRBE when talking to pubd. +# +# @li @c pubd-cert: +# Name of file containing BPKI certificate used +# by pubd. +# +# @li @c pubd-key: +# Name of file containing RSA key corresponding +# to @c pubd-cert. +# +# @li @c server-host: +# Hostname or IP address on which to listen for +# HTTPS connections. Current default is +# INADDR_ANY (IPv4 0.0.0.0); this will need to +# be hacked to support IPv6 for production. +# +# @li @c server-port: +# TCP port on which to listen for HTTPS +# connections. +# +# @li @c publication-base: +# Path to base of filesystem tree where pubd +# should store publishable objects. Default is +# "publication/". +# +# +# @section rootd rootd.py +# +# 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. +# +# The 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: +# +# @li @c cms-ta: +# Name of file containing trust anchor to use +# when verifying CMS up-down queries. +# +# @li @c cms-key: +# Name of file containing RSA key to use when +# signing CMS up-down replies. +# +# @li @c cms-cert: +# Name(s) of file(s) containing certificate(s) +# to include in CMS wrapper when signing up-down +# replies. You can specify more than one +# certificate using OpenSSL-style subscripts: +# cms-cert.0, cms-cert.1, etc. +# +# @li @c https-key: +# Name of file containing RSA key to use in the +# HTTPS server role for the up-down protocol. +# +# @li @c https-cert: +# Name(s) of file(s) containing certificate(s) +# to use in the HTTPS server role for the +# up-down protocol. You can specify more than +# one certificate using OpenSSL-style +# subscripts: https-cert.0, https-cert.1, +# etc. +# +# @li @c https-server-host: +# Hostname or IP address on which to listen for +# HTTPS connections. Default is localhost. +# +# @li @c https-server-port: +# TCP port on which to listen for HTTPS +# connections. +# +# @li @c rpki-key: +# Name of file containing RSA key to use in +# signing resource certificates. +# +# @li @c rpki-issuer: +# Name of file containing self-signed root +# resource certificate corresponding to +# rpki-key. +# +# @li @c rpki-subject-filename: +# Name of file that rootd should use to save the +# one and only certificate it issues. +# +# @li @c rpki-pkcs10-filename: +# 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. +# +# +# @section irdbd irdbd.py +# +# 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 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 IDs (foreign keys into rpkid's database, basicly) in the +# IRDB. The irbe-setup.py program shows an example of how to do this. +# +# 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: +# +# @li @c startup-message: +# String to %log on startup, useful when +# debugging a collection of irdbd instances at +# once. +# +# @li @c sql-username: +# Username to hand to MySQL when connecting to +# irdbd's database. +# +# @li @c sql-database: +# MySQL's database name for irdbd's database. +# +# @li @c sql-password: +# Password to hand to MySQL when connecting to +# irdbd's database. +# +# @li @c cms-ta: +# Name of file containing CMS trust anchor to +# use when authenticating messages from rpkid. +# +# @li @c cms-key: +# Name of file containing RSA key to use when +# signing CMS messages to rpkid. +# +# @li @c cms-cert: +# Name(s) of file(s) containing certificate(s) +# to include in CMS wrapper when signing +# messages to rpkid. You can specify more than +# one certificate using OpenSSL-style +# subscripts: cms-cert.0, cms-cert.1, etc. +# +# @li @c https-key: +# Name of file containing RSA key to use in the +# HTTPS server role when listening for +# connections from rpkid. +# +# @li @c https-cert: +# Name(s) of file(s) containing certificate(s) +# to use in the HTTPS server role when listening +# for connections from rpkid. You can specify +# more than one certificate using OpenSSL-style +# subscripts: https-cert.0, https-cert.1, etc. +# +# @li @c https-url: +# Service URL for irdbd. Must be a %https:// URL. +# +# +# @section irdbd_cli irbe-cli.py +# +# irbe-cli is a simple command line client for the control subset of the +# left-right protocol. In production use this functionality would be +# part of the IRBE stub. +# +# Basic configuration of irbe-cli is handled via a %config file. The +# specific action or actions to be performed are specified on the +# command line, and map closely to the left-right protocol itself. +# +# At present the user is assumed to be able to read the (XML) left-right +# protocol messages, and with one exception, no attempt is made to +# interpret the responses other than to check for errors. The one +# exception is that, if the @c --pem_out option is specified on the command +# line, any PKCS \#10 requests received from rpkid will be written in PEM +# format to that file; this makes it easier to hand these requests off +# to the business PKI in order to issue signing certs corresponding to +# newly generated business keys. +# +# @verbinclude irbe-cli.usage +# +# Global options (@c --config, @c --help, @c --pem_out) come first, then zero or +# more commands (parent, repository, self, child, route_origin, bsc), +# each followed by its own set of options. The commands map to +# elements in the left-right protocol, and the command-specific options +# map to attributes or subelements for those commands. +# +# @c --action is one of @c create, @c set, @c get, @c %list, or @c +# destroy; exactly one of these must be specified for each command. +# +# @c --type is @c query or @c reply; since irbe-cli is a client, +# @c query is the default. +# +# @c --tag is an optional arbitrary tag (think IMAP) to simplify +# matching up replies with batched queries. +# +# @c --*_id options refer to the primary keys of previously created +# objects. +# +# The remaining options are specific to the particular commands, and +# follow directly from the left-right protocol specification. +# +# A trailing "=" in the above option summary indicates that an option +# takes a value, eg, "--action create" or "--action=create". Options +# without a trailing "=" correspond to boolean control attributes. +# +# The default %config file for irbe-cli is irbe.conf, start rpkid with +# "-c filename" (or "--config filename") to choose a different %config +# file. All options are in the section "[irbe-cli]". Certificates, +# keys, and trust anchors may be in either DER or PEM format. +# +# %Config file options: +# +# @li @c cms-ta: +# Name of file containing CMS trust anchor to +# use when authenticating messages from rpkid. +# +# @li @c cms-key: +# Name of file containing RSA key to use when +# signing CMS messages to rpkid. +# +# @li @c cms-cert: +# Name(s) of file(s) containing certificate(s) +# to include in CMS wrapper when signing +# messages to rpkid. You can specify more than +# one certificate using OpenSSL-style +# subscripts: cms-cert.0, cms-cert.1, etc. +# +# @li @c https-key: +# Name of file containing RSA key to use in the +# HTTPS client role when contacting rpkid. +# +# @li @c https-cert: +# Name(s) of file(s) containing certificate(s) +# to use in the HTTPS client role when +# contacting rpkid. You can specify more than +# one certificate using OpenSSL-style +# subscripts: https-cert.0, https-cert.1, +# etc. +# +# @li @c https-ta: +# Name of file containing trust anchor to use +# when verifying rpkid's HTTPS server +# certificate. +# +# @li @c https-url: +# Service URL for rpkid. Must be a %https:// URL. +# +# +# @section irbe_setup irbe-setup.py config file +# +# The default %config file is irbe.conf, start rpkid with "-c filename" +# to choose a different %config file. Most options are in the section +# "[irbe-cli]", but a few are in the section "[irdbd]". Certificates, +# keys, and trust anchors may be in either DER or PEM format. +# +# Options in the "[irbe-cli]" section: +# +# @li @c cms-ta: +# Name of file containing CMS trust anchor to +# use when authenticating messages from rpkid. +# +# @li @c cms-key: +# Name of file containing RSA key to use when +# signing CMS messages to rpkid. +# +# @li @c cms-cert: +# Name(s) of file(s) containing certificate(s) +# to include in CMS wrapper when signing +# messages to rpkid. You can specify more than +# one certificate using OpenSSL-style +# subscripts: cms-cert.0, cms-cert.1, etc. +# +# @li @c https-key: +# Name of file containing RSA key to use in the +# HTTPS client role when contacting rpkid. +# +# @li @c https-cert: +# Name(s) of file(s) containing certificate(s) +# to use in the HTTPS client role when +# contacting rpkid. You can specify more than +# one certificate using OpenSSL-style +# subscripts: https-cert.0, https-cert.1, +# etc. +# +# @li @c https-ta: +# Name of file containing trust anchor to use +# when verifying rpkid's HTTPS server +# certificate. +# +# @li @c https-url: +# Service URL for rpkid. Must be a %https:// URL. +# +# Options in the "[irdbd]" section: +# +# @li @c sql-username: +# Username to hand to MySQL when connecting to +# irdbd's database. +# +# @li @c sql-database: +# MySQL's database name for irdbd's database. +# +# @li @c sql-password: +# Password to hand to MySQL when connecting to +# irdbd's database. +# +# +# @section cronjob cronjob.py +# +# This is a trivial program to trigger a cron run within rpkid. Once +# rpkid has been converted to the planned event-driven model, this +# function will be handled internally, but for now it has to be +# triggered by an external program. For pseudo-production use one would +# run this program under the system cron daemon. For scripted testing +# it happens to be useful to be able to control when cron cycles occur, +# so at the current stage of code development use of an external trigger +# is a useful feature. +# +# The default %config file is cronjob.conf, start cronjob with "-c +# filename" to choose a different %config file. All options are in the +# section "[cronjob]". Certificates, keys, and trust anchors may be in +# either DER or PEM format. +# +# %Config file options: +# +# @li @c https-key: +# Name of file containing RSA key to use in the +# HTTPS client role when contacting rpkid. +# +# @li @c https-cert: +# Name(s) of file(s) containing certificate(s) +# to use in the HTTPS client role when +# contacting rpkid. You can specify more than +# one certificate using OpenSSL-style +# subscripts: https-cert.0, https-cert.1, +# etc. +# +# @li @c https-ta: +# Name of file containing trust anchor to use +# when verifying rpkid's HTTPS server +# certificate. +# +# @li @c https-url: +# Service URL for rpkid. Must be a %https:// URL. +# +# +# @section testbed testbed.py: +# +# testbed is a test harness to set up and run a collection of rpkid and +# irdbd instances under scripted control. testbed is a very recent +# addition to the toolset and is still evolving rapidly. +# +# Unlike the programs described above, testbed 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. testbed 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. +# +# All of the options in in the first (optional) configuration file are +# just overrides for wired-in default values. In most cases the +# defaults will suffice, and the set of options is still in flux, so +# only a few of the options are described here. The default name for +# this configuration file is testbed.conf, run testbed with "-c +# filename" to change it. +# +# testbed.conf options: +# +# @li @c testbed_dir: +# Working directory into which testbed should write the +# (many) files it generates. Default is "testbed.dir". +# +# @li @c irdb_db_pass: +# MySQL password for the "irdb" user. Default is +# "fnord". You may want to override this. +# +# @li @c rpki_db_pass: +# MySQL password for the "rpki" user. Default is +# "fnord". You may want to override this. +# +# @li @c rootd_sia: +# rsync URI naming a (perhaps fictious) directory to use +# as the id-ad-caRepository SIA value in the generated +# root resource certificate. Default is +# "rsync://wombat.invalid/". You may want to override +# this if you intend to run an rsync server and test +# against the generated results using rcynic. This +# default will likely change if and when testbed learns +# how to run rcynic itself as part of the test suite. +# +# The second configuration file is named testbed.yaml by default, run +# testbed 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". The +# details are still evolving, but here's an example of current usage: +# +# @verbatim +# name: RIR +# valid_for: 2d +# sia_base: "rsync://wombat.invalid/" +# kids: +# - name: LIR0 +# kids: +# - name: Alice +# ipv4: 192.0.2.1-192.0.2.33 +# asn: 64533 +# --- +# - name: Alice +# valid_add: 10 +# --- +# - name: Alice +# add_as: 33 +# valid_add: 2d +# --- +# - name: Alice +# valid_sub: 2d +# --- +# - name: Alice +# valid_for: 10d +# @endverbatim +# +# This specifies an initial layout consisting of an RPKI engine named +# "RIR", with one child "LIR0", which in turn has one child "Alice". +# Alice 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 Alice's resources and makes no other +# modifications. The second subsequent document grants Alice additional +# resources and adds another two days to the validity interval for +# Alice's resources. The next document subtracts two days from the +# validity interval for Alice's resources. The final document sets the +# validity interval for Alice's resources to ten days. +# +# Operators in subsequent (update) documents: +# +# @li @c add_as, @c add_v4, @c add_v6: +# These add ASN, IPv4, or IPv6 resources, respectively. +# +# @li @c sub_as, @c sub_v4, @c sub_v6: +# These subtract resources. +# +# @li @c valid_until: +# Set an absolute expiration date. +# +# @li @c valid_for: +# Set a relative expiration date. +# +# @li @c valid_add, @c valid_sub: +# Add to or subtract from validity interval. +# +# @li @c sleep [interval]: +# Sleep for specified interval, or until testbed receives a SIGALRM signal. +# +# 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". +# +# +# @section testpoke testpoke.py +# +# This is a command-line client for the up-down protocol. Unlike all of +# the above programs, testpoke does not accept a %config file in +# OpenSSL-compatable format at all. Instead, it is configured +# exclusively by a YAML script. testpoke's design was constrained by a +# desire to have it be compatable with APNIC's rpki_poke.pl tool, so +# that the two tools could use a common configuration language to +# simplify scripted testing. There are minor variations due to slightly +# different feature sets, but YAML files intended for one program will +# usually work with the other. +# +# README for APNIC's tool describing the input language can be found at +# http://mirin.apnic.net/svn/rpki_engine/branches/gary-poker/client/poke/README +# +# testpoke.py takes a simplified command line and uses only one YAML +# input file. +# +# @verbatim +# Usage: python testpoke.py [ { -y | --yaml } configfile ] +# [ { -r | --request } requestname ] +# [ { -h | --help } ] +# @endverbatim +# +# Default configuration file is testpoke.yaml, override with --yaml +# option. +# +# The --request option specifies the specific command within the YAML +# file to execute. +# +# Sample configuration file: +# +# @verbatim +# --- +# # Sample YAML configuration file for testpoke.py +# +# version: 1 +# posturl: https://localhost:4433/up-down/1 +# recipient-id: wombat +# sender-id: "1" +# +# cms-cert-file: biz-certs/Frank-EE.cer +# cms-key-file: biz-certs/Frank-EE.key +# cms-ca-cert-file: biz-certs/Bob-Root.cer +# cms-cert-chain-file: [ biz-certs/Frank-CA.cer ] +# +# ssl-cert-file: biz-certs/Frank-EE.cer +# ssl-key-file: biz-certs/Frank-EE.key +# ssl-ca-cert-file: biz-certs/Bob-Root.cer +# +# requests: +# list: +# type: list +# issue: +# type: issue +# class: 1 +# sia: [ "rsync://bandicoot.invalid/some/where/" ] +# revoke: +# type: revoke +# class: 1 +# ski: "CB5K6APY-4KcGAW9jaK_cVPXKX0" +# @endverbatim +# +# testpoke adds one extension to the language described in APNIC's +# README: the cms-cert-chain-* and ssl-cert-chain-* options, which allow +# one to specify a chain of intermediate certificates to be presented in +# the CMS or TLS protocol. APNIC's initial implementation required +# direct knowledge of the issuing certificate (ie, it supported a +# maximum chain length of one); subsequent APNIC code changes have +# probably relaxed this restriction, and with luck APNIC has copied +# testpoke's syntax to express chains of intermediate certificates. ## @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 Terminology -## -## @li @em IRBE: Internet Registry Back End -## -## @li @em IRDB: Internet Registry Data Base -## -## @li @em BPKI: Business PKI -## -## @li @em RPKI: Resource PKI -## -## @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 HTTPS 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_id" 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_id attribute, which must be specified -## for the "set", "get", and "destroy" actions. -## -## Payload data which can be configured in a @c <self/> %object: -## -## @li @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. -## -## @li @c crl_interval (attribute): -## Positive integer representing the planned lifetime of an RPKI CRL -## for this @c <self/>, measured in seconds. -## -## @li @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. -## -## @li @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. -## -## @li @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: -## -## @li @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. -## -## @li @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. -## -## @li @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. -## -## @li @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. -## -## @li @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 or HTTPS 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_id, which must be specified for the -## "get", "set", and "destroy" actions. Every @c <bsc/> also has a self_id -## 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: -## -## @li @c signing_cert (element): -## BPKI certificate to use when generating a signature. -## -## @li @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: -## -## @li @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": -## -## @li @c key_type: -## Type of BPKI keypair to generate. "rsa" is both the default and, -## at the moment, the only allowed value. -## -## @li @c hash_alg: -## Cryptographic hash algorithm to use with this keypair. "sha256" -## is both the default and, at the moment, the only allowed value. -## -## @li @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_id, which must be specified for -## the "get", "set", and "destroy" actions. Every @c <parent/> also has a -## self_id attribute which indicates the @c <self/> %object with which this -## @c <parent/> %object is associated, a bsc_id attribute indicating the @c <bsc/> -## %object to be used when signing messages sent to this parent, and a -## repository_id 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: -## -## @li @c peer_contact_uri (attribute): -## HTTPS URI used to contact this parent. -## -## @li @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. -## -## @li @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. -## -## @li @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. -## -## @li @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. -## -## @li @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. -## -## @li @c bpki_https_cert (element): -## BPKI HTTPS CA certificate for this @c <parent/>. This is like the -## bpki_cms_cert %object, only used for validating incoming TLS -## messages rather than CMS. -## -## @li @c bpki_cms_glue (element): -## Another BPKI HTTPS CA certificate for this @c <parent/>, usually not -## needed. This is like the bpki_cms_glue certificate, only used for -## validating incoming TLS messages rather than CMS. -## -## Control attributes that can be set to "yes" to force actions: -## -## @li @c rekey: -## This is like the rekey command in the @c <self/> %object, but limited -## to RPKI CAs under this parent. -## -## @li @c reissue: -## This is like the reissue command in the @c <self/> %object, but limited -## to RPKI CAs under this parent. -## -## @li @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 parent_id, which must be specified for the -## "get", "set", and "destroy" actions. Every @c <child/> also has a -## self_id 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: -## -## @li @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. -## -## @li @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: -## -## @li @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_id, which must be -## specified for the "get", "set", and "destroy" actions. Every -## @c <repository/> also has a self_id 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: -## -## @li @c peer_contact_uri (attribute): -## HTTPS URI used to contact this repository. -## -## @li @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. -## -## @li @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. -## -## @li @c bpki_https_cert (element): -## BPKI HTTPS CA certificate for this @c <repository/>. This is like the -## bpki_cms_cert %object, only used for validating incoming TLS -## messages rather than CMS. -## -## @li @c bpki_cms_glue (element): -## Another BPKI HTTPS CA certificate for this @c <repository/>, usually not -## needed. This is like the bpki_cms_glue certificate, only used for -## validating incoming TLS messages rather than CMS. -## -## At present there are no control attributes for @c <repository/> %objects. -## -## @subsection route_origin_obj <route_origin/> object -## -## 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: -## -## @li @c as_number (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. -## -## @li @c ipv4 (attribute): -## %List of IPv4 prefix and maxLength values, see below for format. -## -## @li @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: -## -## @li @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 and HTTPS 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_id" attribute naming -## the @c <self/> that is making the request and also a @c "child_id" -## 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_id, and @c child_id copied -## from the request: -## -## @li @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. -## -## @li @c subject_name: -## An optional text string naming the child. Not currently used. -## -## @li @c asn: -## A %list of autonomous sequence numbers, expressed as a -## comma-separated sequence of decimal integers with no whitespace. -## -## @li @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. -## -## @li @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 HTTPS -## 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_id" 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. - +# +# 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 Terminology +# +# @li @em IRBE: Internet Registry Back End +# +# @li @em IRDB: Internet Registry Data Base +# +# @li @em BPKI: Business PKI +# +# @li @em RPKI: Resource PKI +# +# @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 HTTPS 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_id" 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_id attribute, which must be specified +# for the "set", "get", and "destroy" actions. +# +# Payload data which can be configured in a @c <self/> %object: +# +# @li @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. +# +# @li @c crl_interval (attribute): +# Positive integer representing the planned lifetime of an RPKI CRL +# for this @c <self/>, measured in seconds. +# +# @li @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. +# +# @li @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. +# +# @li @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: +# +# @li @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. +# +# @li @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. +# +# @li @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. +# +# @li @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. +# +# @li @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 or HTTPS 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_id, which must be specified for the +# "get", "set", and "destroy" actions. Every @c <bsc/> also has a self_id +# 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: +# +# @li @c signing_cert (element): +# BPKI certificate to use when generating a signature. +# +# @li @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: +# +# @li @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": +# +# @li @c key_type: +# Type of BPKI keypair to generate. "rsa" is both the default and, +# at the moment, the only allowed value. +# +# @li @c hash_alg: +# Cryptographic hash algorithm to use with this keypair. "sha256" +# is both the default and, at the moment, the only allowed value. +# +# @li @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_id, which must be specified for +# the "get", "set", and "destroy" actions. Every @c <parent/> also has a +# self_id attribute which indicates the @c <self/> %object with which this +# @c <parent/> %object is associated, a bsc_id attribute indicating the @c <bsc/> +# %object to be used when signing messages sent to this parent, and a +# repository_id 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: +# +# @li @c peer_contact_uri (attribute): +# HTTPS URI used to contact this parent. +# +# @li @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. +# +# @li @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. +# +# @li @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. +# +# @li @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. +# +# @li @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. +# +# @li @c bpki_https_cert (element): +# BPKI HTTPS CA certificate for this @c <parent/>. This is like the +# bpki_cms_cert %object, only used for validating incoming TLS +# messages rather than CMS. +# +# @li @c bpki_cms_glue (element): +# Another BPKI HTTPS CA certificate for this @c <parent/>, usually not +# needed. This is like the bpki_cms_glue certificate, only used for +# validating incoming TLS messages rather than CMS. +# +# Control attributes that can be set to "yes" to force actions: +# +# @li @c rekey: +# This is like the rekey command in the @c <self/> %object, but limited +# to RPKI CAs under this parent. +# +# @li @c reissue: +# This is like the reissue command in the @c <self/> %object, but limited +# to RPKI CAs under this parent. +# +# @li @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 parent_id, which must be specified for the +# "get", "set", and "destroy" actions. Every @c <child/> also has a +# self_id 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: +# +# @li @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. +# +# @li @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: +# +# @li @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_id, which must be +# specified for the "get", "set", and "destroy" actions. Every +# @c <repository/> also has a self_id 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: +# +# @li @c peer_contact_uri (attribute): +# HTTPS URI used to contact this repository. +# +# @li @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. +# +# @li @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. +# +# @li @c bpki_https_cert (element): +# BPKI HTTPS CA certificate for this @c <repository/>. This is like the +# bpki_cms_cert %object, only used for validating incoming TLS +# messages rather than CMS. +# +# @li @c bpki_cms_glue (element): +# Another BPKI HTTPS CA certificate for this @c <repository/>, usually not +# needed. This is like the bpki_cms_glue certificate, only used for +# validating incoming TLS messages rather than CMS. +# +# At present there are no control attributes for @c <repository/> %objects. +# +# @subsection route_origin_obj <route_origin/> object +# +# 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: +# +# @li @c as_number (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. +# +# @li @c ipv4 (attribute): +# %List of IPv4 prefix and maxLength values, see below for format. +# +# @li @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: +# +# @li @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 and HTTPS 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_id" attribute naming +# the @c <self/> that is making the request and also a @c "child_id" +# 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_id, and @c child_id copied +# from the request: +# +# @li @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. +# +# @li @c subject_name: +# An optional text string naming the child. Not currently used. +# +# @li @c asn: +# A %list of autonomous sequence numbers, expressed as a +# comma-separated sequence of decimal integers with no whitespace. +# +# @li @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. +# +# @li @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 HTTPS +# 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_id" 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 the IRBE to use to configure the %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 @link Left-right left-right protocol: @endlink like the -## left-right protocol, the %publication protocol uses CMS-wrapped XML -## over HTTPS with the same eContentType OID and the same HTTPS -## 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 HTTPS server which serves -## both of these subprotocols. The two subprotocols share a single -## server port, but use distinct URLs. -## -## @section Terminology -## -## @li @em IRBE: Internet Registry Back End -## -## @li @em IRDB: Internet Registry Data Base -## -## @li @em BPKI: Business PKI -## -## @li @em RPKI: Resource PKI -## -## @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: -## -## @li @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. Fortunately, 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_id" -## attribute, which is used in responses and must be specified in "set", -## "get", or "destroy" actions. -## -## Payload data which can be configured in a <client/> %object: -## -## @li @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. -## -## @li @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. -## -## @li @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 HTTPS -## 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 on either the "forward" (IRBE -## as client of RPKI engine) or "back" (RPKI engine as client of IRDB) -## communication channel. -## -## The <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_id" attribute indicating the -## <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 <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. - +# +# The %publication protocol is really two separate client/server +# protocols, between different parties. The first is a configuration +# protocol for the IRBE to use to configure the %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 @link Left-right left-right protocol: @endlink like the +# left-right protocol, the %publication protocol uses CMS-wrapped XML +# over HTTPS with the same eContentType OID and the same HTTPS +# 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 HTTPS server which serves +# both of these subprotocols. The two subprotocols share a single +# server port, but use distinct URLs. +# +# @section Terminology +# +# @li @em IRBE: Internet Registry Back End +# +# @li @em IRDB: Internet Registry Data Base +# +# @li @em BPKI: Business PKI +# +# @li @em RPKI: Resource PKI +# +# @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: +# +# @li @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. Fortunately, 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_id" +# attribute, which is used in responses and must be specified in "set", +# "get", or "destroy" actions. +# +# Payload data which can be configured in a <client/> %object: +# +# @li @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. +# +# @li @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. +# +# @li @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 HTTPS +# 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 on either the "forward" (IRBE +# as client of RPKI engine) or "back" (RPKI engine as client of IRDB) +# communication channel. +# +# The <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_id" attribute indicating the +# <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 <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. |