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