RPKI Engine 1.0

__doc__.py (3902)

Go to the documentation of this file.
00001 ## @file
00002 # @details
00003 # Documentation sourc, expressed as Python comments to make Doxygen happy.
00004 #
00005 # $Id: __doc__.py 3902 2011-06-27 18:31:02Z sra $
00006 #
00007 # Copyright (C) 2009--2010  Internet Systems Consortium ("ISC")
00008 #
00009 # Permission to use, copy, modify, and distribute this software for any
00010 # purpose with or without fee is hereby granted, provided that the above
00011 # copyright notice and this permission notice appear in all copies.
00012 #
00013 # THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00014 # REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00015 # AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00016 # INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00017 # LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00018 # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00019 # PERFORMANCE OF THIS SOFTWARE.
00020 #
00021 # Portions copyright (C) 2007--2008  American Registry for Internet Numbers ("ARIN")
00022 #
00023 # Permission to use, copy, modify, and distribute this software for any
00024 # purpose with or without fee is hereby granted, provided that the above
00025 # copyright notice and this permission notice appear in all copies.
00026 #
00027 # THE SOFTWARE IS PROVIDED "AS IS" AND ARIN DISCLAIMS ALL WARRANTIES WITH
00028 # REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00029 # AND FITNESS.  IN NO EVENT SHALL ARIN BE LIABLE FOR ANY SPECIAL, DIRECT,
00030 # INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00031 # LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00032 # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00033 # PERFORMANCE OF THIS SOFTWARE.
00034 
00035 ## @mainpage RPKI Engine Reference Manual
00036 #
00037 # This collection of Python modules implements a prototype of the
00038 # RPKI Engine.  This is a work in progress.
00039 #
00040 # See http://subvert-rpki.hactrn.net/ for code and
00041 # design documents.
00042 #
00043 # The RPKI Engine is an implementation of the production-side tools
00044 # for generating certificates, CRLs, and ROAs.  The
00045 # <a href="http://subvert-rpki.hactrn.net/rcynic/">relying party tools</a>
00046 # are a separate (and much simpler) package.
00047 #
00048 # The Subversion repository for the entire project is available for
00049 # (read-only) anonymous access at http://subvert-rpki.hactrn.net/.
00050 #
00051 # The documentation you're reading is generated automatically by
00052 # Doxygen from comments and documentation in
00053 # <a href="http://subvert-rpki.hactrn.net/rpkid/rpki/">the code</a>.
00054 #
00055 # Besides the automatically-generated code documentation, this manual
00056 # also includes documentation of the overall package:
00057 #
00058 # @li @subpage Overview "Overview of the tools"
00059 #
00060 # @li @subpage Installation "Installation instructions"
00061 #
00062 # @li @subpage Configuration "Configuration instructions"
00063 #
00064 # @li @subpage MySQL-Setup "MySQL setup instructions"
00065 #
00066 # @li The @subpage myrpki "myrpki tool"
00067 #
00068 # @li A description of the @subpage Left-Right "left-right protocol"
00069 #
00070 # @li A description of the @subpage Publication "publication protocol"
00071 #
00072 # @li A description of the @subpage bpki-model "BPKI model"
00073 #     used to secure the up-down, left-right, and %publication protocols
00074 #
00075 # @li A description of the several @subpage sql-schemas "SQL database schemas"
00076 #
00077 # This work was funded from 2006 through 2008 by <a
00078 # href="http://www.arin.net/">ARIN</a>, in collaboration with the
00079 # other Regional Internet Registries.  Current work is funded by DHS.
00080 
00081 ## @page Overview Overview
00082 #
00083 # @section Terminology Terminology
00084 #
00085 # A few special terms that appear often enough in code or
00086 # documentation that they need explaining.
00087 #
00088 # @todo
00089 # These explanations should be fleshed out properly.
00090 #
00091 # @par IRBE:
00092 #       Internet Registry Back End.
00093 #
00094 # @par IRDB:
00095 #       Internet Registry Data Base.
00096 #
00097 # @par BPKI:
00098 #       Business PKI.
00099 #
00100 # @par RPKI:
00101 #       Resource PKI.
00102 #
00103 #
00104 # @section Programs Programs
00105 #
00106 # At present the package is intended to be run out of the @c rpkid/
00107 # directory.
00108 #
00109 # In addition to the library routines in the @c rpkid/rpki/ directory,
00110 # the package includes the following programs:
00111 #
00112 # @li @ref rpkid "@c rpkid":
00113 #              The main RPKI engine daemon.
00114 #
00115 # @li @ref pubd "@c pubd":
00116 #              The publication engine daemon.
00117 #
00118 # @li @ref rootd "@c rootd"
00119 #              A separate daemon for handling the root of an RPKI
00120 #              certificate tree.  This is essentially a stripped down
00121 #              version of rpkid with no SQL database, no left-right
00122 #              protocol implementation, and only the parent side of
00123 #              the up-down protocol.  It's separate because the root
00124 #              is a special case in several ways and it was simpler
00125 #              to keep the special cases out of the main daemon.
00126 #
00127 # @li @ref irdbd "@c irdbd":
00128 #              A sample implementation of an IR database daemon.
00129 #              rpkid calls into this to perform lookups via the
00130 #              left-right protocol.
00131 #
00132 # @li @ref smoketest "@c smoketest":
00133 #              A test tool for running a collection of rpkid and irdb
00134 #              instances under common control, driven by a unified
00135 #              test script.
00136 #
00137 # @li @ref yamltest "@c yamltest":
00138 #              Another test tool which takes the same input format as
00139 #              @c smoketest.py, but with slightly different purpose.
00140 #              @c smoketest.py is intended to support regression tests,
00141 #              while @c yamltest.py is intended for automated testing
00142 #              of something closer to a real operational environment.
00143 #              There's a fair amount of code duplication between the
00144 #              two, and at some point they will probably be merged
00145 #              into a single program that supports both modes of
00146 #              operation.
00147 #
00148 # Most of these programs take configuration files in a common format
00149 # similar to that used by the OpenSSL command line tool.  The test
00150 # programs also take input in YAML format to drive the tests.  Runs of
00151 # the @c yamltest test tool will generate a fairly complete set
00152 # configuration files which may be useful as examples.
00153 #
00154 # Basic operation consists of creating the appropriate MySQL databases
00155 # (see @ref MySQL-Setup "MySQL Setup"), configuring relationships
00156 # between parents and children and between publication clients and
00157 # repositories (see @ref MyRPKI "The myrpki tool"), starting @c rpkid,
00158 # @c pubd, @c rootd, and @c irdbd, and using the left-right and
00159 # publication control protocols (see @ref MyRPKI "The myrpki tool") to
00160 # set up rpkid's and pubd's internal state.  All other operations
00161 # should occur either as a result of cron events or as a result of
00162 # incoming left-right and up-down protocol requests.
00163 #
00164 # The core programs are all event-driven, and are (in theory) capable
00165 # of supporting an arbitrary number of hosted RPKI engines to run in a
00166 # single rpkid instance, up to the performance limits of the underlying
00167 # hardware.
00168 #
00169 # At present the daemon programs all run in foreground, that is, the
00170 # daemons themselves make no attempt to put themselves in background.
00171 # The easiest way to run the servers is to run the @c start_servers
00172 # script, which examines your @c rpki.conf file and starts the
00173 # appropriate servers in background using @c rpki.conf as the
00174 # configuration file for each server as well.
00175 #
00176 # If you prefer, you can run each server by hand instead of using the
00177 # script, eg, using Bourne shell syntax to run rpkid in background:
00178 #
00179 # @verbatim
00180 #   $ rpkid &
00181 #   $ echo >rpkid.pid  "$!"
00182 # @endverbatim
00183 #
00184 # All of the daemons use syslog by default.  You can change this by
00185 # running either the servers themselves or the @c start_servers script
00186 # with the "-d" option.  Used as an argument to a server directly,
00187 # "-d" causes that server to log to @c stderr instead of to syslog.
00188 # Used as an argument to @c start_servers, "-d" starts each of the
00189 # servers with "-d" while redirecting @c stderr from each server to a
00190 # separate log file.  This is intended primarily for debugging.
00191 #
00192 # Some of the options that the several daemons take are common to all
00193 # daemons.  Which daemon they affect depends only on which sections of
00194 # which config files they are in.  See
00195 # @ref CommonOptions "Common Options"
00196 # for details.
00197 #
00198 # @subsection rpkid rpkid
00199 #
00200 # rpkid is the main RPKI engine daemon.  Configuration of rpkid is a
00201 # two step process: a %config file to bootstrap rpkid to the point
00202 # where it can speak using the @ref Left-Right "left-right protocol",
00203 # followed by dynamic configuration via the left-right protocol.  The
00204 # latter stage is handled by the @c myrpki tool.
00205 #
00206 # rpkid stores dynamic data in an SQL database, which must have been
00207 # created for it, as explained in the
00208 # @ref Installation "Installation Guide".
00209 #
00210 #
00211 # @subsection pubd pubd
00212 #
00213 # pubd is the publication daemon.  It implements the server side of
00214 # the publication protocol, and is used by rpkid to publish the
00215 # certificates and other objects that rpkid generates.
00216 #
00217 # pubd is separate from rpkid for two reasons:
00218 #
00219 # @li The hosting model allows entities which choose to run their own
00220 #     copies of rpkid to publish their output under a common
00221 #     publication point.  In general, encouraging shared publication
00222 #     services where practical is a good thing for relying parties,
00223 #     as it will speed up rcynic synchronization time.
00224 #
00225 # @li The publication server has to run on (or at least close to) the
00226 #     publication point itself, which in turn must be on a publically
00227 #     reachable server to be useful.  rpkid, on the other hand, need
00228 #     only be reachable by the IRBE and its children in the RPKI tree.
00229 #     rpkid is a much more complex piece of software than pubd, so in
00230 #     some situations it might make sense to wrap tighter firewall
00231 #     constraints around rpkid than would be practical if rpkid and
00232 #     pubd were a single program.
00233 #
00234 # pubd stores dynamic data in an SQL database, which must have been
00235 # created for it, as explained in the
00236 # @ref Installation "Installation Guide".  pubd also
00237 # stores the published objects themselves as disk files in a
00238 # configurable location which should correspond to an appropriate
00239 # module definition in rsync.conf; see the
00240 # @ref Configuration "Configuration Guide"
00241 # for details.
00242 #
00243 #
00244 # @subsection rootd rootd
00245 #
00246 # rootd is a stripped down implmenetation of (only) the server side of
00247 # the up-down protocol.  It's a separate program because the root
00248 # certificate of an RPKI certificate tree requires special handling
00249 # and may also require a special handling policy.  rootd is a simple
00250 # implementation intended for test use, it's not suitable for use in a
00251 # production system.  All configuration comes via the %config file;
00252 # see the
00253 # @ref Configuration "Configuration Guide"
00254 # for details.
00255 #
00256 #
00257 # @subsection irdbd irdbd
00258 #
00259 # irdbd is a sample implemntation of the server side of the IRDB
00260 # callback subset of the left-right protocol.  In production use this
00261 # service is a function of the IRBE stub; irdbd may be suitable for
00262 # production use in simple cases, but an IR with a complex IRDB may need
00263 # to extend or rewrite irdbd.
00264 #
00265 # irdbd requires a pre-populated database to represent the IR's
00266 # customers.  irdbd expects this database to use
00267 # @ref irdbd-sql "the SQL schema defined in rpkid/irdbd.sql".
00268 # Once this database has been populated, the IRBE stub needs to create
00269 # the appropriate objects in rpkid's database via the control subset
00270 # of the left-right protocol, and store the linkage handles (foreign
00271 # keys into rpkid's database) in the IRDB.  See the
00272 # @ref Installation "Installation Guide"
00273 # and the
00274 # @ref MySQL-Setup "MySQL setup instructions"
00275 # for details.
00276 #
00277 #
00278 # @subsection smoketest smoketest
00279 #
00280 # smoketest is a test harness to set up and run a collection of rpkid and
00281 # irdbd instances under scripted control.
00282 #
00283 # Unlike the programs described above, smoketest takes two configuration
00284 # files in different languages.  The first configuration file uses the
00285 # same syntax as the above configuration files but is completely
00286 # optional.  The second configuration file is the test script, which is
00287 # encoded using the YAML serialization language (see
00288 # http://www.yaml.org/ for more information on YAML).  The YAML script
00289 # is not optional, as it describes the test layout.  smoketest is designed
00290 # to support running a fairly wide set of test configurations as canned
00291 # scripts without writing any new control code.  The intent is to make
00292 # it possible to write meaningful regression tests.
00293 #
00294 # See @ref smoketestconf "smoketest.conf" for what can go into the
00295 # (optional) first configuration file.
00296 #
00297 # See @ref smoketestyaml "smoketest.yaml" for what goes into the
00298 # (required) second configuration file.
00299 #
00300 #
00301 # @subsection yamltest yamltest
00302 #
00303 # yamltest is another test harness to set up and run a collection of
00304 # rpkid and irdbd instances under scripted control.  It is similar in
00305 # many ways to @ref smoketest "@c smoketest", and in fact uses the
00306 # same YAML test description language, but its purpose is different:
00307 # @c smoketest runs a particular test scenario through a series of
00308 # changes, then shuts it down; @c yamltest, on the other hand, sets up
00309 # a test network using the same tools that a real user would
00310 # (principally the @c myrpki tool), and leaves the test running
00311 # indefinitely.
00312 #
00313 # @c yamltest grew out of @c smoketest and the two probably should be
00314 # merged back into a single tool which supports both kinds of testing.
00315 #
00316 #
00317 # @section further-reading Further Reading
00318 #
00319 # If you're interested in this package you might also be interested
00320 # in:
00321 #
00322 # @li <a href="http://subvert-rpki.hactrn.net/rcynic/">The rcynic validation tool</a>
00323 #
00324 # @li <a href="http://www.hactrn.net/opaque/rcynic.html">A live sample of rcynic's summary output</a>
00325 #
00326 #
00327 # @section getting-started Getting Started
00328 #
00329 # The first step to bringing up rpkid and friends is installing the code,
00330 # which is described in the @ref Installation "Installation Guide".
00331 
00332 ## @page Installation Installation Guide
00333 #
00334 # Installation instructions for rpkid et al.  These are the
00335 # production-side RPKI tools, for Internet Registries (RIRs, LIRs,
00336 # etc).  See the "rcynic" program for relying party tools.
00337 #
00338 # rpkid is a set of Python modules supporting generation and maintenance
00339 # of resource certificates.  Most of the code is in the rpkid/rpki/
00340 # directory.  rpkid itself is a relatively small program that calls the
00341 # library modules.  There are several other programs that make use of
00342 # the same libraries, as well as a collection of test programs.
00343 #
00344 # At present the package is intended to be run out of its build
00345 # directory.  Setting up proper installation in a system area using the
00346 # Python distutils package would likely not be very hard but has not yet
00347 # been done.
00348 #
00349 # Note that initial development of this code has been on FreeBSD, so
00350 # installation will probably be easiest on FreeBSD.
00351 #
00352 # Before attempting to build the package, you need to install any
00353 # missing prerequisites.  Note that the Python code requires Python
00354 # version 2.5 or 2.6.  rpkid et al are mostly self-contained, but do
00355 # require a small number of external packages to run.
00356 #
00357 # <ul>
00358 #   <li>
00359 #     If your Python installation does not already include the sources
00360 #     files needed to compile new Python extension modules, you will
00361 #     need to install whatever package does include those source
00362 #     files.  The need for and name of this package varies from system
00363 #     to system.  On FreeBSD, the base Python interpreter package
00364 #     includes the development sources; on at least some Linux
00365 #     distributions, you have to install a separate "python-devel"
00366 #     package or something similar.  If you get compilation errors
00367 #     trying to build the POW code (below) and the error message says
00368 #     something about the file "Python.h" being missing, this is
00369 #     almost certainly your problem.
00370 #   </li>
00371 #
00372 #   <li>
00373 #     <a href="http://codespeak.net/lxml/">http://codespeak.net/lxml/</a>,
00374 #     a Pythonic interface to the Gnome LibXML2 libraries.  
00375 #     lxml in turn requires the LibXML2 C libraries.
00376 #     <ul>
00377 #       <li>FreeBSD: /usr/ports/devel/py-lxml</li>
00378 #       <li>Fedora:  python-lxml.i386</li>
00379 #       <li>Ubuntu:  python-lxml</li>
00380 #     </ul>
00381 #   </li>
00382 #
00383 #   <li>
00384 #     <a href="http://sourceforge.net/projects/mysql-python/">http://sourceforge.net/projects/mysql-python/</a>,
00385 #     the Python "db" interface to MySQL.  MySQLdb in turn requires MySQL client and server.  rpkid et al have
00386 #     been tested with MySQL 5.0 and 5.1.
00387 #     <ul>
00388 #       <li>FreeBSD: /usr/ports/databases/py-MySQLdb</li>
00389 #       <li>Fedora:  MySQL-python.i386</li>
00390 #       <li>Ubuntu:  python-mysqldb</li>
00391 #     </ul>
00392 #   </li>
00393 # </ul>
00394 #
00395 # rpkid et al also make heavy use of a modified copy of the Python
00396 # OpenSSL Wrappers (POW) package, but this copy has enough modifications
00397 # and additions that it's included in the subversion tree.
00398 #
00399 # The next step is to build the OpenSSL and POW binaries.  At present
00400 # the OpenSSL code is just a snapshot of the OpenSSL development
00401 # sources, compiled with special options to enable RFC 3779 support
00402 # that ISC wrote under previous contract to ARIN.  The POW (Python
00403 # OpenSSL Wrapper) library is an extended copy of the stock POW
00404 # release.
00405 #
00406 # To build these, cd to the top-level directory in the distribution,
00407 # run the configure script, then run "make":
00408 #
00409 # @verbatim
00410 #   $ cd $top
00411 #   $ ./configure
00412 #   $ make
00413 # @endverbatim
00414 #
00415 # This should automatically build everything, in the right order,
00416 # including linking the POW extension module with the OpenSSL library
00417 # to provide RFC 3779 support.  If you get errors building POW, see
00418 # the above discussion of Python development sources.
00419 #
00420 # The architecture is intended to support hardware signing modules
00421 # (HSMs), but the code to support them has not been written.
00422 #
00423 # At this point, you should have all the necessary software installed
00424 # to run the core programs, but you will probably want to test it.
00425 # The test suite requires a few more external packages, only one of
00426 # which is Python code.
00427 #
00428 # <ul>
00429 #   <li>
00430 #     <a href="http://pyyaml.org/">http://pyyaml.org/</a>.
00431 #     Several of the test programs use PyYAML to parse a YAML
00432 #     description of a simulated allocation hierarchy to test.
00433 #     <ul>
00434 #       <li>FreeBSD: /usr/ports/devel/py-yaml</li>
00435 #       <li>Ubuntu: python-yaml</li>
00436 #     </ul>
00437 #   </li>
00438 #
00439 #   <li>
00440 #     <a href="http://xmlsoft.org/XSLT/">http://xmlsoft.org/XSLT/</a>.
00441 #     Some of the test code uses xsltproc, from the Gnome LibXSLT
00442 #     package.
00443 #     <ul>
00444 #       <li>FreeBSD: /usr/ports/textproc/libxslt</li>
00445 #       <li>Ubuntu:  xsltproc</li>
00446 #     </ul>
00447 #   </li>
00448 # </ul>
00449 #
00450 # All tests should be run from the rpkid/ directories.  
00451 #
00452 # Some of the tests require MySQL databases to store their data.  To
00453 # set up all the databases that the tests will need, run the SQL
00454 # commands in rpkid/tests/smoketest.setup.sql.  The MySQL command line
00455 # client is usually the easiest way to do this, eg:
00456 #
00457 # @verbatim
00458 #   $ cd $top/rpkid
00459 #   $ mysql -u root -p <tests/smoketest.setup.sql
00460 # @endverbatim
00461 #
00462 # To run the tests, run "make all-tests":
00463 #
00464 # @verbatim
00465 #   $ cd $top/rpkid
00466 #   $ make all-tests
00467 # @endverbatim
00468 #
00469 # If nothing explodes, your installation is probably ok.  Any Python
00470 # backtraces in the output indicate a problem.
00471 #
00472 # There's a last set of tools that only developers should need, as
00473 # they're only used when modifying schemas or regenerating the
00474 # documentation.  These tools are listed here for completeness.
00475 #
00476 # <ul>
00477 #   <li>
00478 #     <a href="http://www.doxygen.org/">http://www.doxygen.org/</a>.
00479 #     Doxygen in turn pulls in several other tools, notably Graphviz,
00480 #     pdfLaTeX, and Ghostscript.
00481 #     <ul>
00482 #       <li>FreeBSD: /usr/ports/devel/doxygen</li>
00483 #       <li>Ubuntu: doxygen</li>
00484 #     </ul>
00485 #   </li>
00486 #
00487 #   <li>
00488 #     <a href="http://www.mbayer.de/html2text/">http://www.mbayer.de/html2text/</a>.
00489 #     The documentation build process uses xsltproc and html2text to dump
00490 #     flat text versions of a few critical documentation pages.
00491 #     <ul>
00492 #       <li>FreeBSD: /usr/ports/textproc/html2text</li>
00493 #     </ul>
00494 #   </li>
00495 #
00496 #   <li>
00497 #     <a href="http://www.thaiopensource.com/relaxng/trang.html">http://www.thaiopensource.com/relaxng/trang.html</a>.
00498 #     Trang is used to convert RelaxNG schemas from the human-readable
00499 #     "compact" form to the XML form that LibXML2 understands.  Trang in
00500 #     turn requires Java.
00501 #     <ul>
00502 #       <li>FreeBSD: /usr/ports/textproc/trang</li>
00503 #     </ul>
00504 #   </li>
00505 #
00506 #   <li>
00507 #     <a href="http://search.cpan.org/dist/SQL-Translator/">http://search.cpan.org/dist/SQL-Translator/</a>.
00508 #     SQL-Translator, also known as "SQL Fairy", includes code to parse
00509 #     an SQL schema and dump a description of it as Graphviz input.
00510 #     SQL Fairy in turn requires Perl.
00511 #     <ul>
00512 #       <li>FreeBSD: /usr/ports/databases/p5-SQL-Translator</li>
00513 #     </ul>
00514 #   </li>
00515 # </ul>
00516 #
00517 # Once you've finished with installation, the next thing you should
00518 # read is the @ref Configuration "Configuration Guide".
00519 
00520 ## @page Configuration Configuration Guide
00521 #
00522 # This section describes the configuration file syntax and settings.
00523 #
00524 # Each of the programs that make up the RPKI tookit can potentially
00525 # take its own configuration file, but for most uses this is
00526 # unnecessarily complicated.  The recommended approach is to use a
00527 # single configuration file, and to put all of the parameters that a
00528 # normal user might need to change into a single section of that
00529 # configuration file, then reference these common settings from the
00530 # program-specific sections of the configuration file via macro
00531 # expansion.  The configuration file parser supports a limited version
00532 # of the macro facility used in OpenSSL's configuration parser.  An
00533 # expression such as @verbatim foo = ${bar::baz} @endverbatim sets foo
00534 # to the value of the @c baz variable from section @c bar.  The section
00535 # name @c ENV is special: it refers to environment variables.
00536 #
00537 # @section rpkiconf rpki.conf
00538 #
00539 # The default name for the shared configuration file is @c rpki.conf.
00540 # Unless you really know what you're doing, you should start by
00541 # copying the @c rpki.conf from the @c rpkid/examples directory and
00542 # modifying it, as the sample configuration file already includes all
00543 # the additional settings necessary to use the simplified configuration.
00544 #
00545 # @dontinclude rpki.conf
00546 # @skipline [myrpki]
00547 #
00548 # The @c [myrpki] section of @c rpki.conf contains all the
00549 # parameters that you really need to configure.
00550 #
00551 # @skip #
00552 # @until =
00553 #
00554 # Every resource-holding or server-operating entity needs a "handle",
00555 # which is just an identifier by which the entity calls itself.
00556 # Handles do not need to be globally unique, but should be chosen with
00557 # an eye towards debugging operational problems: it's best if you use
00558 # a handle that your parents and children will recognize as being you.
00559 #
00560 # @skip #
00561 # @until bpki/servers
00562 #
00563 # The myrpki tool requires filenames for several input data files, the
00564 # "business PKI" databases used to secure CMS and TLS communications,
00565 # and the XML intermediate format that it uses.  Rather than
00566 # hardwiring the names into the code, they're configured here.  You
00567 # can change the names if you must, but the defaults should be fine in
00568 # most cases.
00569 #
00570 # @skip #
00571 # @until irdbd_server_port
00572 #
00573 # If you're hosting RPKI service for others, or are self-hosting, you
00574 # want this on.  If somebody else is running rpkid on your behalf and
00575 # you're just shipping them your @c myrpki.xml file, you can turn this
00576 # off.
00577 #
00578 # If you're running @c rpkid at all, you'll need to set at least the
00579 # @c rpkid_server_host parameter here.  You may be able to use the
00580 # default port numbers, or may need to pick different ones.  Unless
00581 # you plan to run @c irdbd on a different machine from @c rpkid, you
00582 # should leave @c irdbd_server_host alone.
00583 #
00584 # @skip #
00585 # @until pubd_contact_info
00586 #
00587 # The myrpki tool will attempt to negotiate publication service for
00588 # you with whatever publication service your parent is using, if you
00589 # let it, so in most cases you should not need to run @c pubd unless
00590 # you need to issue certificates for private IP address space or
00591 # private Autononmous System Numbers.
00592 #
00593 # If you do run @c pubd, you will need to set @c pubd_server_host.
00594 # You may also need to set @c pubd_server_port, and you should provide
00595 # something helpful as contact information in @c pubd_contact_info if
00596 # you plan to offer publication service to your RPKI children, so that
00597 # grandchildren (or descendents even further down the tree) who
00598 # receive referrals to your service will know how to contact you.
00599 #
00600 # @skip #
00601 # @until rootd_server_port
00602 #
00603 # You shouldn't run rootd unless you're the root of an RPKI tree.  Who
00604 # gets to be the root of the public RPKI tree is a political issue
00605 # outside the scope of this document.  For everybody else, the only
00606 # reason for running @c rootd (other than test purposes) would be to
00607 # support certification of private IP addresses and ASNs.  The core
00608 # tools can do this without any problem, but the simplified
00609 # configuration mechanism does not (yet) make this easy to do.
00610 #
00611 # @skip #
00612 # @until publication_rsync_server
00613 #
00614 # These parameters control the mapping between the rsync URIs
00615 # presented by @c rsyncd and the local filesystem on the machine where
00616 # @c pubd and @c rsyncd run.  Any changes here must also be reflected
00617 # as changes in @c rsyncd.conf.  In most cases you should not change
00618 # the value of @c publication_rsync_module from the default; since
00619 # pubd can't (and should not) rewrite @c rsyncd.conf, it's best to use
00620 # a static rsync module name here and let @c pubd do its work
00621 # underneath that name.  In most cases @c publication_rsync_server
00622 # should be the same as @c publication_rsync_server, which is what the
00623 # macro invocation in the default setting does.  @c
00624 # publication_base_directory, like other pathnames in @c rpki.conf,
00625 # can be either a relative or absolute pathname; if relative, it's
00626 # interpreted with respect to the directory in which the programs in
00627 # question were started.  In this specific case, it's probably better
00628 # to use an absolute pathname, since this pathname must also appear in
00629 # @c rsyncd.conf.
00630 #
00631 # @skip #
00632 # @until pubd_sql_password
00633 #
00634 # These settings control how @c rpkid, @c irdbd, and @c pubd talk to
00635 # the MySQL server.  At minimum, each daemon needs its own database;
00636 # in the simplest configuration, the username and password can be
00637 # shared, which is what the macro references in the default
00638 # configuration does.  If for some reason you need to set different
00639 # usernames and passwords for different daemons, you can do so by
00640 # changing the daemon-specific variables.
00641 #
00642 # @skip #
00643 # @until = openssl
00644 #
00645 # The @c myrpki tool uses the @c openssl command line tool for most of
00646 # its BPKI operations, for two reasons:
00647 #
00648 # @li To avoid duplicating CA-management functionality already
00649 # provided by the command line tool, and
00650 #
00651 # @li To ease portability of the @c myrpki tool, so that a "hosted"
00652 # resource holder can use it without needing to install entire toolkit.
00653 #
00654 # The @c myrpki tool's use of OpenSSL does not require exotic features
00655 # like RFC 3779 support, but it does require a version of the tool
00656 # recent enough to support CMS and the @c -ss_cert argument to the @c
00657 # ca command.  Depending on the platform on which you are running this
00658 # code, you may or may not have a system copy of the @c openssl tool
00659 # installed that meets these criteria; if not, the @c openssl binary
00660 # built when you compile the toolkit will suffice.  This parameter
00661 # allows you to tell @c myrpki where to find the binary, if necessary;
00662 # the default just uses the system search path.
00663 #
00664 # @section otherconf Other configuration files and options
00665 #
00666 # In most cases the simplified configuration in the @c [myrpki]
00667 # section of @c rpki.conf should suffice, but in case you need to
00668 # tinker, here are details on the the rest of the configuration
00669 # options.  In most cases the default name of the configuration file
00670 # for a program is the name of the program followed by @c ".conf", and
00671 # the section name is also named for the program, so that you can
00672 # combine sections into a single configuration file as shown with @c
00673 # rpki.conf.
00674 #
00675 # @li @subpage CommonOptions "Common configuration options"
00676 #
00677 # @li @subpage rpkidconf "rpkid configuration"
00678 #
00679 # @li @subpage irdbdconf "irdbd configuration"
00680 #
00681 # @li @subpage pubdconf  "pubd configuration"
00682 #
00683 # @li @subpage rootdconf "rootd configuration"
00684 #
00685 # @li @subpage smoketestconf "configuration of the smoketest test harness"
00686 #
00687 # @li @subpage smoketestyaml "test description language for the smoketest test harness"
00688 #
00689 # Once you've finished with configuration, the next thing you should
00690 # read is the @ref MySQL-Setup "MySQL setup instructions".
00691  
00692 ## @page MySQL-Setup MySQL Setup
00693 #
00694 # You need to install MySQL and set up the relevant databases before
00695 # starting @c rpkid, @c irdbd, or @c pubd.
00696 #
00697 # See the @ref Installation "Installation Guide" for details on where
00698 # to download MySQL and find documentation on installing it.
00699 #
00700 # See the @ref Configuration "Configuration Guide" for details on the
00701 # configuration file settings the daemons will use to find and
00702 # authenticate themselves to their respective databases.
00703 #
00704 # Before you can (usefully) start any of the daemons, you will need to
00705 # set up the MySQL databases they use.  You can do this by hand, or
00706 # you can use the @c rpki-sql-setup script, which prompts you for your
00707 # MySQL root password then attempts to do everything else
00708 # automatically using values from rpki.conf.
00709 #
00710 # Using the script is simple:
00711 #
00712 # @verbatim
00713 # $ rpki-sql-setup.py
00714 # Please enter your MySQL root password:
00715 # @endverbatim
00716 #
00717 # The script should tell you what databases it creates.  You can use
00718 # the -v option if you want to see more details about what it's doing.
00719 #
00720 # If you'd prefer to do the SQL setup manually, perhaps because you
00721 # have valuable data in other MySQL databases and you don't want to
00722 # trust some random setup script with your MySQL root password, you'll
00723 # need to use the MySQL command line tool, as follows:
00724 #
00725 # @verbatim
00726 # $ mysql -u root -p
00727 # 
00728 # mysql> CREATE DATABASE irdb_database;
00729 # mysql> GRANT all ON irdb_database.* TO irdb_user@localhost IDENTIFIED BY 'irdb_password';
00730 # mysql> USE irdb_database;
00731 # mysql> SOURCE $top/rpkid/irdbd.sql;
00732 # mysql> CREATE DATABASE rpki_database;
00733 # mysql> GRANT all ON rpki_database.* TO rpki_user@localhost IDENTIFIED BY 'rpki_password';
00734 # mysql> USE rpki_database;
00735 # mysql> SOURCE $top/rpkid/rpkid.sql;
00736 # mysql> COMMIT;
00737 # mysql> quit
00738 # @endverbatim
00739 #
00740 # where @c irdb_database, @c irdb_user, @c irdb_password, @c
00741 # rpki_database, @c rpki_user, and @c rpki_password match the values
00742 # you used in your configuration file.
00743 #
00744 # If you are running pubd and are doing manual SQL setup, you'll also
00745 # have to do:
00746 #
00747 # @verbatim
00748 # $ mysql -u root -p
00749 # mysql> CREATE DATABASE pubd_database;
00750 # mysql> GRANT all ON pubd_database.* TO pubd_user@localhost IDENTIFIED BY 'pubd_password';
00751 # mysql> USE pubd_database;
00752 # mysql> SOURCE $top/rpkid/pubd.sql;
00753 # mysql> COMMIT;
00754 # mysql> quit
00755 # @endverbatim
00756 #
00757 # where @c pubd_database, @c pubd_user @c pubd_password match the
00758 # values you used in your configuration file.
00759 #
00760 # Once you've finished configuring MySQL, the next thing you should
00761 # read is the instructions for the @ref MyRPKI "myrpki tool".
00762 
00763 
00764 ## @page MyRPKI The myrpki tool
00765 #
00766 # The design of rpkid and friends assumes that certain tasks can be
00767 # thrown over the wall to the registry's back end operation.  This was
00768 # a deliberate design decision to allow rpkid et al to remain
00769 # independent of existing database schema, business PKIs, and so forth
00770 # that a registry might already have.  All very nice, but it leaves
00771 # someone who just wants to test the tools or who has no existing back
00772 # end with a fairly large programming project.  The @c myrpki tool
00773 # attempts to fill that gap.
00774 # 
00775 # @c myrpki is a basic implementation of what a registry back end
00776 # would need to use rpkid and friends.  @c myrpki does not use every
00777 # available option in the other programs, nor is it necessarily as
00778 # efficient as possible.  Large registries will almost certainly want
00779 # to roll their own tools, perhaps using these as a starting point.
00780 # Nevertheless, we hope that @c myrpki will at least provide a useful
00781 # example, and may be adaquate for simple use.
00782 # 
00783 # @c myrpki is (currently) implemented as a single command line Python
00784 # program.  It has a number of commands, most of which are used for
00785 # initial setup, some of which are used on an ongoing basis.  @c
00786 # myrpki can be run either in an interactive mode or by passing a
00787 # single command on the command line when starting the program; the
00788 # former mode is intended to be somewhat human-friendly, the latter
00789 # mode is useful in scripting, cron jobs, and automated testing.
00790 # 
00791 # @c myrpki use has two distinct phases: setup and data maintenance.
00792 # The setup phase is primarily about constructing the "business PKI"
00793 # (BPKI) certificates that the daemons use to authenticate CMS
00794 # messages and obtaining the service URLs needed to configure
00795 # the daemons.  The data maintenance phase is about configuring local
00796 # data into the daemons.
00797 # 
00798 # @c myrpki uses the OpenSSL command line tool for almost all
00799 # operations on keys and certificates; the one exception to this is
00800 # the comamnd which talks directly to the daemons, as this command
00801 # uses the same communication libraries as the daemons themselves do.
00802 # The intent behind using the OpenSSL command line tool for everything
00803 # else is to allow all the other commands to be run without requiring
00804 # all the auxiliary packages upon which the daemons depend; this can
00805 # be useful, eg, if one wants to run the back-end on a laptop while
00806 # running the daemons on a server, in which case one might prefer not
00807 # to have to install a bunch of unnecessary packages on the laptop.
00808 # 
00809 # During setup phase @c myrpki generates and processes small XML
00810 # messages which it expects the user to ship to and from its parents,
00811 # children, etc via some out-of-band means (email, perhaps with PGP
00812 # signatures, USB stick, we really don't care).  During data
00813 # maintenance phase, @c myrpki does something similar with another XML
00814 # file, to allow hosting of RPKI services; in the degenerate case
00815 # where an entity is just self-hosting (ie, is running the daemons for
00816 # itself, and only for itself), this latter XML file need not be sent
00817 # anywhere.
00818 # 
00819 # The basic idea here is that a user who has resources maintains a set
00820 # of .csv files containing a text representation of the data needed by
00821 # the back-end, along with a configuration file containing other
00822 # parameters.  The intent is that these be very simple files that are
00823 # easy to generate either by hand or as a dump from relational
00824 # database, spreadsheet, awk script, whatever works in your
00825 # environment.  Given these files, the user then runs @c myrpki to
00826 # extract the relevant information and encode everything about its
00827 # back end state into an XML file, which can then be shipped to the
00828 # appropriate other party.
00829 # 
00830 # Many of the @c myrpki commands which process XML input write out a
00831 # new XML file, either in place or as an entirely new file; in
00832 # general, these files need to be sent back to the party that sent the
00833 # original file.  Think of all this as a very slow packet-based
00834 # communication channel, where each XML file is a single packet.  In
00835 # setup phase, there's generally a single round-trip per setup
00836 # conversation; in the data maintenance phase, the same XML file keeps
00837 # bouncing back and forth between hosted entity and hosting entity.
00838 # 
00839 # Note that, as certificates and CRLs have expiration and nextUpdate
00840 # values, a low-level cycle of updates passing between resource holder
00841 # and rpkid operator will be necessary as a part of steady state
00842 # operation.  [The current version of these tools does not yet
00843 # regenerate these expiring objects, but fixing this will be a
00844 # relatively minor matter.]
00845 # 
00846 # The third important kind of file in this system is the
00847 # @ref Configuration "configuration file"
00848 # for @c myrpki.  This contains a number of sections, some of which
00849 # are for myrpki, others of which are for the OpenSSL command line
00850 # tool, still others of which are for the various RPKI daemon
00851 # programs.  The examples/ subdirectory contains a commented version
00852 # of the configuration file that explains the various parameters.
00853 # 
00854 # The .csv files read by myrpki are (now) misnamed: formerly, they
00855 # used the "excel-tab" format from the Python csv library, but early
00856 # users kept trying to make the colums line up, which didn't do what
00857 # the users expected.  So now these files are just
00858 # whitespace-delimted, such as a program like "awk" would understand.
00859 # 
00860 # Keep reading, and don't panic.
00861 # 
00862 # The default configuration file name for @c myrpki is
00863 # @ref Configuration "@c rpki.conf".
00864 # You can change this using the "-c" option when invoking myrpki, or
00865 # by setting the environment variable MYRPKI_CONF.
00866 # 
00867 # See examples/*.csv for commented examples of the several CSV files.
00868 # Note that the comments themselves are not legal CSV, they're just
00869 # present to make it easier to understand the examples.
00870 # 
00871 # @section myrpkioverview  myrpki overview
00872 # 
00873 # Which process you need to follow depends on whether you are running
00874 # rpkid yourself or will be hosted by somebody else.  We call the first
00875 # case "self-hosted", because the software treats running rpkid to
00876 # handle resources that you yourself hold as if you are an rpkid
00877 # operator who is hosting an entity that happens to be yourself.
00878 # 
00879 # "$top" in the following refers to wherever you put the
00880 # subvert-rpki.hactrn.net code.  Once we have autoconf and "make
00881 # install" targets, this will be some system directory or another; for
00882 # now, it's wherever you checked out a copy of the code from the
00883 # subversion repository or unpacked a tarball of the code.
00884 # 
00885 # Most of the setup process looks the same for any resource holder,
00886 # regardless of whether they are self-hosting or not.  The differences
00887 # come in the data maintenence phase.
00888 # 
00889 # The steps needed during setup phase are:
00890 # 
00891 # @li Write a configuration file (copy $top/rpkid/examples/rpki.conf
00892 #     and edit as needed).  You need to configure the @c [myrpki] section;
00893 #     in theory, the rest of the file should be ok as it is, at least for
00894 #     simple use.  You also need to create (either by hand or by dumping
00895 #     from a database, spreadsheet, whatever) the CSV files describing
00896 #     prefixes and ASNs you want to allocate to your children and ROAs
00897 #     you want created.
00898 # 
00899 # @li Initialization ("initialize" command).  This creates the local BPKI
00900 #     and other data structures that can be constructed just based on
00901 #     local data such as the config file.  Other than some internal data
00902 #     structures, the main output of this step is the "identity.xml" file,
00903 #     which is used as input to later stages.
00904 # 
00905 #     In theory it should be safe to run the "initialize" command more
00906 #     than once, in practice this has not (yet) been tested.
00907 # 
00908 # @li Send (email, USB stick, carrier pigeon) identity.xml to each of your
00909 #     parents.  This tells each of your parents what you call yourself,
00910 #     and supplies each parent with a trust anchor for your
00911 #     resource-holding BPKI.
00912 # 
00913 # @li Each of your parents runs the "configure_child" command, giving
00914 #     the identity.xml you supplied as input.  This registers your
00915 #     data with the parent, including BPKI cross-registration, and
00916 #     generates a return message containing your parent's BPKI trust
00917 #     anchors, a service URL for contacting your parent via the
00918 #     "up-down" protocol, and (usually) either an offer of publication
00919 #     service (if your parent operates a repository) or a referral
00920 #     from your parent to whatever publication service your parent
00921 #     does use.  Referrals include a CMS-signed authorization token
00922 #     that the repository operator can use to determine that your
00923 #     parent has given you permission to home underneath your parent
00924 #     in the publication tree.
00925 # 
00926 # @li Each of your parents sends (...) back the response XML file
00927 #     generated by the "configure_child" command.
00928 # 
00929 # @li You feed the response message you just got into myrpki using the
00930 #     "configure_parent" command.  This registers the parent's
00931 #     information in your database, including BPKI
00932 #     cross-certification, and processes the repository offer or
00933 #     referral to generate a publication request message.
00934 # 
00935 # @li You send (...) the publication request message to the
00936 #     repository.  The @c contact_info element in the request message
00937 #     should (in theory) provide some clue as to where you should send
00938 #     this.
00939 # 
00940 # @li The repository operator processes your request using myrpki's
00941 #     "configure_publication_client" command.  This registers your
00942 #     information, including BPKI cross-certification, and generates a
00943 #     response message containing the repository's BPKI trust anchor
00944 #     and service URL.
00945 # 
00946 # @li Repository operator sends (...) the publication confirmation message
00947 #     back to you.
00948 # 
00949 # @li You process the publication confirmation message using myrpki's
00950 #     "configure_repository" command.
00951 # 
00952 # At this point you should, in theory, have established relationships,
00953 # exchanged trust anchors, and obtained service URLs from all of your
00954 # parents and repositories.  The last setup step is establishing a
00955 # relationship with your RPKI service host, if you're not self-hosted,
00956 # but as this is really just the first message of an ongoing exchange
00957 # with your host, it's handled by the data maintenance commands.
00958 # 
00959 # The two commands used in data maintenence phase are
00960 # "configure_resources" and "configure_daemons".  The first is used by
00961 # the resource holder, the second is used by the host.  In the
00962 # self-hosted case, it is not necessary to run "configure_resources" at
00963 # all, myrpki will run it for you automatically.
00964 # 
00965 # @section myrpkihosted Hosted case
00966 # 
00967 # The basic steps involved in getting started for a resource holder who
00968 # is being hosted by somebody else are:
00969 # 
00970 # @li Run through steps listed in
00971 #     @ref myrpkioverview "the myrpki overview section".
00972 # 
00973 # @li Run the configure_resources command to generate myrpki.xml.
00974 # 
00975 # @li Send myrpki.xml to the rpkid operator who will be hosting you.
00976 # 
00977 # @li Wait for your rpkid operator to ship you back an updated XML
00978 #     file containing a PKCS #10 certificate request for the BPKI
00979 #     signing context (BSC) created by rpkid.
00980 # 
00981 # @li Run configure_resources again with the XML file you just
00982 #     received, to issue the BSC certificate and update the XML file
00983 #     again to contain the newly issued BSC certificate.
00984 # 
00985 # @li Send the updated XML file back to your rpkid operator.
00986 # 
00987 # At this point you're done with initial setup.  You will need to run
00988 # configure_resources again whenever you make any changes to your
00989 # configuration file or CSV files.
00990 #
00991 # @warning Once myrpki knows how to update
00992 # BPKI CRLs, you will also need to run configure_resources periodically
00993 # to keep your BPKI CRLs up to date.
00994 #
00995 # Any time you run configure_resources myrpki, you should send the
00996 # updated XML file to your rpkid operator, who should send you a
00997 # further updated XML file in response.
00998 # 
00999 # @section myrpkiselfhosted Self-hosted case
01000 # 
01001 # The first few steps involved in getting started for a self-hosted
01002 # resource holder (that is, a resource holder that runs its own copy
01003 # of rpkid) are the same as in the @ref myrpkihosted "hosted case"
01004 # above; after that the process diverges.
01005 # 
01006 # The [current] steps are:
01007 # 
01008 # @li Follow the basic installation instructions in
01009 #     @ref Installation "the Installation Guide" to build the
01010 #     RFC-3779-aware OpenSSL code and associated Python extension
01011 #     module.
01012 # 
01013 # @li Run through steps listed in
01014 #     @ref myrpkioverview "the myrpki overview section".
01015 # 
01016 # @li Set up the MySQL databases that rpkid et al will use.  The
01017 #     package includes a tool to do this for you, you can use that or
01018 #     do the job by hand.  See
01019 #     @ref MySQL-Setup "MySQL database setup"
01020 #     for details.
01021 # 
01022 # @li If you are running your own publication repository (that is, if
01023 #     you are running pubd), you will also need to set up an rsyncd
01024 #     server or configure your existing one to serve pubd's output.
01025 #     There's a sample configuration file in
01026 #     $top/rpkid/examples/rsyncd.conf, but you may need to do
01027 #     something more complicated if you are already running rsyncd for
01028 #     other purposes.  See the rsync(1) and rsyncd.conf(5) manual
01029 #     pages for more details.
01030 # 
01031 # @li Start the daemons.  You can use $top/rpkid/rpki-start-servers.py to
01032 #     do this, or write your own script.  If you intend to run pubd,
01033 #     you should make sure that the directory you specified as
01034 #     publication_base_directory exists and is writable by the userid
01035 #     that will be running pubd, and should also make sure to start
01036 #     rsyncd.
01037 # 
01038 # @li Run myrpki's configure_daemons command, twice, with no
01039 #     arguments.  You need to run the command twice because myrpki has
01040 #     to ask rpkid to create a keypair and generate a certification
01041 #     request for the BSC.  The first pass does this, the second
01042 #     processes the certification request, issues the BSC, and loads
01043 #     the result into rpkid.  [Yes, we could automate this somehow, if
01044 #     necessary.]
01045 # 
01046 # At this point, if everything went well, rpkid should be up,
01047 # configured, and starting to obtain resource certificates from its
01048 # parents, generate CRLs and manifests, and so forth.  At this point you
01049 # should go figure out how to use the relying party tool, rcynic: see
01050 # $top/rcynic/README if you haven't already done so.
01051 # 
01052 # If and when you change your CSV files, you should run
01053 # configure_daemons again to feed the changes into the daemons.
01054 # 
01055 # @section myrpkihosting Hosting case
01056 # 
01057 # If you are running rpkid not just for your own resources but also to
01058 # host other resource holders (see @ref myrpkihosted "hosted case"
01059 # above), your setup will be almost the same as in the self-hosted
01060 # case (see @ref myrpkiselfhosted "self-hosted case", above), with one
01061 # procedural change: you will need to tell @c configure_daemons to
01062 # process the XML files produced by the resource holders you are
01063 # hosting.  You do this by specifying the names of all those XML files
01064 # on as arguments to the @c configure_daemons command.  So, if you are
01065 # hosting two friends, Alice and Bob, then, everywhere the
01066 # instructions for the self-hosted case say to run @c
01067 # configure_daemons with no arguments, you will instead run it with
01068 # the names of Alice's and Bob's XML files as arguments.
01069 # 
01070 # Note that @c configure_daemons sometimes modifies these XML files,
01071 # in which case it will write them back to the same filenames.  While
01072 # it is possible to figure out the set of circumstances in which this
01073 # will happen (at present, only when @c myrpki has to ask @c rpkid to
01074 # create a new BSC keypair and PKCS #10 certificate request), it may
01075 # be easiest just to ship back an updated copy of the XML file after
01076 # every you run @c configure_daemons.
01077 # 
01078 # @section myrpkipurehosting "Pure" hosting case
01079 # 
01080 # In general we assume that anybody who bothers to run @c rpkid is
01081 # also a resource holder, but the software does not insist on this.
01082 # 
01083 # @todo
01084 # Er, well, rpkid doesn't, but myrpki now does -- "pure" hosting was an
01085 # unused feature that fell by the wayside while simplifying the user
01086 # interface.  It would be relatively straightforward to add it back if
01087 # we ever need it for anything, but the mechanism it used to use no
01088 # longer exists -- the old [myirbe] section of the config file has been
01089 # collapsed into the [myrpki] section, so testing for existance of the
01090 # [myrpki] section no longer works.  So we'll need an explicit
01091 # configuration option, no big deal, just not worth chasing now.
01092 # 
01093 # A (perhaps) plausible use for this capability would be if you are an
01094 # rpkid-running resource holder who wants for some reason to keep the
01095 # resource-holding side of your operation completely separate from the
01096 # rpkid-running side of your operation.  This is essentially the
01097 # pure-hosting model, just with an internal hosted entity within a
01098 # different part of your own organization.
01099 # 
01100 # @section myrpkitroubleshooting Troubleshooting
01101 # 
01102 # If you run into trouble setting up this package, the first thing to do
01103 # is categorize the kind of trouble you are having.  If you've gotten
01104 # far enough to be running the daemons, check their log files.  If
01105 # you're seeing Python exceptions, read the error messages.  If you're
01106 # getting TLS errors, check to make sure that you're using all the right
01107 # BPKI certificates and service contact URLs.
01108 # 
01109 # TLS configuration errors are, unfortunately, notoriously difficult to
01110 # debug, because connection failures due to misconfiguration happen
01111 # early, deep in the guts of the OpenSSL TLS code, where there isn't
01112 # enough application context available to provide useful error messages.
01113 # 
01114 # If you've completed the steps above, everything appears to have gone
01115 # OK, but nothing seems to be happening, the first thing to do is
01116 # check the logs to confirm that nothing is actively broken.  @c
01117 # rpkid's log should include messages telling you when it starts and
01118 # finishes its internal "cron" cycle.  It can take several cron cycles
01119 # for resources to work their way down from your parent into a full
01120 # set of certificates and ROAs, so have a little patience.  @c rpkid's
01121 # log should also include messages showing every time it contacts its
01122 # parent(s) or attempts to publish anything.
01123 # 
01124 # @c rcynic in fully verbose mode provides a fairly detailed
01125 # explanation of what it's doing and why objects that fail have
01126 # failed.
01127 # 
01128 # You can use @c rsync (sic) to examine the contents of a publication
01129 # repository one directory at a time, without attempting validation,
01130 # by running rsync with just the URI of the directory on its command
01131 # line:
01132 #
01133 # @verbatim
01134 #   $ rsync rsync://rpki.example.org/where/ever/
01135 # @endverbatim
01136 # 
01137 # @section myrpkiknownissues Known Issues
01138 # 
01139 # The lxml package provides a Python interface to the Gnome libxml2
01140 # and libxslt C libraries.  This code has been quite stable for
01141 # several years, but initial testing with lxml compiled and linked
01142 # against a newer version of libxml2 ran into problems (specifically,
01143 # gratuitous RelaxNG schema validation failures).  libxml2 2.7.3
01144 # worked; libxml2 2.7.5 did not work on the test machine in question.
01145 # Reverting to libxml2 2.7.3 fixed the problem.  Rewriting the two
01146 # lines of Python code that were triggering the lxml bug appears to
01147 # have solved the problem, so the code now works properly with libxml
01148 # 2.7.5, but if you start seeing weird XML validation failures, it
01149 # might be another variation of this lxml bug.
01150 # 
01151 # An earlier version of this code ran into problems with what appears
01152 # to be an implementation restriction in the the GNU linker ("ld") on
01153 # 64-bit hardware, resulting in obscure build failures.  The
01154 # workaround for this required use of shared libraries and is somewhat
01155 # less portable than the original code, but without it the code simply
01156 # would not build in 64-bit environments with the GNU tools.  The
01157 # current workaround appears to behave properly, but the workaround
01158 # requires that the pathname to the RFC-3779-aware OpenSSL shared
01159 # libraries be built into the _POW.so Python extension module.  If
01160 # necessary, you can override this by setting the LD_LIBRARY_PATH
01161 # environment variable, see the ld.so man page for details.  This is a
01162 # relatively minor variation on the usual build issues for shared
01163 # libraries, it's just annoying because shared libraries should not be
01164 # needed here and would not be if not for this GNU linker issue.
01165 
01166 ## @page CommonOptions Common Configuration Options
01167 #
01168 # Some of the options that the several daemons take are common to all
01169 # daemons.  Which daemon they affect depends only on which sections of
01170 # which config files they are in.
01171 #
01172 # The first group of options are debugging flags, which can be set to
01173 # "true" or "false".  If not specified, default values will be chosen
01174 # (generally false).
01175 #
01176 # @par @c debug_http:
01177 #                               Enable verbose http debug logging.
01178 #
01179 # @par @c debug_tls_certs:
01180 #                               Enable verbose logging about tls certs.
01181 #
01182 # @par @c want_persistent_client:
01183 #                               Enable http 1.1 persistence, client side.
01184 #
01185 # @par @c want_persistent_server:
01186 #                               Enable http 1.1 persistence, server side.
01187 #
01188 # @par @c debug_cms_certs:
01189 #                               Enable verbose logging about cms certs.
01190 #
01191 # @par @c sql_debug:
01192 #                               Enable verbose logging about sql operations.
01193 #
01194 # @par @c gc_debug:
01195 #                               Enable scary garbage collector debugging.
01196 #
01197 # @par @c timer_debug:
01198 #                               Enable verbose logging of timer system.
01199 #
01200 # There are also a few options that allow you to save CMS messages for
01201 # audit or debugging.  The save format is a simple MIME encoding in a
01202 # Maildir-format mailbox.  The current options are very crude, at some
01203 # point we may provide finer grain controls.
01204 #
01205 # @par @c dump_outbound_cms:
01206 #                               Dump messages we send to this mailbox.
01207 #
01208 # @par @c dump_inbound_cms:
01209 #                               Dump messages we receive to this mailbox.
01210 
01211 ## @page rpkidconf rpkid.conf
01212 #
01213 # rpkid's default %config file is rpkid.conf, start rpkid with "-c
01214 # filename" to choose a different %config file.  All options are in
01215 # the section "[rpkid]".  Certificates, keys, and trust anchors may be
01216 # in either DER or PEM format.
01217 #
01218 # %Config file options:
01219 #
01220 # @par @c startup-message:
01221 #                      String to %log on startup, useful when
01222 #                      debugging a collection of rpkid instances at
01223 #                      once.
01224 #
01225 # @par @c sql-username:
01226 #                      Username to hand to MySQL when connecting to
01227 #                      rpkid's database.
01228 #
01229 # @par @c sql-database:
01230 #                      MySQL's database name for rpkid's database.
01231 #
01232 # @par @c sql-password:
01233 #                      Password to hand to MySQL when connecting to
01234 #                      rpkid's database.
01235 #
01236 # @par @c bpki-ta:
01237 #                      Name of file containing BPKI trust anchor.
01238 #                      All BPKI certificate verification within rpkid
01239 #                      traces back to this trust anchor. 
01240 #
01241 # @par @c rpkid-cert:
01242 #                      Name of file containing rpkid's own BPKI EE
01243 #                      certificate.
01244 #
01245 # @par @c rpkid-key:
01246 #                      Name of file containing RSA key corresponding
01247 #                      to rpkid-cert.
01248 #
01249 # @par @c irbe-cert:
01250 #                      Name of file containing BPKI certificate used
01251 #                      by IRBE when talking to rpkid.
01252 #
01253 # @par @c irdb-cert:
01254 #                      Name of file containing BPKI certificate used
01255 #                      by irdbd.
01256 #
01257 # @par @c irdb-url:
01258 #                      Service URL for irdbd.  Must be a %http:// URL.
01259 #
01260 # @par @c server-host:
01261 #                      Hostname or IP address on which to listen for
01262 #                      HTTP connections.  Current default is
01263 #                      INADDR_ANY (IPv4 0.0.0.0); this will need to
01264 #                      be hacked to support IPv6 for production.
01265 #
01266 # @par @c server-port:
01267 #                      TCP port on which to listen for HTTP
01268 #                      connections.
01269 
01270 ## @page pubdconf pubd.conf
01271 #
01272 # pubd's default %config file is pubd.conf, start pubd with "-c
01273 # filename" to choose a different %config file.  All options are in
01274 # the section "[pubd]".  Certifiates, keys, and trust anchors may be
01275 # either DER or PEM format.
01276 #
01277 # %Config file options:
01278 #
01279 # @par @c sql-username:
01280 #                      Username to hand to MySQL when connecting to
01281 #                      pubd's database.
01282 #
01283 # @par @c sql-database:
01284 #                      MySQL's database name for pubd's database.
01285 #
01286 # @par @c sql-password:
01287 #                      Password to hand to MySQL when connecting to
01288 #                      pubd's database.
01289 #
01290 # @par @c bpki-ta:
01291 #                      Name of file containing master BPKI trust
01292 #                      anchor for  pubd.  All BPKI validation in pubd
01293 #                      traces back to this trust anchor.
01294 #
01295 # @par @c irbe-cert:
01296 #                      Name of file containing BPKI certificate used
01297 #                      by IRBE when talking to pubd.
01298 #
01299 # @par @c pubd-cert:
01300 #                      Name of file containing BPKI certificate used
01301 #                      by pubd.
01302 #
01303 # @par @c pubd-key:
01304 #                      Name of file containing RSA key corresponding
01305 #                      to @c pubd-cert.
01306 #
01307 # @par @c server-host:
01308 #                      Hostname or IP address on which to listen for
01309 #                      HTTP connections.  Current default is
01310 #                      INADDR_ANY (IPv4 0.0.0.0); this will need to
01311 #                      be hacked to support IPv6 for production.
01312 #
01313 # @par @c server-port:
01314 #                      TCP port on which to listen for HTTP
01315 #                      connections.
01316 #
01317 # @par @c publication-base:
01318 #                      Path to base of filesystem tree where pubd
01319 #                      should store publishable objects.  Default is
01320 #                      "publication/".
01321 
01322 ## @page rootdconf rootd.conf
01323 #
01324 # rootd's default %config file is rootd.conf, start rootd with "-c
01325 # filename" to choose a different %config file.  All options are in
01326 # the section "[rootd]".  Certificates, keys, and trust anchors may be
01327 # in either DER or PEM format.
01328 #
01329 # %Config file options:
01330 #
01331 # @par @c bpki-ta:
01332 #                      Name of file containing BPKI trust anchor.  All
01333 #                      BPKI certificate validation in rootd traces
01334 #                      back to this trust anchor.
01335 #
01336 # @par @c rootd-bpki-cert:
01337 #                      Name of file containing rootd's own BPKI
01338 #                      certificate. 
01339 #
01340 # @par @c rootd-bpki-key:
01341 #                      Name of file containing RSA key corresponding to
01342 #                      rootd-bpki-cert.
01343 #
01344 # @par @c rootd-bpki-crl:
01345 #                      Name of file containing BPKI CRL that would
01346 #                      cover rootd-bpki-cert had it been revoked.
01347 #
01348 # @par @c child-bpki-cert:
01349 #                      Name of file containing BPKI certificate for 
01350 #                      rootd's one and only child (RPKI engine to
01351 #                      which rootd issues an RPKI certificate).
01352 #
01353 # @par @c server-host:
01354 #                      Hostname or IP address on which to listen for
01355 #                      HTTP connections.  Default is localhost.
01356 #
01357 # @par @c server-port:
01358 #                      TCP port on which to listen for HTTP
01359 #                      connections.
01360 #
01361 # @par @c rpki-root-key:
01362 #                      Name of file containing RSA key to use in
01363 #                      signing resource certificates.
01364 #
01365 # @par @c rpki-root-cert:
01366 #                      Name of file containing self-signed root
01367 #                      resource certificate corresponding to
01368 #                      rpki-root-key.
01369 #
01370 # @par @c rpki-root-dir:
01371 #                      Name of directory where rootd should write
01372 #                      RPKI subject certificate, manifest, and CRL.
01373 #
01374 # @par @c rpki-subject-cert:
01375 #                      Name of file that rootd should use to save the
01376 #                      one and only certificate it issues.
01377 #                      Default is "Subroot.cer".
01378 #
01379 # @par @c rpki-root-crl:
01380 #                      Name of file to which rootd should save its
01381 #                      RPKI CRL.  Default is "Root.crl".
01382 #
01383 # @par @c rpki-root-manifest:
01384 #                      Name of file to which rootd should save its
01385 #                      RPKI manifest.  Default is "Root.mnf".
01386 #
01387 # @par @c rpki-subject-pkcs10:
01388 #                      Name of file that rootd should use when saving
01389 #                      a copy of the received PKCS #10 request for a
01390 #                      resource certificate.  This is only used for
01391 #                      debugging.  Default is not to save the PKCS
01392 #                      #10 request.
01393 
01394 ## @page irdbdconf irdbd.conf
01395 #
01396 # irdbd's default %config file is irdbd.conf, start irdbd with "-c
01397 # filename" to choose a different %config file.  All options are in the
01398 # section "[irdbd]".  Certificates, keys, and trust anchors may be in
01399 # either DER or PEM format.
01400 #
01401 # %Config file options:
01402 #
01403 # @par @c startup-message:
01404 #                      String to %log on startup, useful when
01405 #                      debugging a collection of irdbd instances at
01406 #                      once.
01407 #
01408 # @par @c sql-username:
01409 #                      Username to hand to MySQL when connecting to
01410 #                      irdbd's database.
01411 #
01412 # @par @c sql-database:
01413 #                      MySQL's database name for irdbd's database.
01414 #
01415 # @par @c sql-password:
01416 #                      Password to hand to MySQL when connecting to
01417 #                      irdbd's database.
01418 #
01419 # @par @c bpki-ta:
01420 #                      Name of file containing BPKI trust anchor.  All
01421 #                      BPKI certificate validation in irdbd traces
01422 #                      back to this trust anchor.
01423 #
01424 # @par @c irdbd-cert:
01425 #                      Name of file containing irdbd's own BPKI
01426 #                      certificate. 
01427 #
01428 # @par @c irdbd-key:
01429 #                      Name of file containing RSA key corresponding
01430 #                      to irdbd-cert.
01431 #
01432 # @par @c rpkid-cert:
01433 #                      Name of file containing certificate used the
01434 #                      one and only by rpkid instance authorized to
01435 #                      contact this irdbd instance.
01436 #
01437 # @par @c http-url:
01438 #                      Service URL for irdbd.  Must be a %http:// URL.
01439 
01440 ## @page smoketestconf smoketest.conf
01441 #
01442 # All of the options in smoketest's (optional) configuration file are
01443 # overrides for wired-in default values.  In almost all cases the
01444 # defaults will suffice.  There are a ridiculous number of options,
01445 # most of which noone will ever need, see the code for details.  The
01446 # default name for this configuration file is smoketest.conf, run
01447 # smoketest with "-c filename" to change it.
01448 
01449 ## @page smoketestyaml smoketest.yaml
01450 #
01451 # smoketest's second configuration file is named smoketest.yaml by
01452 # default, run smoketest with "-y filename" to change it.  The YAML
01453 # file contains multiple YAML "documents".  The first document
01454 # describes the initial test layout and resource allocations,
01455 # subsequent documents describe modifications to the initial
01456 # allocations and other parameters.  Resources listed in the initial
01457 # layout are aggregated automatically, so that a node in the resource
01458 # hierarchy automatically receives the resources it needs to issue
01459 # whatever its children are listed as holding.  Actions in the
01460 # subsequent documents are modifications to the current resource set,
01461 # modifications to validity dates or other non-resource parameters, or
01462 # special commands like "sleep".
01463 # 
01464 # Here's an example of current usage:
01465 #
01466 # @verbatim
01467 #     name:           Alice
01468 #     valid_for:      2d
01469 #     sia_base:       "rsync://alice.example/rpki/"
01470 #     kids:
01471 #       - name: Bob
01472 #      kids:
01473 #        - name: Carol
01474 #          ipv4: 192.0.2.1-192.0.2.33
01475 #          asn:  64533
01476 #     ---
01477 #     - name: Carol
01478 #       valid_add:   10
01479 #     ---
01480 #     - name: Carol
01481 #       add_as: 33
01482 #       valid_add:   2d
01483 #     ---
01484 #     - name: Carol
01485 #       valid_sub:   2d
01486 #     ---
01487 #     - name: Carol
01488 #       valid_for:   10d
01489 # @endverbatim
01490 #
01491 # This specifies an initial layout consisting of an RPKI engine named
01492 # "Alice", with one child "Bob", which in turn has one child "Carol".
01493 # Carol has a set of assigned resources, and all resources in the system
01494 # are initially set to be valid for two days from the time at which the
01495 # test is started.  The first subsequent document adds ten seconds to
01496 # the validity interval for Carol's resources and makes no other
01497 # modifications.  The second subsequent document grants Carol additional
01498 # resources and adds another two days to the validity interval for
01499 # Carol's resources.  The next document subtracts two days from the
01500 # validity interval for Carol's resources.  The final document sets the
01501 # validity interval for Carol's resources to ten days.
01502 #
01503 # Operators in subsequent (update) documents:
01504 #
01505 # @par @c add_as:
01506 #              Add ASN resources.
01507 #
01508 # @par @c add_v4:
01509 #              Add IPv4 resources.
01510 #
01511 # @par @c add_v6:
01512 #              Add IPv6 resources.
01513 #
01514 # @par @c sub_as:
01515 #              Subtract ASN resources.
01516 #
01517 # @par @c sub_v4:
01518 #              Subtract IPv4 resources.
01519 #
01520 # @par @c sub_v6:
01521 #              Subtract IPv6 resources.
01522 #
01523 # @par @c valid_until:
01524 #              Set an absolute expiration date.
01525 #
01526 # @par @c valid_for:
01527 #              Set a relative expiration date.
01528 #
01529 # @par @c valid_add:
01530 #              Add to validity interval.
01531 #
01532 # @par @c valid_sub:
01533 #              Subtract from validity interval.
01534 #
01535 # @par @c sleep [interval]:
01536 #              Sleep for specified interval, or until smoketest receives a SIGALRM signal.
01537 #
01538 # @par @c shell cmd...:
01539 #              Pass rest of line verbatim to /bin/sh and block until the shell returns.
01540 #
01541 # Absolute timestamps should be in the form shown (UTC timestamp format
01542 # as used in XML).
01543 #
01544 # Intervals (@c valid_add, @c valid_sub, @c valid_for, @c sleep) are either
01545 # integers, in which case they're interpreted as seconds, or are a
01546 # string of the form "wD xH yM zS" where w, x, y, and z are integers and
01547 # D, H, M, and S indicate days, hours, minutes, and seconds.  In the
01548 # latter case all of the fields are optional, but at least one must be
01549 # specified.  For example, "3D4H" means "three days plus four hours".
01550 
01551 
01552 ## @page Left-Right Left-Right Protocol
01553 #
01554 # The left-right protocol is really two separate client/server
01555 # protocols over separate channels between the RPKI engine and the IR
01556 # back end (IRBE).  The IRBE is the client for one of the
01557 # subprotocols, the RPKI engine is the client for the other.
01558 #
01559 # @section Operations initiated by the IRBE
01560 #
01561 # This part of the protcol uses a kind of message-passing.  Each %object
01562 # that the RPKI engine knows about takes five messages: "create", "set",
01563 # "get", "list", and "destroy".  Actions which are not just data
01564 # operations on %objects are handled via an SNMP-like mechanism, as if
01565 # they were fields to be set.  For example, to generate a keypair one
01566 # "sets" the "generate-keypair" field of a BSC %object, even though there
01567 # is no such field in the %object itself as stored in SQL.  This is a bit
01568 # of a kludge, but the reason for doing it as if these were variables
01569 # being set is to allow composite operations such as creating a BSC,
01570 # populating all of its data fields, and generating a keypair, all as a
01571 # single operation.  With this model, that's trivial, otherwise it's at
01572 # least two round trips.
01573 #
01574 # Fields can be set in either "create" or "set" operations, the
01575 # difference just being whether the %object already exists.  A "get"
01576 # operation returns all visible fields of the %object.  A "list"
01577 # operation returns a %list containing what "get" would have returned on
01578 # each of those %objects.
01579 #
01580 # Left-right protocol %objects are encoded as signed CMS messages
01581 # containing XML as eContent and using an eContentType OID of @c id-ct-xml
01582 # (1.2.840.113549.1.9.16.1.28).  These CMS messages are in turn passed
01583 # as the data for HTTP POST operations, with an HTTP content type of
01584 # "application/x-rpki" for both the POST data and the response data.
01585 #
01586 # All operations allow an optional "tag" attribute which can be any
01587 # alphanumeric token.  The main purpose of the tag attribute is to allow
01588 # batching of multiple requests into a single PDU.
01589 #
01590 # @subsection self_obj <self/> object
01591 #
01592 # A @c &lt;self/&gt; %object represents one virtual RPKI engine.  In simple cases
01593 # where the RPKI engine operator operates the engine only on their own
01594 # behalf, there will only be one @c &lt;self/&gt; %object, representing the engine
01595 # operator's organization, but in environments where the engine operator
01596 # hosts other entities, there will be one @c @c &lt;self/&gt; %object per hosted
01597 # entity (probably including the engine operator's own organization,
01598 # considered as a hosted customer of itself).
01599 #
01600 # Some of the RPKI engine's configured parameters and data are shared by
01601 # all hosted entities, but most are tied to a specific @c &lt;self/&gt; %object.
01602 # Data which are shared by all hosted entities are referred to as
01603 # "per-engine" data, data which are specific to a particular @c &lt;self/&gt;
01604 # %object are "per-self" data.
01605 #
01606 # Since all other RPKI engine %objects refer to a @c &lt;self/&gt; %object via a
01607 # "self_handle" value, one must create a @c &lt;self/&gt; %object before one can
01608 # usefully configure any other left-right protocol %objects.
01609 #
01610 # Every @c &lt;self/&gt; %object has a self_handle attribute, which must be specified
01611 # for the "create", "set", "get", and "destroy" actions.
01612 #
01613 # Payload data which can be configured in a @c &lt;self/&gt; %object:
01614 #
01615 # @par @c use_hsm (attribute):
01616 #     Whether to use a Hardware Signing Module.  At present this option
01617 #     has no effect, as the implementation does not yet support HSMs.
01618 #
01619 # @par @c crl_interval (attribute):
01620 #     Positive integer representing the planned lifetime of an RPKI CRL
01621 #     for this @c &lt;self/&gt;, measured in seconds.
01622 #
01623 # @par @c regen_margin (attribute):
01624 #     Positive integer representing how long before expiration of an
01625 #     RPKI certificiate a new one should be generated, measured in
01626 #     seconds.  At present this only affects the one-off EE
01627 #     certificates associated with ROAs.  This parameter also controls
01628 #     how long before the nextUpdate time of CRL or manifest the CRL
01629 #     or manifest should be updated.
01630 #
01631 # @par @c bpki_cert (element):
01632 #     BPKI CA certificate for this @c &lt;self/&gt;.  This is used as part of the
01633 #     certificate chain when validating incoming TLS and CMS messages,
01634 #     and should be the issuer of cross-certification BPKI certificates
01635 #     used in @c &lt;repository/&gt;, @c &lt;parent/&gt;, and @c &lt;child/&gt; %objects.  If the
01636 #     bpki_glue certificate is in use (below), the bpki_cert certificate
01637 #     should be issued by the bpki_glue certificate; otherwise, the
01638 #     bpki_cert certificate should be issued by the per-engine bpki_ta
01639 #     certificate.
01640 #
01641 # @par @c bpki_glue (element):
01642 #     Another BPKI CA certificate for this @c &lt;self/&gt;, usually not needed.
01643 #     Certain pathological cross-certification cases require a
01644 #     two-certificate chain due to issuer name conflicts.  If used, the
01645 #     bpki_glue certificate should be the issuer of the bpki_cert
01646 #     certificate and should be issued by the per-engine bpki_ta
01647 #     certificate; if not needed, the bpki_glue certificate should be
01648 #     left unset.
01649 #
01650 # Control attributes that can be set to "yes" to force actions:
01651 #
01652 # @par @c rekey:
01653 #     Start a key rollover for every RPKI CA associated with every
01654 #     @c &lt;parent/&gt; %object associated with this @c &lt;self/&gt; %object.  This is the
01655 #     first phase of a key rollover operation.
01656 #
01657 # @par @c revoke:
01658 #     Revoke any remaining certificates for any expired key associated
01659 #     with any RPKI CA for any @c &lt;parent/&gt; %object associated with this
01660 #     @c &lt;self/&gt; %object.   This is the second (cleanup) phase for a key
01661 #     rollover operation; it's separate from the first phase to leave
01662 #     time for new RPKI certificates to propegate and be installed.
01663 #
01664 # @par @c reissue:
01665 #     Not implemented, may be removed from protocol.  Original theory
01666 #     was that this operation would force reissuance of any %object with
01667 #     a changed key, but as that happens automatically as part of the
01668 #     key rollover mechanism this operation seems unnecessary.
01669 #
01670 # @par @c run_now:
01671 #     Force immediate processing for all tasks associated with this
01672 #     @c &lt;self/&gt; %object that would ordinarily be performed under cron.  Not
01673 #     currently implemented.
01674 #
01675 # @par @c publish_world_now:
01676 #     Force (re)publication of every publishable %object for this @c &lt;self/&gt;
01677 #     %object.  Not currently implemented.   Intended to aid in recovery
01678 #     if RPKI engine and publication engine somehow get out of sync.
01679 #
01680 #
01681 # @subsection bsc_obj <bsc/> object
01682 #
01683 # The @c &lt;bsc/&gt; ("business signing context") %object represents all the BPKI
01684 # data needed to sign outgoing CMS messages.  Various other
01685 # %objects include pointers to a @c &lt;bsc/&gt; %object.  Whether a particular
01686 # @c &lt;self/&gt; uses only one @c &lt;bsc/&gt; or multiple is a configuration decision
01687 # based on external requirements: the RPKI engine code doesn't care, it
01688 # just cares that, for any %object representing a relationship for which
01689 # it must sign messages, there be a @c &lt;bsc/&gt; %object that it can use to
01690 # produce that signature.
01691 #
01692 # Every @c &lt;bsc/&gt; %object has a bsc_handle, which must be specified for the
01693 # "create", "get", "set", and "destroy" actions.  Every @c &lt;bsc/&gt; also has a self_handle
01694 # attribute which indicates the @c &lt;self/&gt; %object with which this @c &lt;bsc/&gt;
01695 # %object is associated.
01696 #
01697 # Payload data which can be configured in a @c &lt;isc/&gt; %object:
01698 #
01699 # @par @c signing_cert (element):
01700 #     BPKI certificate to use when generating a signature.
01701 #
01702 # @par @c signing_cert_crl (element):
01703 #     CRL which would %list signing_cert if it had been revoked.
01704 #
01705 # Control attributes that can be set to "yes" to force actions:
01706 #
01707 # @par @c generate_keypair:
01708 #     Generate a new BPKI keypair and return a PKCS #10 certificate
01709 #     request.  The resulting certificate, once issued, should be
01710 #     configured as this @c &lt;bsc/&gt; %object's signing_cert.
01711 #
01712 # Additional attributes which may be specified when specifying
01713 # "generate_keypair":
01714 #
01715 # @par @c key_type:
01716 #     Type of BPKI keypair to generate.  "rsa" is both the default and,
01717 #     at the moment, the only allowed value.
01718 #
01719 # @par @c hash_alg:
01720 #     Cryptographic hash algorithm to use with this keypair.  "sha256"
01721 #     is both the default and, at the moment, the only allowed value.
01722 #
01723 # @par @c key_length:
01724 #     Length in bits of the keypair to be generated.  "2048" is both the
01725 #     default and, at the moment, the only allowed value.
01726 #
01727 # Replies to "create" and "set" actions that specify "generate-keypair"
01728 # include a &lt;bsc_pkcs10/> element, as do replies to "get" and "list"
01729 # actions for a @c &lt;bsc/&gt; %object for which a "generate-keypair" command has
01730 # been issued.  The RPKI engine stores the PKCS #10 request, which
01731 # allows the IRBE to reuse the request if and when it needs to reissue
01732 # the corresponding BPKI signing certificate.
01733 #
01734 # @subsection parent_obj <parent/> object
01735 #
01736 # The @c &lt;parent/&gt; %object represents the RPKI engine's view of a particular
01737 # parent of the current @c &lt;self/&gt; %object in the up-down protocol.  Due to
01738 # the way that the resource hierarchy works, a given @c &lt;self/&gt; may obtain
01739 # resources from multiple parents, but it will always have at least one;
01740 # in the case of IANA or an RIR, the parent RPKI engine may be a trivial
01741 # stub.
01742 #
01743 # Every @c &lt;parent/&gt; %object has a parent_handle, which must be specified for
01744 # the "create", "get", "set", and "destroy" actions.  Every @c &lt;parent/&gt; also has a
01745 # self_handle attribute which indicates the @c &lt;self/&gt; %object with which this
01746 # @c &lt;parent/&gt; %object is associated, a bsc_handle attribute indicating the @c &lt;bsc/&gt;
01747 # %object to be used when signing messages sent to this parent, and a
01748 # repository_handle indicating the @c &lt;repository/&gt; %object to be used when
01749 # publishing issued by the certificate issued by this parent.
01750 #
01751 # Payload data which can be configured in a @c &lt;parent/&gt; %object:
01752 #
01753 # @par @c peer_contact_uri (attribute):
01754 #     HTTP URI used to contact this parent.
01755 #
01756 # @par @c sia_base (attribute):
01757 #     The leading portion of an rsync URI that the RPKI engine should
01758 #     use when composing the publication URI for %objects issued by the
01759 #     RPKI certificate issued by this parent.
01760 #
01761 # @par @c sender_name (attribute):
01762 #     Sender name to use in the up-down protocol when talking to this
01763 #     parent.  The RPKI engine doesn't really care what this value is,
01764 #     but other implementations of the up-down protocol do care.
01765 #
01766 # @par @c recipient_name (attribute):
01767 #     Recipient name to use in the up-down protocol when talking to this
01768 #     parent.   The RPKI engine doesn't really care what this value is,
01769 #     but other implementations of the up-down protocol do care.
01770 #
01771 # @par @c bpki_cms_cert (element):
01772 #     BPKI CMS CA certificate for this @c &lt;parent/&gt;.  This is used as part
01773 #     of the certificate chain when validating incoming CMS messages If
01774 #     the bpki_cms_glue certificate is in use (below), the bpki_cms_cert
01775 #     certificate should be issued by the bpki_cms_glue certificate;
01776 #     otherwise, the bpki_cms_cert certificate should be issued by the
01777 #     bpki_cert certificate in the @c &lt;self/&gt; %object.
01778 #
01779 # @par @c bpki_cms_glue (element):
01780 #     Another BPKI CMS CA certificate for this @c &lt;parent/&gt;, usually not
01781 #     needed.  Certain pathological cross-certification cases require a
01782 #     two-certificate chain due to issuer name conflicts.  If used, the
01783 #     bpki_cms_glue certificate should be the issuer of the
01784 #     bpki_cms_cert certificate and should be issued by the bpki_cert
01785 #     certificate in the @c &lt;self/&gt; %object; if not needed, the
01786 #     bpki_cms_glue certificate should be left unset.
01787 #
01788 # Control attributes that can be set to "yes" to force actions:
01789 #
01790 # @par @c rekey:
01791 #     This is like the rekey command in the @c &lt;self/&gt; %object, but limited
01792 #     to RPKI CAs under this parent.
01793 #
01794 # @par @c reissue:
01795 #     This is like the reissue command in the @c &lt;self/&gt; %object, but limited
01796 #     to RPKI CAs under this parent.
01797 #
01798 # @par @c revoke:
01799 #     This is like the revoke command in the @c &lt;self/&gt; %object, but limited
01800 #     to RPKI CAs under this parent.
01801 #
01802 # @subsection child_obj <child/> object
01803 #
01804 # The @c &lt;child/&gt; %object represents the RPKI engine's view of particular
01805 # child of the current @c &lt;self/&gt; in the up-down protocol.
01806 #
01807 # Every @c &lt;child/&gt; %object has a child_handle, which must be specified for the
01808 # "create", "get", "set", and "destroy" actions.  Every @c &lt;child/&gt; also has a
01809 # self_handle attribute which indicates the @c &lt;self/&gt; %object with which this
01810 # @c &lt;child/&gt; %object is associated.
01811 #
01812 # Payload data which can be configured in a @c &lt;child/&gt; %object:
01813 #
01814 # @par @c bpki_cert (element):
01815 #     BPKI CA certificate for this @c &lt;child/&gt;.  This is used as part of
01816 #     the certificate chain when validating incoming TLS and CMS
01817 #     messages.  If the bpki_glue certificate is in use (below), the
01818 #     bpki_cert certificate should be issued by the bpki_glue
01819 #     certificate; otherwise, the bpki_cert certificate should be issued
01820 #     by the bpki_cert certificate in the @c &lt;self/&gt; %object.
01821 #
01822 # @par @c bpki_glue (element):
01823 #     Another BPKI CA certificate for this @c &lt;child/&gt;, usually not needed.
01824 #     Certain pathological cross-certification cases require a
01825 #     two-certificate chain due to issuer name conflicts.  If used, the
01826 #     bpki_glue certificate should be the issuer of the bpki_cert
01827 #     certificate and should be issued by the bpki_cert certificate in
01828 #     the @c &lt;self/&gt; %object; if not needed, the bpki_glue certificate
01829 #     should be left unset.
01830 #
01831 # Control attributes that can be set to "yes" to force actions:
01832 #
01833 # @par @c reissue:
01834 #     Not implemented, may be removed from protocol.
01835 #
01836 # @subsection repository_obj <repository/> object
01837 #
01838 # The @c &lt;repository/&gt; %object represents the RPKI engine's view of a
01839 # particular publication repository used by the current @c &lt;self/&gt; %object.
01840 #
01841 # Every @c &lt;repository/&gt; %object has a repository_handle, which must be
01842 # specified for the "create", "get", "set", and "destroy" actions.  Every
01843 # @c &lt;repository/&gt; also has a self_handle attribute which indicates the @c &lt;self/&gt;
01844 # %object with which this @c &lt;repository/&gt; %object is associated.
01845 #
01846 # Payload data which can be configured in a @c &lt;repository/&gt; %object:
01847 #
01848 # @par @c peer_contact_uri (attribute):
01849 #     HTTP URI used to contact this repository.
01850 #
01851 # @par @c bpki_cms_cert (element):
01852 #     BPKI CMS CA certificate for this @c &lt;repository/&gt;.  This is used as part
01853 #     of the certificate chain when validating incoming CMS messages If
01854 #     the bpki_cms_glue certificate is in use (below), the bpki_cms_cert
01855 #     certificate should be issued by the bpki_cms_glue certificate;
01856 #     otherwise, the bpki_cms_cert certificate should be issued by the
01857 #     bpki_cert certificate in the @c &lt;self/&gt; %object.
01858 #
01859 # @par @c bpki_cms_glue (element):
01860 #     Another BPKI CMS CA certificate for this @c &lt;repository/&gt;, usually not
01861 #     needed.  Certain pathological cross-certification cases require a
01862 #     two-certificate chain due to issuer name conflicts.  If used, the
01863 #     bpki_cms_glue certificate should be the issuer of the
01864 #     bpki_cms_cert certificate and should be issued by the bpki_cert
01865 #     certificate in the @c &lt;self/&gt; %object; if not needed, the
01866 #     bpki_cms_glue certificate should be left unset.
01867 #
01868 # At present there are no control attributes for @c &lt;repository/&gt; %objects.
01869 #
01870 # @subsection route_origin_obj <route_origin/> object
01871 #
01872 # This section is out-of-date. The @c &lt;route_origin/&gt; %object
01873 # has been replaced by the @c &lt;list_roa_requests/&gt; IRDB query,
01874 # but the documentation for that hasn't been written yet.
01875 #
01876 # The @c &lt;route_origin/&gt; %object is a kind of prototype for a ROA.  It
01877 # contains all the information needed to generate a ROA once the RPKI
01878 # engine obtains the appropriate RPKI certificates from its parent(s).
01879 #
01880 # Note that a @c &lt;route_origin/&gt; %object represents a ROA to be generated on
01881 # behalf of @c &lt;self/&gt;, not on behalf of a @c &lt;child/&gt;.  Thus, a hosted entity
01882 # that has no children but which does need to generate ROAs would be
01883 # represented by a hosted @c &lt;self/&gt; with no @c &lt;child/&gt; %objects but one or
01884 # more @c &lt;route_origin/&gt; %objects.   While lumping ROA generation in with
01885 # the other RPKI engine activities may seem a little odd at first, it's
01886 # a natural consequence of the design requirement that the RPKI daemon
01887 # never transmit private keys across the network in any form; given this
01888 # requirement, the RPKI engine that holds the private keys for an RPKI
01889 # certificate must also be the engine which generates any ROAs that
01890 # derive from that RPKI certificate.
01891 #
01892 # The precise content of the @c &lt;route_origin/&gt; has changed over time as
01893 # the underlying ROA specification has changed.  The current
01894 # implementation as of this writing matches what we expect to see in
01895 # draft-ietf-sidr-roa-format-03, once it is issued.  In particular, note
01896 # that the exactMatch boolean from the -02 draft has been replaced by
01897 # the prefix and maxLength encoding used in the -03 draft.
01898 #
01899 # Payload data which can be configured in a @c &lt;route_origin/&gt; %object:
01900 #
01901 # @par @c asn (attribute):
01902 #     Autonomous System Number (ASN) to place in the generated ROA.  A
01903 #     single ROA can only grant authorization to a single ASN; multiple
01904 #     ASNs require multiple ROAs, thus multiple @c &lt;route_origin/&gt; %objects.
01905 #
01906 # @par @c ipv4 (attribute):
01907 #     %List of IPv4 prefix and maxLength values, see below for format.
01908 #
01909 # @par @c ipv6 (attribute):
01910 #     %List of IPv6 prefix and maxLength values, see below for format.
01911 #
01912 # Control attributes that can be set to "yes" to force actions:
01913 #
01914 # @par @c suppress_publication:
01915 #     Not implemented, may be removed from protocol.
01916 #
01917 # The lists of IPv4 and IPv6 prefix and maxLength values are represented
01918 # as comma-separated text strings, with no whitespace permitted.  Each
01919 # entry in such a string represents a single prefix/maxLength pair.
01920 #
01921 # ABNF for these address lists:
01922 #
01923 # @verbatim
01924 #
01925 #   <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ]
01926 #                         ; Where <max_prefixlen> defaults to the same
01927 #                         ; value as <prefixlen>.
01928 #
01929 #   <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> )
01930 #
01931 # @endverbatim
01932 #
01933 # For example, @c "10.0.1.0/24-32,10.0.2.0/24", which is a shorthand
01934 # form of @c "10.0.1.0/24-32,10.0.2.0/24-24".
01935 #
01936 # @section irdb_queries Operations initiated by the RPKI engine
01937 #
01938 # The left-right protocol also includes queries from the RPKI engine
01939 # back to the IRDB.  These queries do not follow the message-passing
01940 # pattern used in the IRBE-initiated part of the protocol.  Instead,
01941 # there's a single query back to the IRDB, with a corresponding
01942 # response.  The CMS encoding are the same as in the rest of
01943 # the protocol, but the BPKI certificates will be different as the
01944 # back-queries and responses form a separate communication channel.
01945 #
01946 # @subsection list_resources_msg <list_resources/> messages
01947 #
01948 # The @c &lt;list_resources/&gt; query and response allow the RPKI engine to ask
01949 # the IRDB for information about resources assigned to a particular
01950 # child.  The query must include both a @c "self_handle" attribute naming
01951 # the @c &lt;self/&gt; that is making the request and also a @c "child_handle"
01952 # attribute naming the child that is the subject of the query.  The
01953 # query and response also allow an optional @c "tag" attribute of the
01954 # same form used elsewhere in this protocol, to allow batching.
01955 #
01956 # A @c &lt;list_resources/&gt; response includes the following attributes, along
01957 # with the @c tag (if specified), @c self_handle, and @c child_handle copied
01958 # from the request:
01959 #
01960 # @par @c valid_until:
01961 #     A timestamp indicating the date and time at which certificates
01962 #     generated by the RPKI engine for these data should expire.  The
01963 #     timestamp is expressed as an XML @c xsd:dateTime, must be
01964 #     expressed in UTC, and must carry the "Z" suffix indicating UTC.
01965 #
01966 # @par @c asn:
01967 #     A %list of autonomous sequence numbers, expressed as a
01968 #     comma-separated sequence of decimal integers with no whitespace.
01969 #
01970 # @par @c ipv4:
01971 #     A %list of IPv4 address prefixes and ranges, expressed as a
01972 #     comma-separated %list of prefixes and ranges with no whitespace.
01973 #     See below for format details.
01974 #
01975 # @par @c ipv6:
01976 #     A %list of IPv6 address prefixes and ranges, expressed as a
01977 #     comma-separated %list of prefixes and ranges with no whitespace.
01978 #     See below for format details.
01979 #
01980 # Entries in a %list of address prefixes and ranges can be either
01981 # prefixes, which are written in the usual address/prefixlen notation,
01982 # or ranges, which are expressed as a pair of addresses denoting the
01983 # beginning and end of the range, written in ascending order separated
01984 # by a single "-" character.  This format is superficially similar to
01985 # the format used for prefix and maxLength values in the @c &lt;route_origin/&gt;
01986 # %object, but the semantics differ: note in particular that
01987 # @c &lt;route_origin/&gt; %objects don't allow ranges, while @c &lt;list_resources/&gt;
01988 # messages don't allow a maxLength specification.
01989 #
01990 # @section left_right_error_handling Error handling
01991 #
01992 # Error in this protocol are handled at two levels.
01993 #
01994 # Since all messages in this protocol are conveyed over HTTP
01995 # connections, basic errors are indicated via the HTTP response code.
01996 # 4xx and 5xx responses indicate that something bad happened.  Errors
01997 # that make it impossible to decode a query or encode a response are
01998 # handled in this way.
01999 #
02000 # Where possible, errors will result in a @c &lt;report_error/&gt; message which
02001 # takes the place of the expected protocol response message.
02002 # @c &lt;report_error/&gt; messages are CMS-signed XML messages like the rest of
02003 # this protocol, and thus can be archived to provide an audit trail.
02004 #
02005 # @c &lt;report_error/&gt; messages only appear in replies, never in queries.
02006 # The @c &lt;report_error/&gt; message can appear on either the "forward" (IRBE
02007 # as client of RPKI engine) or "back" (RPKI engine as client of IRDB)
02008 # communication channel.
02009 #
02010 # The @c &lt;report_error/&gt; message includes an optional @c "tag" attribute to
02011 # assist in matching the error with a particular query when using
02012 # batching, and also includes a @c "self_handle" attribute indicating the
02013 # @c &lt;self/&gt; that issued the error.
02014 #
02015 # The error itself is conveyed in the @c error_code (attribute).  The
02016 # value of this attribute is a token indicating the specific error that
02017 # occurred.  At present this will be the name of a Python exception; the
02018 # production version of this protocol will nail down the allowed error
02019 # tokens here, probably in the RelaxNG schema.
02020 #
02021 # The body of the @c &lt;report_error/&gt; element itself is an optional text
02022 # string; if present, this is debugging information.  At present this
02023 # capabilty is not used, debugging information goes to syslog.
02024 
02025 ## @page Publication Publication protocol
02026 #
02027 # The %publication protocol is really two separate client/server
02028 # protocols, between different parties.  The first is a configuration
02029 # protocol for an IRBE to use to configure a %publication engine,
02030 # the second is the interface by which authorized clients request
02031 # %publication of specific objects.
02032 #
02033 # Much of the architecture of the %publication protocol is borrowed
02034 # from the @ref Left-Right "left-right protocol": like the
02035 # left-right protocol, the %publication protocol uses CMS-wrapped XML
02036 # over HTTP with the same eContentType OID and the same HTTP
02037 # content-type, and the overall style of the XML messages is very
02038 # similar to the left-right protocol.  All operations allow an
02039 # optional "tag" attribute to allow batching.
02040 #
02041 # The %publication engine operates a single HTTP server which serves
02042 # both of these subprotocols.  The two subprotocols share a single
02043 # server port, but use distinct URLs to allow demultiplexing.
02044 #
02045 # @section Publication-control Publication control subprotocol
02046 #
02047 # The control subprotocol reuses the message-passing design of the
02048 # left-right protocol.  Configured objects support the "create", "set",
02049 # "get", "list", and "destroy" actions, or a subset thereof when the
02050 # full set of actions doesn't make sense.
02051 #
02052 # @subsection config_obj <config/> object
02053 #
02054 # The &lt;config/&gt; %object allows configuration of data that apply to the
02055 # entire %publication server rather than a particular client.
02056 #
02057 # There is exactly one &lt;config/&gt; %object in the %publication server, and
02058 # it only supports the "set" and "get" actions -- it cannot be created
02059 # or destroyed.
02060 #
02061 # Payload data which can be configured in a &lt;config/&gt; %object:
02062 #
02063 # @par @c bpki_crl (element):
02064 #     This is the BPKI CRL used by the %publication server when
02065 #     signing the CMS wrapper on responses in the %publication
02066 #     subprotocol.  As the CRL must be updated at regular intervals,
02067 #     it's not practical to restart the %publication server when the
02068 #     BPKI CRL needs to be updated.  The BPKI model doesn't require
02069 #     use of a BPKI CRL between the IRBE and the %publication server,
02070 #     so we can use the %publication control subprotocol to update the
02071 #     BPKI CRL.
02072 #
02073 # @subsection client_obj <client/> object
02074 #
02075 # The &lt;client/&gt; %object represents one client authorized to use the
02076 # %publication server.
02077 #
02078 # The &lt;client/&gt; %object supports the full set of "create", "set", "get",
02079 # "list", and "destroy" actions.  Each client has a "client_handle"
02080 # attribute, which is used in responses and must be specified in "create", "set",
02081 # "get", or "destroy" actions.
02082 #
02083 # Payload data which can be configured in a &lt;client/&gt; %object:
02084 #
02085 # @par @c base_uri (attribute):
02086 #     This is the base URI below which this client is allowed to publish
02087 #     data.  The %publication server may impose additional constraints in
02088 #     the case of a child publishing beneath its parent.
02089 #
02090 # @par @c bpki_cert (element):
02091 #     BPKI CA certificate for this &lt;client/&gt;.  This is used as part of
02092 #     the certificate chain when validating incoming TLS and CMS
02093 #     messages.  If the bpki_glue certificate is in use (below), the
02094 #     bpki_cert certificate should be issued by the bpki_glue
02095 #     certificate; otherwise, the bpki_cert certificate should be issued
02096 #     by the %publication engine's bpki_ta certificate.
02097 #
02098 # @par @c bpki_glue (element):
02099 #     Another BPKI CA certificate for this &lt;client/&gt;, usually not
02100 #     needed.  Certain pathological cross-certification cases require a
02101 #     two-certificate chain due to issuer name conflicts.  If used, the
02102 #     bpki_glue certificate should be the issuer of the bpki_cert
02103 #     certificate and should be issued by the %publication engine's
02104 #     bpki_ta certificate; if not needed, the bpki_glue certificate
02105 #     should be left unset.
02106 #
02107 # @section Publication-publication Publication subprotocol
02108 #
02109 # The %publication subprotocol is structured somewhat differently from
02110 # the %publication control protocol.  Objects in the %publication
02111 # subprotocol represent objects to be published or objects to be
02112 # withdrawn from %publication.  Each kind of %object supports two actions:
02113 # "publish" and "withdraw".  In each case the XML element representing
02114 # hte %object to be published or withdrawn has a "uri" attribute which
02115 # contains the %publication URI.  For "publish" actions, the XML element
02116 # body contains the DER %object to be published, encoded in Base64; for
02117 # "withdraw" actions, the XML element body is empty.
02118 #
02119 # In theory, the detailed access control for each kind of %object might
02120 # be different.  In practice, as of this writing, access control for all
02121 # objects is a simple check that the client's @c "base_uri" is a leading
02122 # substring of the %publication URI.  Details of why access control might
02123 # need to become more complicated are discussed in a later section.
02124 #
02125 # @subsection certificate_obj <certificate/> object
02126 #
02127 # The &lt;certificate/&gt; %object represents an RPKI certificate to be
02128 # published or withdrawn.
02129 #
02130 # @subsection crl_obj <crl/> object
02131 #
02132 # The &lt;crl/&gt; %object represents an RPKI CRL to be published or withdrawn.
02133 #
02134 # @subsection manifest_obj <manifest/> object
02135 #
02136 # The &lt;manifest/&gt; %object represents an RPKI %publication %manifest to be
02137 # published or withdrawn.
02138 #
02139 # Note that part of the reason for the batching support in the
02140 # %publication protocol is because @em every %publication or withdrawal
02141 # action requires a new %manifest, thus every %publication or withdrawal
02142 # action will involve at least two objects.
02143 #
02144 # @subsection roa_obj <roa/> object
02145 #
02146 # The &lt;roa/&gt; %object represents a ROA to be published or withdrawn.
02147 #
02148 # @section publication_error_handling Error handling
02149 #
02150 # Error in this protocol are handled at two levels.
02151 #
02152 # Since all messages in this protocol are conveyed over HTTP
02153 # connections, basic errors are indicated via the HTTP response code.
02154 # 4xx and 5xx responses indicate that something bad happened.  Errors
02155 # that make it impossible to decode a query or encode a response are
02156 # handled in this way.
02157 #
02158 # Where possible, errors will result in a &lt;report_error/&gt; message which
02159 # takes the place of the expected protocol response message.
02160 # &lt;report_error/&gt; messages are CMS-signed XML messages like the rest of
02161 # this protocol, and thus can be archived to provide an audit trail.
02162 #
02163 # &lt;report_error/&gt; messages only appear in replies, never in
02164 # queries.  The &lt;report_error/&gt; message can appear in both the
02165 # control and publication subprotocols.
02166 #
02167 # The &lt;report_error/&gt; message includes an optional @c "tag" attribute to
02168 # assist in matching the error with a particular query when using
02169 # batching.
02170 #
02171 # The error itself is conveyed in the @c error_code (attribute).  The
02172 # value of this attribute is a token indicating the specific error that
02173 # occurred.  At present this will be the name of a Python exception; the
02174 # production version of this protocol will nail down the allowed error
02175 # tokens here, probably in the RelaxNG schema.
02176 #
02177 # The body of the &lt;report_error/&gt; element itself is an optional text
02178 # string; if present, this is debugging information.  At present this
02179 # capabilty is not used, debugging information goes to syslog.
02180 #
02181 # @section publication_access_control Additional access control considerations.
02182 #
02183 # As detailed above, the %publication protocol is trivially simple.  This
02184 # glosses over two bits of potential complexity:
02185 #
02186 # @li In the case where parent and child are sharing a repository, we'd
02187 #     like to nest child under parent, because testing has demonstrated
02188 #     that even on relatively slow hardware the delays involved in
02189 #     setting up separate rsync connections tend to dominate
02190 #     synchronization time for relying parties.
02191 #
02192 # @li The repository operator might also want to do some checks to
02193 #     assure itself that what it's about to allow the RPKI engine to
02194 #     publish is not dangerous toxic waste.
02195 #
02196 # The up-down protocol includes a mechanism by which a parent can
02197 # suggest a %publication URI to each of its children.  The children are
02198 # not required to accept this hint, and the children must make separate
02199 # arrangements with the repository operator (who might or might not be
02200 # the same as the entity that hosts the children's RPKI engine
02201 # operations) to use the suggested %publication point, but if everything
02202 # works out, this allows children to nest cleanly under their parents
02203 # %publication points, which helps reduce synchronization time for
02204 # relying parties.
02205 #
02206 # In this case, one could argue that the %publication server is
02207 # responsible for preventing one of its clients (the child in the above
02208 # description) from stomping on data published by another of its clients
02209 # (the parent in the above description).  This goes beyond the basic
02210 # access check and requires the %publication server to determine whether
02211 # the parent has given its consent for the child to publish under the
02212 # parent.  Since the RPKI certificate profile requires the child's
02213 # %publication point to be indicated in an SIA extension in a certificate
02214 # issued by the parent to the child, the %publication engine can infer
02215 # this permission from the parent's issuance of a certificate to the
02216 # child.  Since, by definition, the parent also uses this %publication
02217 # server, this is an easy check, as the %publication server should
02218 # already have the parent's certificate available by the time it needs
02219 # to check the child's certificate.
02220 #
02221 # The previous paragraph only covers a "publish" action for a
02222 # &lt;certificate/&gt; %object.  For "publish" actions on other
02223 # objects, the %publication server would need to trace permission back
02224 # to the certificate issued by the parent; for "withdraw" actions,
02225 # the %publication server would have to perform the same checks it
02226 # would perform for a "publish" action, using the current published
02227 # data before withdrawing it.  The latter in turn implies an ordering
02228 # constraint on "withdraw" actions in order to preserve the data
02229 # necessary for these access control decisions; as this may prove
02230 # impractical, the %publication server may probably need to make
02231 # periodic sweeps over its published data looking for orphaned
02232 # objects, but that's probably a good idea anyway.
02233 #
02234 # Note that, in this %publication model, any agreement that the
02235 # repository makes to publish the RPKI engine's output is conditional
02236 # upon the %object to be published passing whatever access control checks
02237 # the %publication server imposes.
02238 
02239 ## @page sql-schemas SQL database schemas
02240 #
02241 # @li @subpage rpkid-sql "rpkid database schema"
02242 # @li @subpage pubd-sql  "pubd database schema"
02243 # @li @subpage irdbd-sql "irdbd database schema"
02244 
02245 ## @page rpkid-sql rpkid SQL schema
02246 #
02247 # @image html  rpkid.png "Diagram of rpkid.sql"
02248 # @image latex rpkid.eps "Diagram of rpkid.sql" height=\textheight
02249 #
02250 # @verbinclude rpkid.sql
02251 
02252 ## @page pubd-sql pubd SQL Schema
02253 #
02254 # @image html  pubd.png "Diagram of pubd.sql"
02255 # @image latex pubd.eps "Diagram of pubd.sql" width=\textwidth
02256 #
02257 # @verbinclude pubd.sql
02258 
02259 ## @page irdbd-sql irdbd SQL Schema
02260 #
02261 # @image html  irdbd.png "Diagram of irdbd.sql"
02262 # @image latex irdbd.eps "Diagram of irdbd.sql" width=\textwidth
02263 #
02264 # @verbinclude irdbd.sql
02265 
02266 ## @page bpki-model BPKI model
02267 #
02268 # The "business PKI" (BPKI) is the PKI used to authenticate
02269 # communication on the up-down, left-right, and %publication protocols.
02270 # BPKI certificates are @em not resource PKI (RPKI) certificates.  The
02271 # BPKI is a separate PKI that represents relationships between the
02272 # various entities involved in the production side of the RPKI system.
02273 # In most cases the BPKI tree will follow existing business
02274 # relationships, hence the "B" (Business) in "BPKI".
02275 #
02276 # Setup of the BPKI is handled by the back end; for the most part,
02277 # rpkid and pubd just use the result.  The one place where the engines
02278 # are directly involved in creation of new BPKI certificates is in the
02279 # production of end-entity certificates for use by the engines.
02280 #
02281 # For the most part an ordinary user of this package need not worry
02282 # about the details explained here, as the
02283 # @ref MyRPKI "myrpki tool"
02284 # takes care of all of this.  However, users who want to understand
02285 # what's going on behind the scenes or who have needs too complex for
02286 # the myrpki tool to handle might want to understand the underlying
02287 # model.
02288 #
02289 # There are a few design principals that underly the chosen BPKI model:
02290 #
02291 # @li Each engine should rely on a single BPKI trust anchor which is
02292 #     controlled by the back end entity that runs the engine; all
02293 #     other trust material should be cross-certified into the engine's
02294 #     BPKI tree.
02295 #
02296 # @li Private keys must never transit the network.
02297 #
02298 # @li Except for end entity certificates, the engine should only have
02299 #     access to the BPKI certificates; in particular, the private key
02300 #     for the BPKI trust anchor should not be accessible to the engine.
02301 #
02302 # @li The number of BPKI keys and certificates that the engine has to
02303 #     manage should be no larger than is necessary.
02304 #
02305 # rpkid's hosting model adds an additional constraint: rpkid's BPKI
02306 # trust anchor belongs to the entity operating rpkid, but the entities
02307 # hosted by rpkid should have control of their own BPKI private keys.
02308 # This implies the need for an additional layer of BPKI certificate
02309 # hierarchy within rpkid.
02310 #
02311 # Here is a simplified picture of what the BPKI might look like for an
02312 # rpkid operator that hosts two entities, "Alice" and "Ellen":
02313 #
02314 # @image html  rpkid-bpki.png
02315 # @image latex rpkid-bpki.eps width=\textwidth
02316 #
02317 # Black objects belong to the hosting entity, blue objects belong to
02318 # the hosted entities, red objects are cross-certified objects from
02319 # the hosted entities' peers.  The arrows indicate certificate
02320 # issuance: solid arrows are the ones that rpkid will care about
02321 # during certificate validation, dotted arrows show the origin of the
02322 # EE certificates that rpkid uses to sign CMS and TLS messages.
02323 #
02324 # The certificate tree looks complicated, but the set of certificates
02325 # needed to build any particular validation chain is obvious.
02326 #
02327 # Detailed instructions on how to build a BPKI are beyond the scope of
02328 # this document, but one can handle simple cases using the OpenSSL
02329 # command line tool and cross_certify; the latter is a tool
02330 # designed specifically for the purpose of generating the
02331 # cross-certification certificates needed to splice foreign trust
02332 # material into a BPKI tree.
02333 #
02334 # The BPKI tree for a pubd instance is similar to to the BPKI tree for
02335 # an rpkid instance, but is a bit simpler, as pubd does not provide
02336 # hosting in the same sense that rpkid does: pubd is a relatively
02337 # simple server that publishes objects as instructed by its clients.
02338 #
02339 # Here's a simplified picture of what the BPKI might look like for a
02340 # pubd operator that serves two clients, "Alice" and "Bob":
02341 #
02342 # @image html  pubd-bpki.png
02343 # @image latex pubd-bpki.eps width=\textwidth
02344 #
02345 # While it is likely that RIRs (at least) will operate both rpkid and
02346 # pubd instances, the two functions are conceptually separate.  As far
02347 # as pubd is concerned, it doesn't matter who operates the rpkid
02348 # instance: pubd just has clients, each of which has trust material
02349 # that has been cross-certified into pubd's BPKI.  Similarly, rpkid
02350 # doesn't really care who operates a pubd instance that it's been
02351 # configured to use, it just treats that pubd as a foreign BPKI whose
02352 # trust material has to be cross-certified into its own BPKI.  Cross
02353 # certification itself is done by the back end operator, using
02354 # cross_certify or some equivalent tool; the resulting BPKI
02355 # certificates are configured into rpkid and pubd via the left-right
02356 # protocol and the control subprotocol of the publication protocol,
02357 # respectively.
02358 #
02359 # Because the BPKI tree is almost entirely controlled by the operating
02360 # entity, CRLs are not necessary for most of the BPKI.  The one
02361 # exception to this is the EE certificates issued under the
02362 # cross-certification points.  These EE certificates are generated by
02363 # the peer, not the local operator, and thus require CRLs.  Because of
02364 # this, both rpkid and pubd require regular updates of certain BPKI
02365 # CRLs, again via the left-right and publication control protocols.
02366 #
02367 # Because the left-right protocol and the publication control
02368 # subprotocol are used to configure BPKI certificates and CRLs, they
02369 # cannot themselves use certificates and CRLs configured in this way.
02370 # This is why the configuration files for rpkid and pubd require
02371 # static configuration of the left-right and publication control
02372 # certificates.
02373 
02374 # Local Variables:
02375 # mode:python
02376 # compile-command: "cd ../.. && ./config.status && cd rpkid && make docs"
02377 # End:
 All Classes Namespaces Files Functions Variables