00001 # $Id: __init__.py 2940 2010-01-12 06:59:16Z sra $ 00002 00003 # Copyright (C) 2009 Internet Systems Consortium ("ISC") 00004 # 00005 # Permission to use, copy, modify, and distribute this software for any 00006 # purpose with or without fee is hereby granted, provided that the above 00007 # copyright notice and this permission notice appear in all copies. 00008 # 00009 # THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 00010 # REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 00011 # AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 00012 # INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 00013 # LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 00014 # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 00015 # PERFORMANCE OF THIS SOFTWARE. 00016 00017 # Portions copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") 00018 # 00019 # Permission to use, copy, modify, and distribute this software for any 00020 # purpose with or without fee is hereby granted, provided that the above 00021 # copyright notice and this permission notice appear in all copies. 00022 # 00023 # THE SOFTWARE IS PROVIDED "AS IS" AND ARIN DISCLAIMS ALL WARRANTIES WITH 00024 # REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 00025 # AND FITNESS. IN NO EVENT SHALL ARIN BE LIABLE FOR ANY SPECIAL, DIRECT, 00026 # INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 00027 # LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 00028 # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 00029 # PERFORMANCE OF THIS SOFTWARE. 00030 00031 00032 # This file exists to tell Python that this the content of this 00033 # directory constitute a Python package. Since we're not doing 00034 # anything exotic, this file doesn't need to contain any code, but 00035 # since its existance defines the package, it's as sensible a place as 00036 # any to put the Doxygen mainpage. 00037 00038 # The "usage" text for irbe_cli in the OPERATIONS section is generated 00039 # automatically by running the program with its --help command. 00040 # Should do the same with the other programs. Don't yet have a sane 00041 # way to automate options in config files, though. Would be nice. 00042 00043 ## @mainpage RPKI Engine Reference Manual 00044 # 00045 # This collection of Python modules implements a prototype of the 00046 # RPKI Engine. This is a work in progress. 00047 # 00048 # See http://viewvc.hactrn.net/subvert-rpki.hactrn.net/ for code, 00049 # design documents, a text mirror of portions of APNIC's Wiki, etc. 00050 # 00051 # The RPKI Engine is an implementation of the production-side tools 00052 # for generating certificates, CRLs, and ROAs. The 00053 # <a href="http://viewvc.hactrn.net/subvert-rpki.hactrn.net/rcynic/">relying party tools</a> 00054 # are a separate (and much simpler) package. 00055 # 00056 # The Subversion repository for the entire project is available for 00057 # (read-only) anonymous access at http://subvert-rpki.hactrn.net/. 00058 # 00059 # The documentation you're reading is generated automatically by 00060 # Doxygen from comments and documentation in 00061 # <a href="http://viewvc.hactrn.net/subvert-rpki.hactrn.net/rpkid/rpki/">the code</a>. 00062 # 00063 # Besides the automatically-generated code documentation, this manual 00064 # also includes documentation of the overall package: 00065 # 00066 # @li The @subpage Installation "installation instructions" 00067 # @li The @subpage Operation "operation instructions" 00068 # @li A description of the @subpage Left-right "left-right protocol" 00069 # @li A description of the @subpage Publication "publication protocol" 00070 # @li A description of the @subpage bpki-model "BPKI model" 00071 # used to secure the up-down, left-right, and %publication protocols 00072 # @li A description of the several @subpage sql-schemas "SQL database schemas" 00073 # @li Some suggestions for @subpage further-reading "further reading" 00074 # 00075 # This work was funded from 2006 through 2008 by <a 00076 # href="http://www.arin.net/">ARIN</a>, in collaboration with the 00077 # other Regional Internet Registries. Current work is funded by DHS. 00078 00079 ## @page further-reading Further Reading 00080 # 00081 # If you're interested in this package you might also be interested 00082 # in: 00083 # 00084 # @li <a href="http://viewvc.hactrn.net/subvert-rpki.hactrn.net/rcynic/">The rcynic validation tool</a> 00085 # @li <a href="http://www.hactrn.net/opaque/rcynic.html">A live sample of rcynic's summary output</a> 00086 # @li <a href="http://mirin.apnic.net/resourcecerts/wiki/">APNIC's Wiki</a> 00087 # @li <a href="http://mirin.apnic.net/trac/">APNIC's project Trac instance</a> 00088 00089 ## @page Installation Installation Guide 00090 # 00091 # Preliminary installation instructions for rpkid et al. These are the 00092 # production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). 00093 # See the "rcynic" program for relying party tools. 00094 # 00095 # rpkid is a set of Python modules supporting generation and maintenance 00096 # of resource certificates. Most of the code is in the rpkid/rpki/ 00097 # directory. rpkid itself is a relatively small program that calls the 00098 # library modules. There are several other programs that make use of 00099 # the same libraries, as well as a collection of test programs. 00100 # 00101 # At present the package is intended to be run out of its build 00102 # directory. Setting up proper installation in a system area using the 00103 # Python distutils package would likely not be very hard but has not yet 00104 # been done. 00105 # 00106 # Note that initial development of this code has been on FreeBSD, so 00107 # installation will probably be easiest on FreeBSD. 00108 # 00109 # Before attempting to build the package, you need to install any 00110 # missing prerequisites. Note that the Python code requires Python 00111 # version 2.5. rpkid et al are mostly self-contained, but do require 00112 # a small number of external packages to run. 00113 # 00114 # <ul> 00115 # <li> 00116 # If your Python installation does not already include the sources 00117 # files needed to compile new Python extension modules, you will 00118 # need to install whatever package does include those source 00119 # files. The need for and name of this package varies from system 00120 # to system. On FreeBSD, the base Python interpreter package 00121 # includes the development sources; on at least some Linux 00122 # distributions, you have to install a separate "python-devel" 00123 # package or something similar. If you get compilation errors 00124 # trying to build the POW code (below) and the error message says 00125 # something about the file "Python.h" being missing, this is 00126 # almost certainly your problem. 00127 # </li> 00128 # 00129 # <li> 00130 # <a href="http://codespeak.net/lxml/">http://codespeak.net/lxml/</a>. 00131 # lxml in turn requires the Gnome LibXML2 C libraries. 00132 # <ul> 00133 # <li>FreeBSD: /usr/ports/devel/py-lxml</li> 00134 # <li>Fedora: python-lxml.i386</li> 00135 # <li>Ubuntu: python-lxml</li> 00136 # </ul> 00137 # </li> 00138 # 00139 # <li> 00140 # <a href="http://sourceforge.net/projects/mysql-python/">http://sourceforge.net/projects/mysql-python/</a>. 00141 # MySQLdb in turn requires MySQL client and server. rpkid et al have 00142 # been tested with MySQL 5.0 and 5.1. 00143 # <ul> 00144 # <li>FreeBSD: /usr/ports/databases/py-MySQLdb</li> 00145 # <li>Fedora: MySQL-python.i386</li> 00146 # <li>Ubuntu: python-mysqldb</li> 00147 # </ul> 00148 # </li> 00149 # </ul> 00150 # 00151 # rpkid et al also make heavy use of a modified copy of the Python 00152 # OpenSSL Wrappers (POW) package, but this copy has enough modifications 00153 # and additions that it's included in the subversion tree. 00154 # 00155 # The next step is to build the OpenSSL and POW binaries. At present 00156 # the OpenSSL code is just a snapshot of the OpenSSL development 00157 # sources, compiled with special options to enable RFC 3779 support 00158 # that ISC wrote under previous contract to ARIN. The POW (Python 00159 # OpenSSL Wrapper) library is an extended copy of the stock POW 00160 # release. 00161 # 00162 # To build these, cd to the top-level directory in the distribution and 00163 # type "make". 00164 # 00165 # @verbatim 00166 # $ cd $top 00167 # $ make 00168 # @endverbatim 00169 # 00170 # This should automatically build everything, in the right order, 00171 # including staticly linking the POW extension module with the OpenSSL 00172 # library to provide RFC 3779 support. If you get errors building 00173 # POW, see the above discussion of Python development sources. 00174 # 00175 # You will also need a MySQL installation. This code was developed 00176 # using MySQL 5.1 and has been tested with MySQL 5.0 and 5.1. 00177 # 00178 # The architecture is intended to support hardware signing modules 00179 # (HSMs), but the code to support them has not been written. 00180 # 00181 # At this point, you should have all the necessary software installed. 00182 # You will probably want to test it. All tests should be run from the 00183 # rpkid/ directory. The test suite requires a few more external 00184 # packages, only one of which is Python code. 00185 # 00186 # <ul> 00187 # <li> 00188 # <a href="http://pyyaml.org/">http://pyyaml.org/</a>. 00189 # testpoke.py (an up-down protocol command line test client) and 00190 # testbed.py (a test harness) use PyYAML. 00191 # <ul> 00192 # <li>FreeBSD: /usr/ports/devel/py-yaml</li> 00193 # <li>Ubuntu: python-yaml</li> 00194 # </ul> 00195 # </li> 00196 # 00197 # <li> 00198 # <a href="http://xmlsoft.org/XSLT/">http://xmlsoft.org/XSLT/</a>. 00199 # Some of the test code uses xsltproc, from the Gnome LibXSLT 00200 # package. 00201 # <ul> 00202 # <li>FreeBSD: /usr/ports/textproc/libxslt</li> 00203 # <li>Ubuntu: xsltproc</li> 00204 # </ul> 00205 # </li> 00206 # 00207 # <li> 00208 # <a href="http://w3m.sourceforge.net/">http://w3m.sourceforge.net/</a>. 00209 # testbed.py uses w3m to display the summary output from rcynic. 00210 # Nothing terrible will happen if w3m isn't available, testbed.py 00211 # will just complain about it being missing and won't display 00212 # rcynic's output. 00213 # <ul> 00214 # <li>FreeBSD: /usr/ports/www/w3m</li> 00215 # <li>Ubuntu: w3m</li> 00216 # </ul> 00217 # </li> 00218 # </ul> 00219 # 00220 # Some of the tests require MySQL databases to store their data. To set 00221 # up all the databases that the tests will need, run the SQL commands in 00222 # rpkid/testbed.setup.sql. The MySQL command line client is usually the 00223 # easiest way to do this, eg: 00224 # 00225 # @verbatim 00226 # $ cd $top/rpkid 00227 # $ mysql -u root -p <testbed.setup.sql 00228 # @endverbatim 00229 # 00230 # To run the tests, run "make all-tests": 00231 # 00232 # @verbatim 00233 # $ cd $top/rpkid 00234 # $ make all-tests 00235 # @endverbatim 00236 # 00237 # If nothing explodes, your installation is probably ok. Any Python 00238 # backtraces in the output indicate a problem. 00239 # 00240 # There's a last set of tools that only developers should need, as 00241 # they're only used when modifying schemas or regenerating the 00242 # documentation. These tools are listed here for completeness. 00243 # 00244 # <ul> 00245 # <li> 00246 # <a href="http://www.doxygen.org/">http://www.doxygen.org/</a>. 00247 # Doxygen in turn pulls in several other tools, notably Graphviz, 00248 # pdfLaTeX, and Ghostscript. 00249 # <ul> 00250 # <li>FreeBSD: /usr/ports/devel/doxygen</li> 00251 # <li>Ubuntu: doxygen</li> 00252 # </ul> 00253 # </li> 00254 # 00255 # <li> 00256 # <a href="http://lynx.isc.org/current/">http://lynx.isc.org/current/</a>. 00257 # The documentation build process uses xsltproc and Lynx to dump 00258 # flat text versions of a few critical documentation pages. 00259 # <ul> 00260 # <li>FreeBSD: /usr/ports/www/lynx</li> 00261 # <li>Ubuntu: lynx</li> 00262 # </ul> 00263 # </li> 00264 # 00265 # <li> 00266 # <a href="http://www.thaiopensource.com/relaxng/trang.html">http://www.thaiopensource.com/relaxng/trang.html</a>. 00267 # Trang is used to convert RelaxNG schemas from the human-readable 00268 # "compact" form to the XML form that LibXML2 understands. Trang in 00269 # turn requires Java. 00270 # <ul> 00271 # <li>FreeBSD: /usr/ports/textproc/trang</li> 00272 # </ul> 00273 # </li> 00274 # 00275 # <li> 00276 # <a href="http://search.cpan.org/dist/SQL-Translator/">http://search.cpan.org/dist/SQL-Translator/</a>. 00277 # SQL-Translator, also known as "SQL Fairy", includes code to parse 00278 # an SQL schema and dump a description of it as Graphviz input. 00279 # SQL Fairy in turn requires Perl. 00280 # <ul> 00281 # <li>FreeBSD: /usr/ports/databases/p5-SQL-Translator</li> 00282 # </ul> 00283 # </li> 00284 # </ul> 00285 00286 ## @page Operation Operation Guide 00287 # 00288 # Preliminary operation instructions for rpkid et al. These are the 00289 # production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). 00290 # See rcynic/README for relying party tools. 00291 # 00292 # @warning 00293 # rpkid is still in development, and the code changes more often than 00294 # the hand-maintained portions of this documentation. The following 00295 # text was reasonably accurate at the time it was written but may be 00296 # obsolete by the time you read it. 00297 # 00298 # At present the package is intended to be run out of the @c rpkid/ 00299 # directory. 00300 # 00301 # In addition to the library routines in the @c rpkid/rpki/ directory, 00302 # the package includes the following programs: 00303 # 00304 # @li @c rpkid.py: 00305 # The main RPKI engine daemon. 00306 # 00307 # @li @c pubd.py: 00308 # The publication engine daemon. 00309 # 00310 # @li @c rootd.py: 00311 # A separate daemon for handling the root of an RPKI 00312 # certificate tree. This is essentially a stripped down 00313 # version of rpkid with no SQL database, no left-right 00314 # protocol implementation, and only the parent side of 00315 # the up-down protocol. It's separate because the root 00316 # is a special case in several ways and it was simpler 00317 # to keep the special cases out of the main daemon. 00318 # 00319 # @li @c irdbd.py: 00320 # A sample implementation of an IR database daemon. 00321 # rpkid calls into this to perform lookups via the 00322 # left-right protocol. 00323 # 00324 # @li @c irbe_cli.py: 00325 # A command-line client for the left-right control 00326 # protocol. 00327 # 00328 # @li @c cross_certify.py: 00329 # A BPKI cross-certification tool. 00330 # 00331 # @li @c cronjob.py: 00332 # A trivial HTTP client used to drive rpkid cron events. 00333 # 00334 # @li @c testbed.py: 00335 # A test tool for running a collection of rpkid and irdb 00336 # instances under common control, driven by a unified 00337 # test script. 00338 # 00339 # @li @c testpoke.py: 00340 # A simple client for the up-down protocol, mostly 00341 # compatable with APNIC's rpki_poke.pl tool. 00342 # 00343 # Most of these programs take configuration files in a common format 00344 # similar to that used by the OpenSSL command line tool. The test 00345 # programs also take input in YAML format to drive the tests. Runs of 00346 # the testbed.py test tool will generate a fairly complete set 00347 # configuration files which may be useful as examples. 00348 # 00349 # Basic operation consists of creating the appropriate MySQL databases, 00350 # starting rpkid, pubd, rootd, and irdbd, using the left-right control 00351 # protocol to set up rpkid's internal state, and setting up a cron job 00352 # to invoke rpkid's cron action at regular intervals. All other 00353 # operations should occur either as a result of cron events or as a 00354 # result of incoming left-right and up-down protocol requests. 00355 # 00356 # Note that the full event-driven model for rpkid hasn't yet been 00357 # implemented. The design is intended to allow an arbitrary number of 00358 # hosted RPKI engines to run in a single rpkid instance, but without the 00359 # event-driven tasking model one must set up a separate rpkid instance 00360 # for each hosted RPKI engine. 00361 # 00362 # At present the daemon programs all run in foreground, that is, if one 00363 # wants them to run in background one must do so manually, eg, using 00364 # Bourne shell syntax: 00365 # 00366 # @verbatim 00367 # $ python whatever.py & 00368 # $ echo >whatever.pid "$!" 00369 # @endverbatim 00370 # 00371 # All of the daemons use syslog by default. To make them log to 00372 # stderr instead, use the "-d" option. 00373 # 00374 # @section CommonOptions Common Options 00375 # 00376 # Some of the options that the several daemons take are common to all 00377 # daemons. Which daemon they affect depends only on which sections of 00378 # which config files they are in. 00379 # 00380 # The first group of options are debugging flags, which can be set to 00381 # "true" or "false". If not specified, default values will be chosen 00382 # (generally false). 00383 # 00384 # @li @c debug_http 00385 # Enable verbose http debug logging. 00386 # @li @c debug_tls_certs 00387 # Enable verbose logging about tls certs. 00388 # 00389 # @li @c want_persistent_client 00390 # Enable http 1.1 persistence, client side. 00391 # 00392 # @li @c want_persistent_server 00393 # Enable http 1.1 persistence, server side. 00394 # 00395 # @li @c debug_cms_certs 00396 # Enable verbose logging about cms certs. 00397 # 00398 # @li @c sql_debug 00399 # Enable verbose logging about sql operations. 00400 # 00401 # @li @c gc_debug 00402 # Enable scary garbage collector debugging. 00403 # 00404 # @li @c timer_debug 00405 # Enable verbose logging of timer system. 00406 # 00407 # There are also a few options that allow you to save CMS messages for 00408 # audit or debugging. The save format is a simple MIME encoding in a 00409 # Maildir-format mailbox. The current options are very crude, at some 00410 # point we may provide finer grain controls. 00411 # 00412 # @li @c dump_outbound_cms 00413 # Dump messages we send to this mailbox. 00414 # 00415 # @li @c dump_inbound_cms 00416 # Dump messages we receive to this mailbox. 00417 # 00418 # 00419 # @section rpkid rpkid.py 00420 # 00421 # rpkid is the main RPKI engine daemon. Configuration of rpkid is a 00422 # two step process: a %config file to bootstrap rpkid to the point 00423 # where it can speak using the @link Left-right left-right protocol, 00424 # @endlink followed by dynamic configuration via the left-right 00425 # protocol. In production use the latter stage would be handled by 00426 # the IRBE stub; for test and develoment purposes it's handled by the 00427 # irbe_cli.py command line interface or by the testbed.py test 00428 # framework. 00429 # 00430 # rpkid stores dynamic data in an SQL database, which must have been 00431 # created for it, as explained in the @link Installation installation 00432 # guide. @endlink 00433 # 00434 # The default %config file is rpkid.conf, start rpkid with "-c filename" 00435 # to choose a different %config file. All options are in the section 00436 # "[rpkid]". Certificates, keys, and trust anchors may be in either DER 00437 # or PEM format. 00438 # 00439 # %Config file options: 00440 # 00441 # @li @c startup-message: 00442 # String to %log on startup, useful when 00443 # debugging a collection of rpkid instances at 00444 # once. 00445 # 00446 # @li @c sql-username: 00447 # Username to hand to MySQL when connecting to 00448 # rpkid's database. 00449 # 00450 # @li @c sql-database: 00451 # MySQL's database name for rpkid's database. 00452 # 00453 # @li @c sql-password: 00454 # Password to hand to MySQL when connecting to 00455 # rpkid's database. 00456 # 00457 # @li @c bpki-ta: 00458 # Name of file containing BPKI trust anchor. 00459 # All BPKI certificate verification within rpkid 00460 # traces back to this trust anchor. 00461 # 00462 # @li @c rpkid-cert: 00463 # Name of file containing rpkid's own BPKI EE 00464 # certificate. 00465 # 00466 # @li @c rpkid-key: 00467 # Name of file containing RSA key corresponding 00468 # to rpkid-cert. 00469 # 00470 # @li @c irbe-cert: 00471 # Name of file containing BPKI certificate used 00472 # by IRBE when talking to rpkid. 00473 # 00474 # @li @c irdb-cert: 00475 # Name of file containing BPKI certificate used 00476 # by irdbd. 00477 # 00478 # @li @c irdb-url: 00479 # Service URL for irdbd. Must be a %https:// URL. 00480 # 00481 # @li @c server-host: 00482 # Hostname or IP address on which to listen for 00483 # HTTPS connections. Current default is 00484 # INADDR_ANY (IPv4 0.0.0.0); this will need to 00485 # be hacked to support IPv6 for production. 00486 # 00487 # @li @c server-port: 00488 # TCP port on which to listen for HTTPS 00489 # connections. 00490 # 00491 # 00492 # @section pubd pubd.py 00493 # 00494 # pubd is the publication daemon. It implements the server side of 00495 # the publication protocol, and is used by rpkid to publish the 00496 # certificates and other objects that rpkid generates. 00497 # 00498 # pubd is separate from rpkid for two reasons: 00499 # 00500 # @li The hosting model allows entities which choose to run their own 00501 # copies of rpkid to publish their output under a common 00502 # publication point. In general, encouraging shared publication 00503 # services where practical is a good thing for relying parties, 00504 # as it will speed up rcynic synchronization time. 00505 # 00506 # @li The publication server has to run on (or at least close to) the 00507 # publication point itself, which in turn must be on a publically 00508 # reachable server to be useful. rpkid, on the other hand, need 00509 # only be reachable by the IRBE and its children in the RPKI tree. 00510 # rpkid is a much more complex piece of software than pubd, so in 00511 # some situations it might make sense to wrap tighter firewall 00512 # constraints around rpkid than would be practical if rpkid and 00513 # pubd were a single program. 00514 # 00515 # pubd stores dynamic data in an SQL database, which must have been 00516 # created for it, as explained in the installation guide. pubd also 00517 # stores the published objects themselves as disk files in a 00518 # configurable location which should correspond to an appropriate 00519 # module definition in rsync.conf. 00520 # 00521 # The default %config file is pubd.conf, start pubd with "-c 00522 # filename" to choose a different %config file. ALl options are in 00523 # the section "[pubd]". Certifiates, keys, and trust anchors may be 00524 # either DER or PEM format. 00525 # 00526 # %Config file options: 00527 # 00528 # @li @c sql-username: 00529 # Username to hand to MySQL when connecting to 00530 # pubd's database. 00531 # 00532 # @li @c sql-database: 00533 # MySQL's database name for pubd's database. 00534 # 00535 # @li @c sql-password: 00536 # Password to hand to MySQL when connecting to 00537 # pubd's database. 00538 # 00539 # @li @c bpki-ta: 00540 # Name of file containing master BPKI trust 00541 # anchor for pubd. All BPKI validation in pubd 00542 # traces back to this trust anchor. 00543 # 00544 # @li @c irbe-cert: 00545 # Name of file containing BPKI certificate used 00546 # by IRBE when talking to pubd. 00547 # 00548 # @li @c pubd-cert: 00549 # Name of file containing BPKI certificate used 00550 # by pubd. 00551 # 00552 # @li @c pubd-key: 00553 # Name of file containing RSA key corresponding 00554 # to @c pubd-cert. 00555 # 00556 # @li @c server-host: 00557 # Hostname or IP address on which to listen for 00558 # HTTPS connections. Current default is 00559 # INADDR_ANY (IPv4 0.0.0.0); this will need to 00560 # be hacked to support IPv6 for production. 00561 # 00562 # @li @c server-port: 00563 # TCP port on which to listen for HTTPS 00564 # connections. 00565 # 00566 # @li @c publication-base: 00567 # Path to base of filesystem tree where pubd 00568 # should store publishable objects. Default is 00569 # "publication/". 00570 # 00571 # 00572 # @section rootd rootd.py 00573 # 00574 # rootd is a stripped down implmenetation of (only) the server side of 00575 # the up-down protocol. It's a separate program because the root 00576 # certificate of an RPKI certificate tree requires special handling and 00577 # may also require a special handling policy. rootd is a simple 00578 # implementation intended for test use, it's not suitable for use in a 00579 # production system. All configuration comes via the %config file. 00580 # 00581 # The default %config file is rootd.conf, start rootd with "-c filename" 00582 # to choose a different %config file. All options are in the section 00583 # "[rootd]". Certificates, keys, and trust anchors may be in either DER 00584 # or PEM format. 00585 # 00586 # %Config file options: 00587 # 00588 # @li @c bpki-ta: 00589 # Name of file containing BPKI trust anchor. All 00590 # BPKI certificate validation in rootd traces 00591 # back to this trust anchor. 00592 # 00593 # @li @c rootd-bpki-cert: 00594 # Name of file containing rootd's own BPKI 00595 # certificate. 00596 # 00597 # @li @c rootd-bpki-key: 00598 # Name of file containing RSA key corresponding to 00599 # rootd-bpki-cert. 00600 # 00601 # @li @c rootd-bpki-crl: 00602 # Name of file containing BPKI CRL that would 00603 # cover rootd-bpki-cert had it been revoked. 00604 # 00605 # @li @c child-bpki-cert: 00606 # Name of file containing BPKI certificate for 00607 # rootd's one and only child (RPKI engine to 00608 # which rootd issues an RPKI certificate). 00609 # 00610 # @li @c server-host: 00611 # Hostname or IP address on which to listen for 00612 # HTTPS connections. Default is localhost. 00613 # 00614 # @li @c server-port: 00615 # TCP port on which to listen for HTTPS 00616 # connections. 00617 # 00618 # @li @c rpki-root-key: 00619 # Name of file containing RSA key to use in 00620 # signing resource certificates. 00621 # 00622 # @li @c rpki-root-cert: 00623 # Name of file containing self-signed root 00624 # resource certificate corresponding to 00625 # rpki-root-key. 00626 # 00627 # @li @c rpki-root-dir: 00628 # Name of directory where rootd should write 00629 # RPKI subject certificate, manifest, and CRL. 00630 # 00631 # @li @c rpki-subject-cert: 00632 # Name of file that rootd should use to save the 00633 # one and only certificate it issues. 00634 # Default is "Subroot.cer". 00635 # 00636 # @li @c rpki-root-crl: 00637 # Name of file to which rootd should save its 00638 # RPKI CRL. Default is "Root.crl". 00639 # 00640 # @li @c rpki-root-manifest: 00641 # Name of file to which rootd should save its 00642 # RPKI manifest. Default is "Root.mnf". 00643 # 00644 # @li @c rpki-subject-pkcs10: 00645 # Name of file that rootd should use when saving 00646 # a copy of the received PKCS #10 request for a 00647 # resource certificate. This is only used for 00648 # debugging. Default is not to save the PKCS 00649 # #10 request. 00650 # 00651 # 00652 # @section irdbd irdbd.py 00653 # 00654 # irdbd is a sample implemntation of the server side of the IRDB 00655 # callback subset of the left-right protocol. In production use this 00656 # service is a function of the IRBE stub; irdbd may be suitable for 00657 # production use in simple cases, but an IR with a complex IRDB may need 00658 # to extend or rewrite irdbd. 00659 # 00660 # irdbd requires a pre-populated database to represent the IR's 00661 # customers. irdbd expects this database to use the SQL schema defined 00662 # in rpkid/irdbd.sql. Once this database has been populated, the 00663 # IRBE stub needs to create the appropriate objects in rpkid's database 00664 # via the control subset of the left-right protocol, and store the 00665 # linkage IDs (foreign keys into rpkid's database, basicly) in the 00666 # IRDB. 00667 # 00668 # irdbd's default %config file is irdbd.conf, start irdbd with "-c 00669 # filename" to choose a different %config file. All options are in the 00670 # section "[irdbd]". Certificates, keys, and trust anchors may be in 00671 # either DER or PEM format. 00672 # 00673 # %Config file options: 00674 # 00675 # @li @c startup-message: 00676 # String to %log on startup, useful when 00677 # debugging a collection of irdbd instances at 00678 # once. 00679 # 00680 # @li @c sql-username: 00681 # Username to hand to MySQL when connecting to 00682 # irdbd's database. 00683 # 00684 # @li @c sql-database: 00685 # MySQL's database name for irdbd's database. 00686 # 00687 # @li @c sql-password: 00688 # Password to hand to MySQL when connecting to 00689 # irdbd's database. 00690 # 00691 # @li @c bpki-ta: 00692 # Name of file containing BPKI trust anchor. All 00693 # BPKI certificate validation in irdbd traces 00694 # back to this trust anchor. 00695 # 00696 # @li @c irdbd-cert: 00697 # Name of file containing irdbd's own BPKI 00698 # certificate. 00699 # 00700 # @li @c irdbd-key: 00701 # Name of file containing RSA key corresponding 00702 # to irdbd-cert. 00703 # 00704 # @li @c rpkid-cert: 00705 # Name of file containing certificate used the 00706 # one and only by rpkid instance authorized to 00707 # contact this irdbd instance. 00708 # 00709 # @li @c https-url: 00710 # Service URL for irdbd. Must be a %https:// URL. 00711 # 00712 # 00713 # @section irdbd_cli irbe_cli.py 00714 # 00715 # irbe_cli is a simple command line client for the control subsets of 00716 # the @link Left-right left-right @endlink and @link Publication 00717 # publication @endlink protocols. In production use this 00718 # functionality would be part of the IRBE stub. 00719 # 00720 # Basic configuration of irbe_cli is handled via a %config file. The 00721 # specific action or actions to be performed are specified on the 00722 # command line, and map closely to the protocols themselves. 00723 # 00724 # At present the user is assumed to be able to read the (XML) 00725 # left-right and publication protocol messages, and with one 00726 # exception, irdbd-cli makes no attempt to interpret the responses 00727 # other than to check for signature and syntax errors. The one 00728 # exception is that, if the @c --pem_out option is specified on the 00729 # command line, any PKCS \#10 requests received from rpkid will be 00730 # written in PEM format to that file; this makes it easier to hand 00731 # these requests off to the business PKI (BPKI in order to issue signing 00732 # certs corresponding to newly generated business keys. 00733 # 00734 # @verbinclude irbe_cli.usage 00735 # 00736 # Global options (@c --config, @c --help, @c --pem_out) come first, 00737 # then zero or more commands (@c parent, @c repository, @c self, @c 00738 # child, @c bsc, @c config, @c client), each followed by its own set 00739 # of options. The commands map to elements in the protocols, and the 00740 # command-specific options map to attributes or subelements for those 00741 # commands. 00742 # 00743 # @c --tag is an optional arbitrary tag (think IMAP) to simplify 00744 # matching up replies with batched queries. 00745 # 00746 # @c --*_handle options refer to object primary keys. 00747 # 00748 # The remaining options are specific to the particular commands, and 00749 # follow directly from the protocol specifications. 00750 # 00751 # A trailing "=" in the above option summary indicates that an option 00752 # takes a value, eg, "--action create" or "--action=create". Options 00753 # without a trailing "=" correspond to boolean control attributes. 00754 # 00755 # The default %config file for irbe_cli is irbe_cli.conf, start 00756 # irbe_cli with "-c filename" (or "--config filename") to choose a 00757 # different %config file. All options are in the section 00758 # "[irbe_cli]". Certificates, keys, and trust anchors may be in 00759 # either DER or PEM format. 00760 # 00761 # %Config file options: 00762 # 00763 # @li @c rpkid-bpki-ta: 00764 # Name of file containing BPKI trust anchor to 00765 # use when authenticating messages from rpkid. 00766 # 00767 # @li @c rpkid-irbe-cert: 00768 # Name of file containing BPKI certificate 00769 # irbe_cli should use when talking to rpkid. 00770 # 00771 # @li @c rpkid-irbe-key: 00772 # Name of file containing RSA key corresponding to 00773 # rpkid-irbe-cert. 00774 # 00775 # @li @c rpkid-cert: 00776 # Name of file containing rpkid's BPKI certificate. 00777 # 00778 # @li @c rpkid-url: 00779 # Service URL for rpkid. Must be a %https:// URL. 00780 # 00781 # @li @c pubd-bpki-ta: 00782 # Name of file containing BPKI trust anchor to 00783 # use when authenticating messages from pubd. 00784 # 00785 # @li @c pubd-irbe-cert: 00786 # Name of file containing BPKI certificate 00787 # irbe_cli should use when talking to pubd. 00788 # 00789 # @li @c pubd-irbe-key: 00790 # Name of file containing RSA key corresponding to 00791 # pubd-irbe-cert. 00792 # 00793 # @li @c pubd-cert: 00794 # Name of file containing pubd's BPKI certificate. 00795 # 00796 # @li @c pubd-url: 00797 # Service URL for pubd. Must be a %https:// URL. 00798 # 00799 # 00800 # 00801 # @section cross_certify cross_certify.py 00802 # 00803 # cross_certify.py is a small tool to extract certain fields from an 00804 # existing X.509 certificate and generate issue a new certificate that 00805 # can be used as part of a cross-certification chain. cross_certify 00806 # doesn't take a config file, all of its arguments are specified on 00807 # the command line. 00808 # 00809 # @verbatim 00810 # python cross_certify.py { -i | --in } input_cert 00811 # { -c | --ca } issuing_cert 00812 # { -k | --key } issuing_cert_key 00813 # { -s | --serial } serial_filename 00814 # [ { -h | --help } ] 00815 # [ { -o | --out } filename ] 00816 # [ { -l | --lifetime } timedelta ] 00817 # @endverbatim 00818 # 00819 # 00820 # @section cronjob cronjob.py 00821 # 00822 # This is a trivial program to trigger a cron run within rpkid. 00823 # Ordinarilly rpkid runs its own internal cron process, but for 00824 # scripted testing it is sometimes useful to be able to control when 00825 # cron cycles occur. 00826 # 00827 # The default %config file is cronjob.conf, start cronjob with "-c 00828 # filename" to choose a different %config file. All options are in the 00829 # section "[cronjob]". Certificates, keys, and trust anchors may be in 00830 # either DER or PEM format. 00831 # 00832 # %Config file options: 00833 # 00834 # @li @c bpki-ta: 00835 # Name of file containing BPKI trust anchor. 00836 # 00837 # @li @c irbe-cert: 00838 # Name of file containing cronjob.py's BPKI 00839 # certificate. 00840 # 00841 # @li @c https-key: 00842 # Name of file containing RSA key corresponding 00843 # to irbe-cert. 00844 # 00845 # @li @c rpkid-cert: 00846 # Name of file containing rpkid's BPKI certificate. 00847 # 00848 # @li @c https-url: 00849 # Service URL for rpkid. Must be a %https:// URL. 00850 # 00851 # 00852 # @section testbed testbed.py: 00853 # 00854 # testbed is a test harness to set up and run a collection of rpkid and 00855 # irdbd instances under scripted control. testbed is a very recent 00856 # addition to the toolset and is still evolving rapidly. 00857 # 00858 # Unlike the programs described above, testbed takes two configuration 00859 # files in different languages. The first configuration file uses the 00860 # same syntax as the above configuration files but is completely 00861 # optional. The second configuration file is the test script, which is 00862 # encoded using the YAML serialization language (see 00863 # http://www.yaml.org/ for more information on YAML). The YAML script 00864 # is not optional, as it describes the test layout. testbed is designed 00865 # to support running a fairly wide set of test configurations as canned 00866 # scripts without writing any new control code. The intent is to make 00867 # it possible to write meaningful regression tests. 00868 # 00869 # All of the options in in the first (optional) configuration file are 00870 # just overrides for wired-in default values. In most cases the 00871 # defaults will suffice, and the set of options is still in flux, so 00872 # only a few of the options are described here. The default name for 00873 # this configuration file is testbed.conf, run testbed with "-c 00874 # filename" to change it. 00875 # 00876 # testbed.conf options: 00877 # 00878 # @li @c testbed_dir: 00879 # Working directory into which testbed should write the 00880 # (many) files it generates. Default is "testbed.dir". 00881 # 00882 # @li @c irdb_db_pass: 00883 # MySQL password for the "irdb" user. Default is 00884 # "fnord". You may want to override this. 00885 # 00886 # @li @c rpki_db_pass: 00887 # MySQL password for the "rpki" user. Default is 00888 # "fnord". You may want to override this. 00889 # 00890 # @li @c rootd_sia: 00891 # rsync URI naming a (perhaps fictious) directory to use 00892 # as the id-ad-caRepository SIA value in the generated 00893 # root resource certificate. Default is 00894 # "rsync://wombat.invalid/". You may want to override 00895 # this if you intend to run an rsync server and test 00896 # against the generated results using rcynic. This 00897 # default will likely change if and when testbed learns 00898 # how to run rcynic itself as part of the test suite. 00899 # 00900 # The second configuration file is named testbed.yaml by default, run 00901 # testbed with "-y filename" to change it. The YAML file contains 00902 # multiple YAML "documents". The first document describes the initial 00903 # test layout and resource allocations, subsequent documents describe 00904 # modifications to the initial allocations and other parameters. 00905 # Resources listed in the initial layout are aggregated automatically, 00906 # so that a node in the resource hierarchy automatically receives the 00907 # resources it needs to issue whatever its children are listed as 00908 # holding. Actions in the subsequent documents are modifications to the 00909 # current resource set, modifications to validity dates or other 00910 # non-resource parameters, or special commands like "sleep". The 00911 # details are still evolving, but here's an example of current usage: 00912 # 00913 # @verbatim 00914 # name: RIR 00915 # valid_for: 2d 00916 # sia_base: "rsync://wombat.invalid/" 00917 # kids: 00918 # - name: LIR0 00919 # kids: 00920 # - name: Alice 00921 # ipv4: 192.0.2.1-192.0.2.33 00922 # asn: 64533 00923 # --- 00924 # - name: Alice 00925 # valid_add: 10 00926 # --- 00927 # - name: Alice 00928 # add_as: 33 00929 # valid_add: 2d 00930 # --- 00931 # - name: Alice 00932 # valid_sub: 2d 00933 # --- 00934 # - name: Alice 00935 # valid_for: 10d 00936 # @endverbatim 00937 # 00938 # This specifies an initial layout consisting of an RPKI engine named 00939 # "RIR", with one child "LIR0", which in turn has one child "Alice". 00940 # Alice has a set of assigned resources, and all resources in the system 00941 # are initially set to be valid for two days from the time at which the 00942 # test is started. The first subsequent document adds ten seconds to 00943 # the validity interval for Alice's resources and makes no other 00944 # modifications. The second subsequent document grants Alice additional 00945 # resources and adds another two days to the validity interval for 00946 # Alice's resources. The next document subtracts two days from the 00947 # validity interval for Alice's resources. The final document sets the 00948 # validity interval for Alice's resources to ten days. 00949 # 00950 # Operators in subsequent (update) documents: 00951 # 00952 # @li @c add_as, @c add_v4, @c add_v6: 00953 # These add ASN, IPv4, or IPv6 resources, respectively. 00954 # 00955 # @li @c sub_as, @c sub_v4, @c sub_v6: 00956 # These subtract resources. 00957 # 00958 # @li @c valid_until: 00959 # Set an absolute expiration date. 00960 # 00961 # @li @c valid_for: 00962 # Set a relative expiration date. 00963 # 00964 # @li @c valid_add, @c valid_sub: 00965 # Add to or subtract from validity interval. 00966 # 00967 # @li @c sleep [interval]: 00968 # Sleep for specified interval, or until testbed receives a SIGALRM signal. 00969 # 00970 # Absolute timestamps should be in the form shown (UTC timestamp format 00971 # as used in XML). 00972 # 00973 # Intervals (@c valid_add, @c valid_sub, @c valid_for, @c sleep) are either 00974 # integers, in which case they're interpreted as seconds, or are a 00975 # string of the form "wD xH yM zS" where w, x, y, and z are integers and 00976 # D, H, M, and S indicate days, hours, minutes, and seconds. In the 00977 # latter case all of the fields are optional, but at least one must be 00978 # specified. For example, "3D4H" means "three days plus four hours". 00979 # 00980 # 00981 # @section testpoke testpoke.py 00982 # 00983 # This is a command-line client for the up-down protocol. Unlike all of 00984 # the above programs, testpoke does not accept a %config file in 00985 # OpenSSL-compatable format at all. Instead, it is configured 00986 # exclusively by a YAML script. testpoke's design was constrained by a 00987 # desire to have it be compatable with APNIC's rpki_poke.pl tool, so 00988 # that the two tools could use a common configuration language to 00989 # simplify scripted testing. There are minor variations due to slightly 00990 # different feature sets, but YAML files intended for one program will 00991 # usually work with the other. 00992 # 00993 # README for APNIC's tool describing the input language can be found at 00994 # <a href="http://mirin.apnic.net/svn/rpki_engine/branches/gary-poker/client/poke/README"> 00995 # http://mirin.apnic.net/svn/rpki_engine/branches/gary-poker/client/poke/README</a>. 00996 # 00997 # testpoke.py takes a simplified command line and uses only one YAML 00998 # input file. 00999 # 01000 # @verbatim 01001 # Usage: python testpoke.py [ { -y | --yaml } configfile ] 01002 # [ { -r | --request } requestname ] 01003 # [ { -h | --help } ] 01004 # @endverbatim 01005 # 01006 # Default configuration file is testpoke.yaml, override with --yaml 01007 # option. 01008 # 01009 # The --request option specifies the specific command within the YAML 01010 # file to execute. 01011 # 01012 # Sample configuration file: 01013 # 01014 # @verbatim 01015 # --- 01016 # # Sample YAML configuration file for testpoke.py 01017 # 01018 # version: 1 01019 # posturl: https://localhost:4433/up-down/1 01020 # recipient-id: wombat 01021 # sender-id: "1" 01022 # 01023 # cms-cert-file: biz-certs/Frank-EE.cer 01024 # cms-key-file: biz-certs/Frank-EE.key 01025 # cms-ca-cert-file: biz-certs/Bob-Root.cer 01026 # cms-cert-chain-file: [ biz-certs/Frank-CA.cer ] 01027 # 01028 # ssl-cert-file: biz-certs/Frank-EE.cer 01029 # ssl-key-file: biz-certs/Frank-EE.key 01030 # ssl-ca-cert-file: biz-certs/Bob-Root.cer 01031 # 01032 # requests: 01033 # list: 01034 # type: list 01035 # issue: 01036 # type: issue 01037 # class: 1 01038 # sia: [ "rsync://bandicoot.invalid/some/where/" ] 01039 # revoke: 01040 # type: revoke 01041 # class: 1 01042 # ski: "CB5K6APY-4KcGAW9jaK_cVPXKX0" 01043 # @endverbatim 01044 # 01045 # testpoke adds one extension to the language described in APNIC's 01046 # README: the cms-cert-chain-* and ssl-cert-chain-* options, which allow 01047 # one to specify a chain of intermediate certificates to be presented in 01048 # the CMS or TLS protocol. APNIC's initial implementation required 01049 # direct knowledge of the issuing certificate (ie, it supported a 01050 # maximum chain length of one); subsequent APNIC code changes have 01051 # probably relaxed this restriction, and with luck APNIC has copied 01052 # testpoke's syntax to express chains of intermediate certificates. 01053 01054 ## @page Left-right Left-right protocol 01055 # 01056 # The left-right protocol is really two separate client/server 01057 # protocols over separate channels between the RPKI engine and the IR 01058 # back end (IRBE). The IRBE is the client for one of the 01059 # subprotocols, the RPKI engine is the client for the other. 01060 # 01061 # @section Terminology 01062 # 01063 # @li @em IRBE: Internet Registry Back End 01064 # 01065 # @li @em IRDB: Internet Registry Data Base 01066 # 01067 # @li @em BPKI: Business PKI 01068 # 01069 # @li @em RPKI: Resource PKI 01070 # 01071 # @section Operations initiated by the IRBE 01072 # 01073 # This part of the protcol uses a kind of message-passing. Each %object 01074 # that the RPKI engine knows about takes five messages: "create", "set", 01075 # "get", "list", and "destroy". Actions which are not just data 01076 # operations on %objects are handled via an SNMP-like mechanism, as if 01077 # they were fields to be set. For example, to generate a keypair one 01078 # "sets" the "generate-keypair" field of a BSC %object, even though there 01079 # is no such field in the %object itself as stored in SQL. This is a bit 01080 # of a kludge, but the reason for doing it as if these were variables 01081 # being set is to allow composite operations such as creating a BSC, 01082 # populating all of its data fields, and generating a keypair, all as a 01083 # single operation. With this model, that's trivial, otherwise it's at 01084 # least two round trips. 01085 # 01086 # Fields can be set in either "create" or "set" operations, the 01087 # difference just being whether the %object already exists. A "get" 01088 # operation returns all visible fields of the %object. A "list" 01089 # operation returns a %list containing what "get" would have returned on 01090 # each of those %objects. 01091 # 01092 # Left-right protocol %objects are encoded as signed CMS messages 01093 # containing XML as eContent and using an eContentType OID of @c id-ct-xml 01094 # (1.2.840.113549.1.9.16.1.28). These CMS messages are in turn passed 01095 # as the data for HTTPS POST operations, with an HTTP content type of 01096 # "application/x-rpki" for both the POST data and the response data. 01097 # 01098 # All operations allow an optional "tag" attribute which can be any 01099 # alphanumeric token. The main purpose of the tag attribute is to allow 01100 # batching of multiple requests into a single PDU. 01101 # 01102 # @subsection self_obj <self/> object 01103 # 01104 # A @c <self/> %object represents one virtual RPKI engine. In simple cases 01105 # where the RPKI engine operator operates the engine only on their own 01106 # behalf, there will only be one @c <self/> %object, representing the engine 01107 # operator's organization, but in environments where the engine operator 01108 # hosts other entities, there will be one @c @c <self/> %object per hosted 01109 # entity (probably including the engine operator's own organization, 01110 # considered as a hosted customer of itself). 01111 # 01112 # Some of the RPKI engine's configured parameters and data are shared by 01113 # all hosted entities, but most are tied to a specific @c <self/> %object. 01114 # Data which are shared by all hosted entities are referred to as 01115 # "per-engine" data, data which are specific to a particular @c <self/> 01116 # %object are "per-self" data. 01117 # 01118 # Since all other RPKI engine %objects refer to a @c <self/> %object via a 01119 # "self_handle" value, one must create a @c <self/> %object before one can 01120 # usefully configure any other left-right protocol %objects. 01121 # 01122 # Every @c <self/> %object has a self_handle attribute, which must be specified 01123 # for the "create", "set", "get", and "destroy" actions. 01124 # 01125 # Payload data which can be configured in a @c <self/> %object: 01126 # 01127 # @li @c use_hsm (attribute): 01128 # Whether to use a Hardware Signing Module. At present this option 01129 # has no effect, as the implementation does not yet support HSMs. 01130 # 01131 # @li @c crl_interval (attribute): 01132 # Positive integer representing the planned lifetime of an RPKI CRL 01133 # for this @c <self/>, measured in seconds. 01134 # 01135 # @li @c regen_margin (attribute): 01136 # Positive integer representing how long before expiration of an 01137 # RPKI certificiate a new one should be generated, measured in 01138 # seconds. At present this only affects the one-off EE certificates 01139 # associated with ROAs. 01140 # 01141 # @li @c bpki_cert (element): 01142 # BPKI CA certificate for this @c <self/>. This is used as part of the 01143 # certificate chain when validating incoming TLS and CMS messages, 01144 # and should be the issuer of cross-certification BPKI certificates 01145 # used in @c <repository/>, @c <parent/>, and @c <child/> %objects. If the 01146 # bpki_glue certificate is in use (below), the bpki_cert certificate 01147 # should be issued by the bpki_glue certificate; otherwise, the 01148 # bpki_cert certificate should be issued by the per-engine bpki_ta 01149 # certificate. 01150 # 01151 # @li @c bpki_glue (element): 01152 # Another BPKI CA certificate for this @c <self/>, usually not needed. 01153 # Certain pathological cross-certification cases require a 01154 # two-certificate chain due to issuer name conflicts. If used, the 01155 # bpki_glue certificate should be the issuer of the bpki_cert 01156 # certificate and should be issued by the per-engine bpki_ta 01157 # certificate; if not needed, the bpki_glue certificate should be 01158 # left unset. 01159 # 01160 # Control attributes that can be set to "yes" to force actions: 01161 # 01162 # @li @c rekey: 01163 # Start a key rollover for every RPKI CA associated with every 01164 # @c <parent/> %object associated with this @c <self/> %object. This is the 01165 # first phase of a key rollover operation. 01166 # 01167 # @li @c revoke: 01168 # Revoke any remaining certificates for any expired key associated 01169 # with any RPKI CA for any @c <parent/> %object associated with this 01170 # @c <self/> %object. This is the second (cleanup) phase for a key 01171 # rollover operation; it's separate from the first phase to leave 01172 # time for new RPKI certificates to propegate and be installed. 01173 # 01174 # @li @c reissue: 01175 # Not implemented, may be removed from protocol. Original theory 01176 # was that this operation would force reissuance of any %object with 01177 # a changed key, but as that happens automatically as part of the 01178 # key rollover mechanism this operation seems unnecessary. 01179 # 01180 # @li @c run_now: 01181 # Force immediate processing for all tasks associated with this 01182 # @c <self/> %object that would ordinarily be performed under cron. Not 01183 # currently implemented. 01184 # 01185 # @li @c publish_world_now: 01186 # Force (re)publication of every publishable %object for this @c <self/> 01187 # %object. Not currently implemented. Intended to aid in recovery 01188 # if RPKI engine and publication engine somehow get out of sync. 01189 # 01190 # 01191 # @subsection bsc_obj <bsc/> object 01192 # 01193 # The @c <bsc/> ("business signing context") %object represents all the BPKI 01194 # data needed to sign outgoing CMS or HTTPS messages. Various other 01195 # %objects include pointers to a @c <bsc/> %object. Whether a particular 01196 # @c <self/> uses only one @c <bsc/> or multiple is a configuration decision 01197 # based on external requirements: the RPKI engine code doesn't care, it 01198 # just cares that, for any %object representing a relationship for which 01199 # it must sign messages, there be a @c <bsc/> %object that it can use to 01200 # produce that signature. 01201 # 01202 # Every @c <bsc/> %object has a bsc_handle, which must be specified for the 01203 # "create", "get", "set", and "destroy" actions. Every @c <bsc/> also has a self_handle 01204 # attribute which indicates the @c <self/> %object with which this @c <bsc/> 01205 # %object is associated. 01206 # 01207 # Payload data which can be configured in a @c <isc/> %object: 01208 # 01209 # @li @c signing_cert (element): 01210 # BPKI certificate to use when generating a signature. 01211 # 01212 # @li @c signing_cert_crl (element): 01213 # CRL which would %list signing_cert if it had been revoked. 01214 # 01215 # Control attributes that can be set to "yes" to force actions: 01216 # 01217 # @li @c generate_keypair: 01218 # Generate a new BPKI keypair and return a PKCS #10 certificate 01219 # request. The resulting certificate, once issued, should be 01220 # configured as this @c <bsc/> %object's signing_cert. 01221 # 01222 # Additional attributes which may be specified when specifying 01223 # "generate_keypair": 01224 # 01225 # @li @c key_type: 01226 # Type of BPKI keypair to generate. "rsa" is both the default and, 01227 # at the moment, the only allowed value. 01228 # 01229 # @li @c hash_alg: 01230 # Cryptographic hash algorithm to use with this keypair. "sha256" 01231 # is both the default and, at the moment, the only allowed value. 01232 # 01233 # @li @c key_length: 01234 # Length in bits of the keypair to be generated. "2048" is both the 01235 # default and, at the moment, the only allowed value. 01236 # 01237 # Replies to "create" and "set" actions that specify "generate-keypair" 01238 # include a <bsc_pkcs10/> element, as do replies to "get" and "list" 01239 # actions for a @c <bsc/> %object for which a "generate-keypair" command has 01240 # been issued. The RPKI engine stores the PKCS #10 request, which 01241 # allows the IRBE to reuse the request if and when it needs to reissue 01242 # the corresponding BPKI signing certificate. 01243 # 01244 # @subsection parent_obj <parent/> object 01245 # 01246 # The @c <parent/> %object represents the RPKI engine's view of a particular 01247 # parent of the current @c <self/> %object in the up-down protocol. Due to 01248 # the way that the resource hierarchy works, a given @c <self/> may obtain 01249 # resources from multiple parents, but it will always have at least one; 01250 # in the case of IANA or an RIR, the parent RPKI engine may be a trivial 01251 # stub. 01252 # 01253 # Every @c <parent/> %object has a parent_handle, which must be specified for 01254 # the "create", "get", "set", and "destroy" actions. Every @c <parent/> also has a 01255 # self_handle attribute which indicates the @c <self/> %object with which this 01256 # @c <parent/> %object is associated, a bsc_handle attribute indicating the @c <bsc/> 01257 # %object to be used when signing messages sent to this parent, and a 01258 # repository_handle indicating the @c <repository/> %object to be used when 01259 # publishing issued by the certificate issued by this parent. 01260 # 01261 # Payload data which can be configured in a @c <parent/> %object: 01262 # 01263 # @li @c peer_contact_uri (attribute): 01264 # HTTPS URI used to contact this parent. 01265 # 01266 # @li @c sia_base (attribute): 01267 # The leading portion of an rsync URI that the RPKI engine should 01268 # use when composing the publication URI for %objects issued by the 01269 # RPKI certificate issued by this parent. 01270 # 01271 # @li @c sender_name (attribute): 01272 # Sender name to use in the up-down protocol when talking to this 01273 # parent. The RPKI engine doesn't really care what this value is, 01274 # but other implementations of the up-down protocol do care. 01275 # 01276 # @li @c recipient_name (attribute): 01277 # Recipient name to use in the up-down protocol when talking to this 01278 # parent. The RPKI engine doesn't really care what this value is, 01279 # but other implementations of the up-down protocol do care. 01280 # 01281 # @li @c bpki_cms_cert (element): 01282 # BPKI CMS CA certificate for this @c <parent/>. This is used as part 01283 # of the certificate chain when validating incoming CMS messages If 01284 # the bpki_cms_glue certificate is in use (below), the bpki_cms_cert 01285 # certificate should be issued by the bpki_cms_glue certificate; 01286 # otherwise, the bpki_cms_cert certificate should be issued by the 01287 # bpki_cert certificate in the @c <self/> %object. 01288 # 01289 # @li @c bpki_cms_glue (element): 01290 # Another BPKI CMS CA certificate for this @c <parent/>, usually not 01291 # needed. Certain pathological cross-certification cases require a 01292 # two-certificate chain due to issuer name conflicts. If used, the 01293 # bpki_cms_glue certificate should be the issuer of the 01294 # bpki_cms_cert certificate and should be issued by the bpki_cert 01295 # certificate in the @c <self/> %object; if not needed, the 01296 # bpki_cms_glue certificate should be left unset. 01297 # 01298 # @li @c bpki_https_cert (element): 01299 # BPKI HTTPS CA certificate for this @c <parent/>. This is like the 01300 # bpki_cms_cert %object, only used for validating incoming TLS 01301 # messages rather than CMS. 01302 # 01303 # @li @c bpki_cms_glue (element): 01304 # Another BPKI HTTPS CA certificate for this @c <parent/>, usually not 01305 # needed. This is like the bpki_cms_glue certificate, only used for 01306 # validating incoming TLS messages rather than CMS. 01307 # 01308 # Control attributes that can be set to "yes" to force actions: 01309 # 01310 # @li @c rekey: 01311 # This is like the rekey command in the @c <self/> %object, but limited 01312 # to RPKI CAs under this parent. 01313 # 01314 # @li @c reissue: 01315 # This is like the reissue command in the @c <self/> %object, but limited 01316 # to RPKI CAs under this parent. 01317 # 01318 # @li @c revoke: 01319 # This is like the revoke command in the @c <self/> %object, but limited 01320 # to RPKI CAs under this parent. 01321 # 01322 # @subsection child_obj <child/> object 01323 # 01324 # The @c <child/> %object represents the RPKI engine's view of particular 01325 # child of the current @c <self/> in the up-down protocol. 01326 # 01327 # Every @c <child/> %object has a child_handle, which must be specified for the 01328 # "create", "get", "set", and "destroy" actions. Every @c <child/> also has a 01329 # self_handle attribute which indicates the @c <self/> %object with which this 01330 # @c <child/> %object is associated. 01331 # 01332 # Payload data which can be configured in a @c <child/> %object: 01333 # 01334 # @li @c bpki_cert (element): 01335 # BPKI CA certificate for this @c <child/>. This is used as part of 01336 # the certificate chain when validating incoming TLS and CMS 01337 # messages. If the bpki_glue certificate is in use (below), the 01338 # bpki_cert certificate should be issued by the bpki_glue 01339 # certificate; otherwise, the bpki_cert certificate should be issued 01340 # by the bpki_cert certificate in the @c <self/> %object. 01341 # 01342 # @li @c bpki_glue (element): 01343 # Another BPKI CA certificate for this @c <child/>, usually not needed. 01344 # Certain pathological cross-certification cases require a 01345 # two-certificate chain due to issuer name conflicts. If used, the 01346 # bpki_glue certificate should be the issuer of the bpki_cert 01347 # certificate and should be issued by the bpki_cert certificate in 01348 # the @c <self/> %object; if not needed, the bpki_glue certificate 01349 # should be left unset. 01350 # 01351 # Control attributes that can be set to "yes" to force actions: 01352 # 01353 # @li @c reissue: 01354 # Not implemented, may be removed from protocol. 01355 # 01356 # @subsection repository_obj <repository/> object 01357 # 01358 # The @c <repository/> %object represents the RPKI engine's view of a 01359 # particular publication repository used by the current @c <self/> %object. 01360 # 01361 # Every @c <repository/> %object has a repository_handle, which must be 01362 # specified for the "create", "get", "set", and "destroy" actions. Every 01363 # @c <repository/> also has a self_handle attribute which indicates the @c <self/> 01364 # %object with which this @c <repository/> %object is associated. 01365 # 01366 # Payload data which can be configured in a @c <repository/> %object: 01367 # 01368 # @li @c peer_contact_uri (attribute): 01369 # HTTPS URI used to contact this repository. 01370 # 01371 # @li @c bpki_cms_cert (element): 01372 # BPKI CMS CA certificate for this @c <repository/>. This is used as part 01373 # of the certificate chain when validating incoming CMS messages If 01374 # the bpki_cms_glue certificate is in use (below), the bpki_cms_cert 01375 # certificate should be issued by the bpki_cms_glue certificate; 01376 # otherwise, the bpki_cms_cert certificate should be issued by the 01377 # bpki_cert certificate in the @c <self/> %object. 01378 # 01379 # @li @c bpki_cms_glue (element): 01380 # Another BPKI CMS CA certificate for this @c <repository/>, usually not 01381 # needed. Certain pathological cross-certification cases require a 01382 # two-certificate chain due to issuer name conflicts. If used, the 01383 # bpki_cms_glue certificate should be the issuer of the 01384 # bpki_cms_cert certificate and should be issued by the bpki_cert 01385 # certificate in the @c <self/> %object; if not needed, the 01386 # bpki_cms_glue certificate should be left unset. 01387 # 01388 # @li @c bpki_https_cert (element): 01389 # BPKI HTTPS CA certificate for this @c <repository/>. This is like the 01390 # bpki_cms_cert %object, only used for validating incoming TLS 01391 # messages rather than CMS. 01392 # 01393 # @li @c bpki_cms_glue (element): 01394 # Another BPKI HTTPS CA certificate for this @c <repository/>, usually not 01395 # needed. This is like the bpki_cms_glue certificate, only used for 01396 # validating incoming TLS messages rather than CMS. 01397 # 01398 # At present there are no control attributes for @c <repository/> %objects. 01399 # 01400 # @subsection route_origin_obj <route_origin/> object 01401 # 01402 # This section is out-of-date. The @c <route_origin/> %object 01403 # has been replaced by the @c <list_roa_requests/> IRDB query, 01404 # but the documentation for that hasn't been written yet. 01405 # 01406 # The @c <route_origin/> %object is a kind of prototype for a ROA. It 01407 # contains all the information needed to generate a ROA once the RPKI 01408 # engine obtains the appropriate RPKI certificates from its parent(s). 01409 # 01410 # Note that a @c <route_origin/> %object represents a ROA to be generated on 01411 # behalf of @c <self/>, not on behalf of a @c <child/>. Thus, a hosted entity 01412 # that has no children but which does need to generate ROAs would be 01413 # represented by a hosted @c <self/> with no @c <child/> %objects but one or 01414 # more @c <route_origin/> %objects. While lumping ROA generation in with 01415 # the other RPKI engine activities may seem a little odd at first, it's 01416 # a natural consequence of the design requirement that the RPKI daemon 01417 # never transmit private keys across the network in any form; given this 01418 # requirement, the RPKI engine that holds the private keys for an RPKI 01419 # certificate must also be the engine which generates any ROAs that 01420 # derive from that RPKI certificate. 01421 # 01422 # The precise content of the @c <route_origin/> has changed over time as 01423 # the underlying ROA specification has changed. The current 01424 # implementation as of this writing matches what we expect to see in 01425 # draft-ietf-sidr-roa-format-03, once it is issued. In particular, note 01426 # that the exactMatch boolean from the -02 draft has been replaced by 01427 # the prefix and maxLength encoding used in the -03 draft. 01428 # 01429 # Payload data which can be configured in a @c <route_origin/> %object: 01430 # 01431 # @li @c asn (attribute): 01432 # Autonomous System Number (ASN) to place in the generated ROA. A 01433 # single ROA can only grant authorization to a single ASN; multiple 01434 # ASNs require multiple ROAs, thus multiple @c <route_origin/> %objects. 01435 # 01436 # @li @c ipv4 (attribute): 01437 # %List of IPv4 prefix and maxLength values, see below for format. 01438 # 01439 # @li @c ipv6 (attribute): 01440 # %List of IPv6 prefix and maxLength values, see below for format. 01441 # 01442 # Control attributes that can be set to "yes" to force actions: 01443 # 01444 # @li @c suppress_publication: 01445 # Not implemented, may be removed from protocol. 01446 # 01447 # The lists of IPv4 and IPv6 prefix and maxLength values are represented 01448 # as comma-separated text strings, with no whitespace permitted. Each 01449 # entry in such a string represents a single prefix/maxLength pair. 01450 # 01451 # ABNF for these address lists: 01452 # 01453 # @verbatim 01454 # 01455 # <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ] 01456 # ; Where <max_prefixlen> defaults to the same 01457 # ; value as <prefixlen>. 01458 # 01459 # <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> ) 01460 # 01461 # @endverbatim 01462 # 01463 # For example, @c "10.0.1.0/24-32,10.0.2.0/24", which is a shorthand 01464 # form of @c "10.0.1.0/24-32,10.0.2.0/24-24". 01465 # 01466 # @section irdb_queries Operations initiated by the RPKI engine 01467 # 01468 # The left-right protocol also includes queries from the RPKI engine 01469 # back to the IRDB. These queries do not follow the message-passing 01470 # pattern used in the IRBE-initiated part of the protocol. Instead, 01471 # there's a single query back to the IRDB, with a corresponding 01472 # response. The CMS and HTTPS encoding are the same as in the rest of 01473 # the protocol, but the BPKI certificates will be different as the 01474 # back-queries and responses form a separate communication channel. 01475 # 01476 # @subsection list_resources_msg <list_resources/> messages 01477 # 01478 # The @c <list_resources/> query and response allow the RPKI engine to ask 01479 # the IRDB for information about resources assigned to a particular 01480 # child. The query must include both a @c "self_handle" attribute naming 01481 # the @c <self/> that is making the request and also a @c "child_handle" 01482 # attribute naming the child that is the subject of the query. The 01483 # query and response also allow an optional @c "tag" attribute of the 01484 # same form used elsewhere in this protocol, to allow batching. 01485 # 01486 # A @c <list_resources/> response includes the following attributes, along 01487 # with the @c tag (if specified), @c self_handle, and @c child_handle copied 01488 # from the request: 01489 # 01490 # @li @c valid_until: 01491 # A timestamp indicating the date and time at which certificates 01492 # generated by the RPKI engine for these data should expire. The 01493 # timestamp is expressed as an XML @c xsd:dateTime, must be 01494 # expressed in UTC, and must carry the "Z" suffix indicating UTC. 01495 # 01496 # @li @c asn: 01497 # A %list of autonomous sequence numbers, expressed as a 01498 # comma-separated sequence of decimal integers with no whitespace. 01499 # 01500 # @li @c ipv4: 01501 # A %list of IPv4 address prefixes and ranges, expressed as a 01502 # comma-separated %list of prefixes and ranges with no whitespace. 01503 # See below for format details. 01504 # 01505 # @li @c ipv6: 01506 # A %list of IPv6 address prefixes and ranges, expressed as a 01507 # comma-separated %list of prefixes and ranges with no whitespace. 01508 # See below for format details. 01509 # 01510 # Entries in a %list of address prefixes and ranges can be either 01511 # prefixes, which are written in the usual address/prefixlen notation, 01512 # or ranges, which are expressed as a pair of addresses denoting the 01513 # beginning and end of the range, written in ascending order separated 01514 # by a single "-" character. This format is superficially similar to 01515 # the format used for prefix and maxLength values in the @c <route_origin/> 01516 # %object, but the semantics differ: note in particular that 01517 # @c <route_origin/> %objects don't allow ranges, while @c <list_resources/> 01518 # messages don't allow a maxLength specification. 01519 # 01520 # @section left_right_error_handling Error handling 01521 # 01522 # Error in this protocol are handled at two levels. 01523 # 01524 # Since all messages in this protocol are conveyed over HTTPS 01525 # connections, basic errors are indicated via the HTTP response code. 01526 # 4xx and 5xx responses indicate that something bad happened. Errors 01527 # that make it impossible to decode a query or encode a response are 01528 # handled in this way. 01529 # 01530 # Where possible, errors will result in a @c <report_error/> message which 01531 # takes the place of the expected protocol response message. 01532 # @c <report_error/> messages are CMS-signed XML messages like the rest of 01533 # this protocol, and thus can be archived to provide an audit trail. 01534 # 01535 # @c <report_error/> messages only appear in replies, never in queries. 01536 # The @c <report_error/> message can appear on either the "forward" (IRBE 01537 # as client of RPKI engine) or "back" (RPKI engine as client of IRDB) 01538 # communication channel. 01539 # 01540 # The @c <report_error/> message includes an optional @c "tag" attribute to 01541 # assist in matching the error with a particular query when using 01542 # batching, and also includes a @c "self_handle" attribute indicating the 01543 # @c <self/> that issued the error. 01544 # 01545 # The error itself is conveyed in the @c error_code (attribute). The 01546 # value of this attribute is a token indicating the specific error that 01547 # occurred. At present this will be the name of a Python exception; the 01548 # production version of this protocol will nail down the allowed error 01549 # tokens here, probably in the RelaxNG schema. 01550 # 01551 # The body of the @c <report_error/> element itself is an optional text 01552 # string; if present, this is debugging information. At present this 01553 # capabilty is not used, debugging information goes to syslog. 01554 01555 ## @page Publication Publication protocol 01556 # 01557 # The %publication protocol is really two separate client/server 01558 # protocols, between different parties. The first is a configuration 01559 # protocol for an IRBE to use to configure a %publication engine, 01560 # the second is the interface by which authorized clients request 01561 # %publication of specific objects. 01562 # 01563 # Much of the architecture of the %publication protocol is borrowed 01564 # from the @link Left-right left-right protocol: @endlink like the 01565 # left-right protocol, the %publication protocol uses CMS-wrapped XML 01566 # over HTTPS with the same eContentType OID and the same HTTPS 01567 # content-type, and the overall style of the XML messages is very 01568 # similar to the left-right protocol. All operations allow an 01569 # optional "tag" attribute to allow batching. 01570 # 01571 # The %publication engine operates a single HTTPS server which serves 01572 # both of these subprotocols. The two subprotocols share a single 01573 # server port, but use distinct URLs to allow demultiplexing. 01574 # 01575 # @section Terminology 01576 # 01577 # @li @em IRBE: Internet Registry Back End 01578 # 01579 # @li @em IRDB: Internet Registry Data Base 01580 # 01581 # @li @em BPKI: Business PKI 01582 # 01583 # @li @em RPKI: Resource PKI 01584 # 01585 # @section Publication-control Publication control subprotocol 01586 # 01587 # The control subprotocol reuses the message-passing design of the 01588 # left-right protocol. Configured objects support the "create", "set", 01589 # "get", "list", and "destroy" actions, or a subset thereof when the 01590 # full set of actions doesn't make sense. 01591 # 01592 # @subsection config_obj <config/> object 01593 # 01594 # The <config/> %object allows configuration of data that apply to the 01595 # entire %publication server rather than a particular client. 01596 # 01597 # There is exactly one <config/> %object in the %publication server, and 01598 # it only supports the "set" and "get" actions -- it cannot be created 01599 # or destroyed. 01600 # 01601 # Payload data which can be configured in a <config/> %object: 01602 # 01603 # @li @c bpki_crl (element): 01604 # This is the BPKI CRL used by the %publication server when 01605 # signing the CMS wrapper on responses in the %publication 01606 # subprotocol. As the CRL must be updated at regular intervals, 01607 # it's not practical to restart the %publication server when the 01608 # BPKI CRL needs to be updated. The BPKI model doesn't require 01609 # use of a BPKI CRL between the IRBE and the %publication server, 01610 # so we can use the %publication control subprotocol to update the 01611 # BPKI CRL. 01612 # 01613 # @subsection client_obj <client/> object 01614 # 01615 # The <client/> %object represents one client authorized to use the 01616 # %publication server. 01617 # 01618 # The <client/> %object supports the full set of "create", "set", "get", 01619 # "list", and "destroy" actions. Each client has a "client_handle" 01620 # attribute, which is used in responses and must be specified in "create", "set", 01621 # "get", or "destroy" actions. 01622 # 01623 # Payload data which can be configured in a <client/> %object: 01624 # 01625 # @li @c base_uri (attribute): 01626 # This is the base URI below which this client is allowed to publish 01627 # data. The %publication server may impose additional constraints in 01628 # the case of a child publishing beneath its parent. 01629 # 01630 # @li @c bpki_cert (element): 01631 # BPKI CA certificate for this <client/>. This is used as part of 01632 # the certificate chain when validating incoming TLS and CMS 01633 # messages. If the bpki_glue certificate is in use (below), the 01634 # bpki_cert certificate should be issued by the bpki_glue 01635 # certificate; otherwise, the bpki_cert certificate should be issued 01636 # by the %publication engine's bpki_ta certificate. 01637 # 01638 # @li @c bpki_glue (element): 01639 # Another BPKI CA certificate for this <client/>, usually not 01640 # needed. Certain pathological cross-certification cases require a 01641 # two-certificate chain due to issuer name conflicts. If used, the 01642 # bpki_glue certificate should be the issuer of the bpki_cert 01643 # certificate and should be issued by the %publication engine's 01644 # bpki_ta certificate; if not needed, the bpki_glue certificate 01645 # should be left unset. 01646 # 01647 # @section Publication-publication Publication subprotocol 01648 # 01649 # The %publication subprotocol is structured somewhat differently from 01650 # the %publication control protocol. Objects in the %publication 01651 # subprotocol represent objects to be published or objects to be 01652 # withdrawn from %publication. Each kind of %object supports two actions: 01653 # "publish" and "withdraw". In each case the XML element representing 01654 # hte %object to be published or withdrawn has a "uri" attribute which 01655 # contains the %publication URI. For "publish" actions, the XML element 01656 # body contains the DER %object to be published, encoded in Base64; for 01657 # "withdraw" actions, the XML element body is empty. 01658 # 01659 # In theory, the detailed access control for each kind of %object might 01660 # be different. In practice, as of this writing, access control for all 01661 # objects is a simple check that the client's @c "base_uri" is a leading 01662 # substring of the %publication URI. Details of why access control might 01663 # need to become more complicated are discussed in a later section. 01664 # 01665 # @subsection certificate_obj <certificate/> object 01666 # 01667 # The <certificate/> %object represents an RPKI certificate to be 01668 # published or withdrawn. 01669 # 01670 # @subsection crl_obj <crl/> object 01671 # 01672 # The <crl/> %object represents an RPKI CRL to be published or withdrawn. 01673 # 01674 # @subsection manifest_obj <manifest/> object 01675 # 01676 # The <manifest/> %object represents an RPKI %publication %manifest to be 01677 # published or withdrawn. 01678 # 01679 # Note that part of the reason for the batching support in the 01680 # %publication protocol is because @em every %publication or withdrawal 01681 # action requires a new %manifest, thus every %publication or withdrawal 01682 # action will involve at least two objects. 01683 # 01684 # @subsection roa_obj <roa/> object 01685 # 01686 # The <roa/> %object represents a ROA to be published or withdrawn. 01687 # 01688 # @section publication_error_handling Error handling 01689 # 01690 # Error in this protocol are handled at two levels. 01691 # 01692 # Since all messages in this protocol are conveyed over HTTPS 01693 # connections, basic errors are indicated via the HTTP response code. 01694 # 4xx and 5xx responses indicate that something bad happened. Errors 01695 # that make it impossible to decode a query or encode a response are 01696 # handled in this way. 01697 # 01698 # Where possible, errors will result in a <report_error/> message which 01699 # takes the place of the expected protocol response message. 01700 # <report_error/> messages are CMS-signed XML messages like the rest of 01701 # this protocol, and thus can be archived to provide an audit trail. 01702 # 01703 # <report_error/> messages only appear in replies, never in 01704 # queries. The <report_error/> message can appear in both the 01705 # control and publication subprotocols. 01706 # 01707 # The <report_error/> message includes an optional @c "tag" attribute to 01708 # assist in matching the error with a particular query when using 01709 # batching. 01710 # 01711 # The error itself is conveyed in the @c error_code (attribute). The 01712 # value of this attribute is a token indicating the specific error that 01713 # occurred. At present this will be the name of a Python exception; the 01714 # production version of this protocol will nail down the allowed error 01715 # tokens here, probably in the RelaxNG schema. 01716 # 01717 # The body of the <report_error/> element itself is an optional text 01718 # string; if present, this is debugging information. At present this 01719 # capabilty is not used, debugging information goes to syslog. 01720 # 01721 # @section publication_access_control Additional access control considerations. 01722 # 01723 # As detailed above, the %publication protocol is trivially simple. This 01724 # glosses over two bits of potential complexity: 01725 # 01726 # @li In the case where parent and child are sharing a repository, we'd 01727 # like to nest child under parent, because testing has demonstrated 01728 # that even on relatively slow hardware the delays involved in 01729 # setting up separate rsync connections tend to dominate 01730 # synchronization time for relying parties. 01731 # 01732 # @li The repository operator might also want to do some checks to 01733 # assure itself that what it's about to allow the RPKI engine to 01734 # publish is not dangerous toxic waste. 01735 # 01736 # The up-down protocol includes a mechanism by which a parent can 01737 # suggest a %publication URI to each of its children. The children are 01738 # not required to accept this hint, and the children must make separate 01739 # arrangements with the repository operator (who might or might not be 01740 # the same as the entity that hosts the children's RPKI engine 01741 # operations) to use the suggested %publication point, but if everything 01742 # works out, this allows children to nest cleanly under their parents 01743 # %publication points, which helps reduce synchronization time for 01744 # relying parties. 01745 # 01746 # In this case, one could argue that the %publication server is 01747 # responsible for preventing one of its clients (the child in the above 01748 # description) from stomping on data published by another of its clients 01749 # (the parent in the above description). This goes beyond the basic 01750 # access check and requires the %publication server to determine whether 01751 # the parent has given its consent for the child to publish under the 01752 # parent. Since the RPKI certificate profile requires the child's 01753 # %publication point to be indicated in an SIA extension in a certificate 01754 # issued by the parent to the child, the %publication engine can infer 01755 # this permission from the parent's issuance of a certificate to the 01756 # child. Since, by definition, the parent also uses this %publication 01757 # server, this is an easy check, as the %publication server should 01758 # already have the parent's certificate available by the time it needs 01759 # to check the child's certificate. 01760 # 01761 # The previous paragraph only covers a "publish" action for a 01762 # <certificate/> %object. For "publish" actions on other 01763 # objects, the %publication server would need to trace permission back 01764 # to the certificate issued by the parent; for "withdraw" actions, 01765 # the %publication server would have to perform the same checks it 01766 # would perform for a "publish" action, using the current published 01767 # data before withdrawing it. The latter in turn implies an ordering 01768 # constraint on "withdraw" actions in order to preserve the data 01769 # necessary for these access control decisions; as this may prove 01770 # impractical, the %publication server may probably need to make 01771 # periodic sweeps over its published data looking for orphaned 01772 # objects, but that's probably a good idea anyway. 01773 # 01774 # Note that, in this %publication model, any agreement that the 01775 # repository makes to publish the RPKI engine's output is conditional 01776 # upon the %object to be published passing whatever access control checks 01777 # the %publication server imposes. 01778 01779 ## @page sql-schemas SQL database schemas 01780 # 01781 # @li @subpage rpkid-sql "rpkid database schema" 01782 # @li @subpage pubd-sql "pubd database schema" 01783 # @li @subpage irdbd-sql "irdbd database schema" 01784 01785 ## @page rpkid-sql rpkid SQL schema 01786 # 01787 # @dotfile rpkid.dot "Diagram of rpkid.sql" 01788 # 01789 # @verbinclude rpkid.sql 01790 01791 ## @page pubd-sql pubd SQL Schema 01792 # 01793 # @dotfile pubd.dot "Diagram of pubd.sql" 01794 # 01795 # @verbinclude pubd.sql 01796 01797 ## @page irdbd-sql irdbd SQL Schema 01798 # 01799 # @dotfile irdbd.dot "Diagram of irdbd.sql" 01800 # 01801 # @verbinclude irdbd.sql 01802 01803 ## @page bpki-model BPKI model 01804 # 01805 # The "business PKI" (BPKI) is the PKI used to authenticate 01806 # communication on the up-down, left-right, and %publication protocols. 01807 # BPKI certificates are @em not resource PKI (RPKI) certificates. The 01808 # BPKI is a separate PKI that represents relationships between the 01809 # various entities involved in the production side of the RPKI system. 01810 # In most cases the BPKI tree will follow existing business 01811 # relationships, hence the name "BPKI". 01812 # 01813 # Setup of the BPKI is handled by the back end; for the most part, 01814 # rpkid and pubd just use the result. The one place where the engines 01815 # are directly involved in creation of new BPKI certificates is in the 01816 # production of end-entity certificates for use by the engines. 01817 # 01818 # There are a few design principals that underly the chosen BPKI model: 01819 # @li Each engine should rely on a single BPKI trust anchor which is 01820 # controlled by the back end entity that runs the engine; all 01821 # other trust material should be cross-certified into the engine's 01822 # BPKI tree. 01823 # @li Private keys must never transit the network. 01824 # @li Except for end entity certificates, the engine should only have 01825 # access to the BPKI certificates; in particular, the private key 01826 # for the BPKI trust anchor should not be accessible to the engine. 01827 # @li The number of BPKI keys and certificates that the engine has to 01828 # manage should be no larger than is necessary. 01829 # 01830 # rpkid's hosting model adds an additional constraint: rpkid's BPKI 01831 # trust anchor belongs to the entity operating rpkid, but the entities 01832 # hosted by rpkid should have control of their own BPKI private keys. 01833 # This implies the need for an additional layer of BPKI certificate 01834 # hierarchy within rpkid. 01835 # 01836 # Here is a simplified picture of what the BPKI might look like for an 01837 # rpkid operator that hosts two entities, "Alice" and "Ellen": 01838 # 01839 # @dot 01840 # // Color code: 01841 # // Black: Hosting entity 01842 # // Blue: Hosted entity 01843 # // Red: Cross-certified peer 01844 # // 01845 # // Shape code: 01846 # // Octagon: TA 01847 # // Diamond: CA 01848 # // Record: EE 01849 # 01850 # digraph bpki_rpkid { 01851 # splines = true; 01852 # size = "14,14"; 01853 # node [ fontname = Times, fontsize = 9 ]; 01854 # 01855 # // Hosting entity 01856 # node [ color = black, shape = record ]; 01857 # TA [ shape = octagon, label = "BPKI TA" ]; 01858 # rpkid [ label = "rpkid|{HTTPS server|HTTPS left-right client|CMS left-right}" ]; 01859 # irdbd [ label = "irdbd|{HTTPS left-right server|CMS left-right}" ]; 01860 # irbe [ label = "IRBE|{HTTPS left-right client|CMS left-right}" ]; 01861 # 01862 # // Hosted entities 01863 # node [ color = blue, fontcolor = blue ]; 01864 # Alice_CA [ shape = diamond ]; 01865 # Alice_EE [ label = "Alice\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; 01866 # Ellen_CA [ shape = diamond ]; 01867 # Ellen_EE [ label = "Ellen\nBSC EE|{HTTPS up-down client|CMS up-down}" ]; 01868 # 01869 # // Peers 01870 # node [ color = red, fontcolor = red, shape = diamond ]; 01871 # Bob_CA; 01872 # Carol_CA; 01873 # Dave_CA; 01874 # Frank_CA; 01875 # Ginny_CA; 01876 # Harry_CA; 01877 # node [ shape = record ]; 01878 # Bob_EE [ label = "Bob\nEE|{HTTPS up-down|CMS up-down}" ]; 01879 # Carol_EE [ label = "Carol\nEE|{HTTPS up-down|CMS up-down}" ]; 01880 # Dave_EE [ label = "Dave\nEE|{HTTPS up-down|CMS up-down}" ]; 01881 # Frank_EE [ label = "Frank\nEE|{HTTPS up-down|CMS up-down}" ]; 01882 # Ginny_EE [ label = "Ginny\nEE|{HTTPS up-down|CMS up-down}" ]; 01883 # Harry_EE [ label = "Bob\nEE|{HTTPS up-down|CMS up-down}" ]; 01884 # 01885 # edge [ color = black, style = solid ]; 01886 # TA -> Alice_CA; 01887 # TA -> Ellen_CA; 01888 # 01889 # edge [ color = black, style = dotted ]; 01890 # TA -> rpkid; 01891 # TA -> irdbd; 01892 # TA -> irbe; 01893 # 01894 # edge [ color = blue, style = solid ]; 01895 # Alice_CA -> Bob_CA; 01896 # Alice_CA -> Carol_CA; 01897 # Alice_CA -> Dave_CA; 01898 # Ellen_CA -> Frank_CA; 01899 # Ellen_CA -> Ginny_CA; 01900 # Ellen_CA -> Harry_CA; 01901 # 01902 # edge [ color = blue, style = dotted ]; 01903 # Alice_CA -> Alice_EE; 01904 # Ellen_CA -> Ellen_EE; 01905 # 01906 # edge [ color = red, style = solid ]; 01907 # Bob_CA -> Bob_EE; 01908 # Carol_CA -> Carol_EE; 01909 # Dave_CA -> Dave_EE; 01910 # Frank_CA -> Frank_EE; 01911 # Ginny_CA -> Ginny_EE; 01912 # Harry_CA -> Harry_EE; 01913 # } 01914 # @enddot 01915 # 01916 # Black objects belong to the hosting entity, blue objects belong to 01917 # the hosted entities, red objects are cross-certified objects from 01918 # the hosted entities' peers. The arrows indicate certificate 01919 # issuance: solid arrows are the ones that rpkid will care about 01920 # during certificate validation, dotted arrows show the origin of the 01921 # EE certificates that rpkid uses to sign CMS and TLS messages. 01922 # 01923 # There's one nasty bit where the model had to bend to fit the current 01924 # state of the underlying protocols: it's not possible to use exactly 01925 # the same BPKI keys and certificates for HTTPS and CMS. The reason 01926 # for this is simple: each hosted entity has its own BPKI, as does the 01927 # hosting entity, but the HTTPS listener is shared. The only ways to 01928 # avoid sharing the HTTPS server certificate would be to use separate 01929 # listeners for each hosted entity, which scales poorly, or to rely on 01930 # the TLS "Server Name Indication" extension (RFC 4366 3.1) which is 01931 # not yet widely implemented. 01932 # 01933 # The certificate tree looks complicated, but the set of certificates 01934 # needed to build any particular validation chain is obvious, again 01935 # excepting the HTTPS server case, where the client certificate is the 01936 # first hint that the engine has of the client's identity, so the 01937 # server must be prepared to accept any current client certificate. 01938 # 01939 # Detailed instructions on how to build a BPKI are beyond the scope of 01940 # this document, but one can handle simple cases using the OpenSSL 01941 # command line tool and cross_certify.py; the latter is a tool 01942 # designed specifically for the purpose of generating the 01943 # cross-certification certificates needed to splice foreign trust 01944 # material into a BPKI tree. 01945 # 01946 # The BPKI tree for a pubd instance is similar to to the BPKI tree for 01947 # an rpkid instance, but is a bit simpler, as pubd does not provide 01948 # hosting in the same sense that rpkid does: pubd is a relatively 01949 # simple server that publishes objects as instructed by its clients. 01950 # 01951 # Here's a simplified picture of what the BPKI might look like for a 01952 # pubd operator that serves two clients, "Alice" and "Bob": 01953 # 01954 # @dot 01955 # // Color code: 01956 # // Black: Operating entity 01957 # // Red: Cross-certified client 01958 # // 01959 # // Shape code: 01960 # // Octagon: TA 01961 # // Diamond: CA 01962 # // Record: EE 01963 # 01964 # digraph bpki_pubd { 01965 # splines = true; 01966 # size = "14,14"; 01967 # node [ fontname = Times, fontsize = 9 ]; 01968 # 01969 # // Operating entity 01970 # node [ color = black, fontcolor = black, shape = record ]; 01971 # TA [ shape = octagon, label = "BPKI TA" ]; 01972 # pubd [ label = "pubd|{HTTPS server|CMS}" ]; 01973 # ctl [ label = "Control|{HTTPS client|CMS}" ]; 01974 # 01975 # // Clients 01976 # node [ color = red, fontcolor = red, shape = diamond ]; 01977 # Alice_CA; 01978 # Bob_CA; 01979 # node [ color = red, fontcolor = red, shape = record ]; 01980 # Alice_EE [ label = "Alice\nEE|{HTTPS client|CMS}" ]; 01981 # Bob_EE [ label = "Bob\nEE|{HTTPS client|CMS}" ]; 01982 # 01983 # edge [ color = black, style = dotted ]; 01984 # TA -> pubd; 01985 # TA -> ctl; 01986 # 01987 # edge [ color = black, style = solid ]; 01988 # TA -> Alice_CA; 01989 # TA -> Bob_CA; 01990 # 01991 # edge [ color = red, style = solid ]; 01992 # Alice_CA -> Alice_EE; 01993 # Bob_CA -> Bob_EE; 01994 # } 01995 # @enddot 01996 # 01997 # While it is likely that RIRs (at least) will operate both rpkid and 01998 # pubd instances, the two functions are conceptually separate. As far 01999 # as pubd is concerned, it doesn't matter who operates the rpkid 02000 # instance: pubd just has clients, each of which has trust material 02001 # that has been cross-certified into pubd's BPKI. Similarly, rpkid 02002 # doesn't really care who operates a pubd instance that it's been 02003 # configured to use, it just treats that pubd as a foreign BPKI whose 02004 # trust material has to be cross-certified into its own BPKI. Cross 02005 # certification itself is done by the back end operator, using 02006 # cross_certify or some equivalent tool; the resulting BPKI 02007 # certificates are configured into rpkid and pubd via the left-right 02008 # protocol and the control subprotocol of the publication protocol, 02009 # respectively. 02010 # 02011 # Because the BPKI tree is almost entirely controlled by the operating 02012 # entity, CRLs are not necessary for most of the BPKI. The one 02013 # exception to this is the EE certificates issued under the 02014 # cross-certification points. These EE certificates are generated by 02015 # the peer, not the local operator, and thus require CRLs. Because of 02016 # this, both rpkid and pubd require regular updates of certain BPKI 02017 # CRLs, again via the left-right and publication control protocols. 02018 # 02019 # Because the left-right protocol and the publication control 02020 # subprotocol are used to configure BPKI certificates and CRLs, they 02021 # cannot themselves use certificates and CRLs configured in this way. 02022 # This is why the configuration files for rpkid and pubd require 02023 # static configuration of the left-right and publication control 02024 # certificates. 02025 02026 # Local Variables: 02027 # compile-command: "cd .. && make doc" 02028 # End: