diff options
Diffstat (limited to 'rpkid/doc')
| -rw-r--r-- | rpkid/doc/INSTALLATION | 72 | ||||
| -rw-r--r-- | rpkid/doc/OPERATION | 692 | ||||
| -rw-r--r-- | rpkid/doc/left-right-protocol | 477 | ||||
| -rw-r--r-- | rpkid/doc/publication-protocol | 227 |
4 files changed, 1468 insertions, 0 deletions
diff --git a/rpkid/doc/INSTALLATION b/rpkid/doc/INSTALLATION new file mode 100644 index 00000000..aec99f3f --- /dev/null +++ b/rpkid/doc/INSTALLATION @@ -0,0 +1,72 @@ +Installation + + Preliminary installation instructions for rpkid et al. + + These are the production-side RPKI tools, for Internet Registries + (RIRs, LIRs, etc). See ../rcynic/README for relying party tools. + + rpkid is a set of Python modules supporting generation and maintenance + of resource certificates. Most of the code is in the rpkid/rpki/ + directory. rpkid itself is a relatively small program that calls the + library modules. There are several other programs that make use of the + same libraries, as well as a collection of test programs. + + At present the package is intended to be run out of its build + directory. Setting up proper installation in a system area using the + Python distutils package would likely not be very hard but has not yet + been done. + + Note that initial development of this code has been on FreeBSD, so + installation will probably be easiest on FreeBSD. + + The first step to running the code is to build the OpenSSL and POW + binaries. At present the OpenSSL code is just a copy of the stock + OpenSSL 0.9.8g release, compiled with special options to enable RFC + 3779 support that ISC wrote under previous contract to ARIN. The POW + (Python OpenSSL Wrapper) library is an extended copy of the stock POW + release. + + To build these, cd to the top-level directory in the distribution and + type "make". + + $ cd $top + $ make + + This should automatically build everything, in the right order, + including staticly linking the POW extension module with the OpenSSL + library to provide RFC 3779 support. + + Next, see the list of required Python modules in rpkid/README. Note + that the Python code requires Python version 2.5. Install any modules + that might be missing. + + You will also need a MySQL installation. This code was developed using + MySQL 5.1 and has been tested with MySQL 5.0 and 5.1. + + The architecture is intended to support hardware signing modules + (HSMs), but the code to support them has not been written. + + At this point, you should have all the necessary software installed. + You will probably want to test it. All tests should be run from the + rpkid/ directory. + + Some of the tests require MySQL databases to store their data. To set + up all the databases that the tests will need, run the SQL commands in + rpkid/testbed.sql. The MySQL command line client is usually the easiest + way to do this, eg: + + $ cd $top/rpkid + $ mysql -u root -p <testbed.sql + + To run the tests, run "make all-tests": + + $ cd $top/rpkid + $ make all-tests + + If nothing explodes, your installation is probably ok. Any Python + backtraces in the output indicate a problem. + __________________________________________________________________ + + + Generated on Thu Jun 12 17:41:24 2008 for RPKI Engine by doxygen + 1.5.5 diff --git a/rpkid/doc/OPERATION b/rpkid/doc/OPERATION new file mode 100644 index 00000000..19471050 --- /dev/null +++ b/rpkid/doc/OPERATION @@ -0,0 +1,692 @@ +Operation + + Preliminary operation instructions for rpkid et al. + + These are the production-side RPKI tools, for Internet Registries + (RIRs, LIRs, etc). See ../rcynic/README for relying party tools. + + Warning: + rpkid is still in development, and the code changes more often + than the hand-maintained portions of this documentation. The + following text was reasonably accurate at the time it was + written but may be obsolete by the time you read it. + + At present the package is intended to be run out of the rpkid/ + directory. + + In addition to the library routines in the rpkid/rpki/ directory, the + package includes the following programs: + + * rpkid.py: The main RPKI engine daemon. + + * pubd.py: The publication engine daemon. + + * rootd.py: A separate daemon for handling the root of an RPKI + certificate tree. This is essentially a stripped down version of + rpkid with no SQL database, no left-right protocol implementation, + and only the parent side of the up-down protocol. It's separate + because the root is a special case in several ways and it was + simpler to keep the special cases out of the main daemon. + + * irdbd.py: A sample implementation of an IR database daemon. rpkid + calls into this to perform lookups via the left-right protocol. + + * irbe-cli.py: A command-line client for the left-right control + protocol. + + * irbe-setup.py: An example of a script to set up the mappings + between the IRDB and rpkid's own database, using the left-right + control protocol. + + * cronjob.py: A trivial HTTP client used to drive rpkid cron events. + + * testbed.py: A test tool for running a collection of rpkid and irdb + instances under common control, driven by a unified test script. + + * testpoke.py: A simple client for the up-down protocol, mostly + compatable with APNIC's rpki_poke.pl tool. + + Most of these programs take configuration files in a common format + similar to that used by the OpenSSL command line tool. The test + programs also take input in YAML format to drive the tests. Runs of the + testbed.py test tool will generate a fairly complete set configuration + files which may be useful as examples. + + Basic operation consists of creating the appropriate MySQL databases, + starting rpkid, rootd, and irdbd, using the left-right control protocol + to set up rpkid's internal state, and setting up a cron job to invoke + rpkid's cron action at regular intervals. All other operations should + occur either as a result of cron events or as a result of incoming + left-right and up-down protocol requests. + + Note that the publication protocol isn't fully specified yet, much less + implmenented. At the moment rpkid just writes its outputs to a local + directory tree. + + Note that the full event-driven model for rpkid hasn't yet been + implemented. The design is intended to allow an arbitrary number of + hosted RPKI engines to run in a single rpkid instance, but without the + event-driven tasking model one has to set up a separate rpkid instance + for each hosted RPKI engine. + + At present the daemon programs all run in foreground, that is, if one + wants them to run in background one must do so manually, eg, using + Bourne shell syntax: + + $ python whatever.py & + $ echo >whatever.pid "$!" + + All of the daemons use syslog. At present they all set LOG_PERROR, so + all logging also goes to stderr. + +rpkid.py + + rpkid is the main RPKI engine daemon. Configuration of rpkid is a two + step process: a config file to bootstrap rpkid to the point where it + can speak using the left-right protocol, followed by dynamic + configuration via the left-right protocol. In production use the latter + stage would be handled by the IRBE stub; for test and develoment + purposes it's handled by the irbe-cli.py command line interface or by + the testbed.py test framework. + + rpkid stores dynamic data in an SQL database, which must have been + created for it, as explained in the installation guide. + + The default config file is rpkid.conf, start rpkid with "-c filename" + to choose a different config file. All options are in the section + "[rpkid]". Certificates, keys, and trust anchors may be in either DER + or PEM format. + + Config file options: + + * startup-message: String to log on startup, useful when debugging a + collection of rpkid instances at once. + + * sql-username: Username to hand to MySQL when connecting to rpkid's + database. + + * sql-database: MySQL's database name for rpkid's database. + + * sql-password: Password to hand to MySQL when connecting to rpkid's + database. + + * cms-ta-irdb: Name of file containing CMS trust anchor to use when + authenticating messages from irdbd. + + * cms-ta-irbe: Name of file containing CMS trust anchor to use when + authenticating control messages from IRBE. + + * cms-key: Name of file containing RSA key to use when signing CMS + messages to IRBE or irdbd. + + * cms-cert: Name(s) of file(s) containing certificate(s) to include + in CMS wrapper when signing messages to IRBE or irdbd. You can + specify more than one certificate using OpenSSL-style subscripts: + cms-cert.0, cms-cert.1, etc. + + * https-key: Name of file containing RSA key to use, both in the + HTTPS server role (for both up-down and left-right protocols) and + in the HTTPS client role (left-right protocol only). + + * https-cert: Name(s) of file(s) containing certificate(s) to use in + same contexts where https-key is used. You can specify more than + one certificate using OpenSSL-style subscripts: https-cert.0, + https-cert.1, etc. + + * https-ta: Name of file containing trust anchor to use when + verifying irdbd's HTTPS server certificate. + + * irdb-url: Service URL for irdbd. Must be a https:// URL. + + * https-server-host: Hostname or IP address on which to listen for + HTTPS connections. Current default is INADDR_ANY (IPv4 0.0.0.0); + this will need to be hacked to support IPv6 for production. + + * https-server-port: TCP port on which to listen for HTTPS + connections. + +pubd.py + + pubd is the publication daemon. It implements the server side of the + publication protocol, and is used by rpkid to publish the certificates + and other objects that rpkid generates. + + pubd is separate from rpkid for two reasons: + + * The hosting model allows entities which choose to run their own + copies of rpkid to publish their output under a common publication + point. In general, encouraging shared publication services where + practical is a good thing for relying parties, as it will speed up + rcynic synchronization time. + + * The publication server has to run on (or at least close to) the + publication point itself, which in turn must be on a publically + reachable server to be useful. rpkid, on the other hand, need only + be reachable by the IRBE and its children in the RPKI tree. rpkid + is a much more complex piece of software than pubd, so in some + situations it might make sense to wrap tighter firewall constraints + around rpkid than would be practical if rpkid and pubd were a + single program. + + pubd stores dynamic data in an SQL database, which must have been + created for it, as explained in the installation guide. pubd also + stores the published objects themselves as disk files in a configurable + location which should correspond to an appropriate module definition in + rsync.conf. + + The default config file is pubd.conf, start pubd with "-c filename" to + choose a different config file. ALl options are in the section + "[pubd]". Certifiates, keys, and trust anchors may be either DER or PEM + format. + + Config file options: + + * sql-username: Username to hand to MySQL when connecting to pubd's + database. + + * sql-database: MySQL's database name for pubd's database. + + * sql-password: Password to hand to MySQL when connecting to pubd's + database. + + * bpki-ta: Name of file containing master BPKI trust anchor for pubd. + All BPKI validation in pubd traces back to this trust anchor. + + * irbe-cert: Name of file containing BPKI certificate used by IRBE + when talking to pubd. + + * pubd-cert: Name of file containing BPKI certificate used by pubd. + + * pubd-key: Name of file containing RSA key corresponding to + pubd-cert. + + * server-host: Hostname or IP address on which to listen for HTTPS + connections. Current default is INADDR_ANY (IPv4 0.0.0.0); this + will need to be hacked to support IPv6 for production. + + * server-port: TCP port on which to listen for HTTPS connections. + + * publication-base: Path to base of filesystem tree where pubd should + store publishable objects. Default is "publication/". + +rootd.py + + rootd is a stripped down implmenetation of (only) the server side of + the up-down protocol. It's a separate program because the root + certificate of an RPKI certificate tree requires special handling and + may also require a special handling policy. rootd is a simple + implementation intended for test use, it's not suitable for use in a + production system. All configuration comes via the config file. + + The default config file is rootd.conf, start rootd with "-c filename" + to choose a different config file. All options are in the section + "[rootd]". Certificates, keys, and trust anchors may be in either DER + or PEM format. + + Config file options: + + * cms-ta: Name of file containing trust anchor to use when verifying + CMS up-down queries. + + * cms-key: Name of file containing RSA key to use when signing CMS + up-down replies. + + * cms-cert: Name(s) of file(s) containing certificate(s) to include + in CMS wrapper when signing up-down replies. You can specify more + than one certificate using OpenSSL-style subscripts: cms-cert.0, + cms-cert.1, etc. + + * https-key: Name of file containing RSA key to use in the HTTPS + server role for the up-down protocol. + + * https-cert: Name(s) of file(s) containing certificate(s) to use in + the HTTPS server role for the up-down protocol. You can specify + more than one certificate using OpenSSL-style subscripts: + https-cert.0, https-cert.1, etc. + + * https-server-host: Hostname or IP address on which to listen for + HTTPS connections. Default is localhost. + + * https-server-port: TCP port on which to listen for HTTPS + connections. + + * rpki-key: Name of file containing RSA key to use in signing + resource certificates. + + * rpki-issuer: Name of file containing self-signed root resource + certificate corresponding to rpki-key. + + * rpki-subject-filename: Name of file that rootd should use to save + the one and only certificate it issues. + + * rpki-pkcs10-filename: Name of file that rootd should use when + saving a copy of the received PKCS #10 request for a resource + certificate. This is only used for debugging. Default is not to + save the PKCS #10 request. + +irdbd.py + + irdbd is a sample implemntation of the server side of the IRDB callback + subset of the left-right protocol. In production use this service is a + function of the IRBE stub; irdbd may be suitable for production use in + simple cases, but an IR with a complex IRDB may need to extend or + rewrite irdbd. + + irdbd requires a pre-populated database to represent the IR's + customers. irdbd expects this database to use the SQL schema defined in + rpkid/irdbd.sql. Once this database has been populated, the IRBE stub + needs to create the appropriate objects in rpkid's database via the + control subset of the left-right protocol, and store the linkage IDs + (foreign keys into rpkid's database, basicly) in the IRDB. The + irbe-setup.py program shows an example of how to do this. + + irdbd's default config file is irdbd.conf, start irdbd with "-c + filename" to choose a different config file. All options are in the + section "[irdbd]". Certificates, keys, and trust anchors may be in + either DER or PEM format. + + Config file options: + + * startup-message: String to log on startup, useful when debugging a + collection of irdbd instances at once. + + * sql-username: Username to hand to MySQL when connecting to irdbd's + database. + + * sql-database: MySQL's database name for irdbd's database. + + * sql-password: Password to hand to MySQL when connecting to irdbd's + database. + + * cms-ta: Name of file containing CMS trust anchor to use when + authenticating messages from rpkid. + + * cms-key: Name of file containing RSA key to use when signing CMS + messages to rpkid. + + * cms-cert: Name(s) of file(s) containing certificate(s) to include + in CMS wrapper when signing messages to rpkid. You can specify more + than one certificate using OpenSSL-style subscripts: cms-cert.0, + cms-cert.1, etc. + + * https-key: Name of file containing RSA key to use in the HTTPS + server role when listening for connections from rpkid. + + * https-cert: Name(s) of file(s) containing certificate(s) to use in + the HTTPS server role when listening for connections from rpkid. + You can specify more than one certificate using OpenSSL-style + subscripts: https-cert.0, https-cert.1, etc. + + * https-url: Service URL for irdbd. Must be a https:// URL. + +irbe-cli.py + + irbe-cli is a simple command line client for the control subset of the + left-right protocol. In production use this functionality would be part + of the IRBE stub. + + Basic configuration of irbe-cli is handled via a config file. The + specific action or actions to be performed are specified on the command + line, and map closely to the left-right protocol itself. + + At present the user is assumed to be able to read the (XML) left-right + protocol messages, and with one exception, no attempt is made to + interpret the responses other than to check for errors. The one + exception is that, if the --pem_out option is specified on the command + line, any PKCS #10 requests received from rpkid will be written in PEM + format to that file; this makes it easier to hand these requests off to + the business PKI in order to issue signing certs corresponding to newly + generated business keys. + + Command line IR back-end control program for rpkid and pubd. + + Usage: + + # Top-level options: + --config= --help --pem_out= --verbose + + # left-right protocol: + parent --action= --tag= --self_id= --parent_id= --bsc_id= + --repository_id= --peer_contact_uri= --sia_base= --sender_name= + --recipient_name= --bpki_cms_cert= --bpki_cms_glue= + --bpki_https_cert= --bpki_https_glue= --rekey --reissue --revoke + repository --action= --tag= --self_id= --repository_id= --bsc_id= + --peer_contact_uri= --bpki_cms_cert= --bpki_cms_glue= + --bpki_https_cert= --bpki_https_glue= + self --action= --tag= --self_id= --crl_interval= --regen_margin= + --bpki_cert= --bpki_glue= --rekey --reissue --revoke --run_now + --publish_world_now + child --action= --tag= --self_id= --child_id= --bsc_id= --bpki_cert= + --bpki_glue= --reissue + route_origin --action= --tag= --self_id= --route_origin_id= + --as_number= --ipv4= --ipv6= --suppress_publication + bsc --action= --tag= --self_id= --bsc_id= --key_type= --hash_alg= + --key_length= --signing_cert= --signing_cert_crl= + --generate_keypair + + # publication protocol: + certificate --action= --tag= --client_id= --uri= + roa --action= --tag= --client_id= --uri= + manifest --action= --tag= --client_id= --uri= + client --action= --tag= --client_id= --base_uri= --bpki_cert= + --bpki_glue= + config --action= --tag= --bpki_crl= + crl --action= --tag= --client_id= --uri= + + Global options (--config, --help, --pem_out) come first, then zero or + more commands (parent, repository, self, child, route_origin, bsc), + each followed by its own set of options. The commands map to elements + in the left-right protocol, and the command-specific options map to + attributes or subelements for those commands. + + --action is one of create, set, get, list, or destroy; exactly one of + these must be specified for each command. + + --type is query or reply; since irbe-cli is a client, query is the + default. + + --tag is an optional arbitrary tag (think IMAP) to simplify matching up + replies with batched queries. + + --*_id options refer to the primary keys of previously created objects. + + The remaining options are specific to the particular commands, and + follow directly from the left-right protocol specification. + + A trailing "=" in the above option summary indicates that an option + takes a value, eg, "--action create" or "--action=create". Options + without a trailing "=" correspond to boolean control attributes. + + The default config file for irbe-cli is irbe.conf, start rpkid with "-c + filename" (or "--config filename") to choose a different config file. + All options are in the section "[irbe-cli]". Certificates, keys, and + trust anchors may be in either DER or PEM format. + + Config file options: + + * cms-ta: Name of file containing CMS trust anchor to use when + authenticating messages from rpkid. + + * cms-key: Name of file containing RSA key to use when signing CMS + messages to rpkid. + + * cms-cert: Name(s) of file(s) containing certificate(s) to include + in CMS wrapper when signing messages to rpkid. You can specify more + than one certificate using OpenSSL-style subscripts: cms-cert.0, + cms-cert.1, etc. + + * https-key: Name of file containing RSA key to use in the HTTPS + client role when contacting rpkid. + + * https-cert: Name(s) of file(s) containing certificate(s) to use in + the HTTPS client role when contacting rpkid. You can specify more + than one certificate using OpenSSL-style subscripts: https-cert.0, + https-cert.1, etc. + + * https-ta: Name of file containing trust anchor to use when + verifying rpkid's HTTPS server certificate. + + * https-url: Service URL for rpkid. Must be a https:// URL. + +irbe-setup.py config file + + The default config file is irbe.conf, start rpkid with "-c filename" to + choose a different config file. Most options are in the section + "[irbe-cli]", but a few are in the section "[irdbd]". Certificates, + keys, and trust anchors may be in either DER or PEM format. + + Options in the "[irbe-cli]" section: + + * cms-ta: Name of file containing CMS trust anchor to use when + authenticating messages from rpkid. + + * cms-key: Name of file containing RSA key to use when signing CMS + messages to rpkid. + + * cms-cert: Name(s) of file(s) containing certificate(s) to include + in CMS wrapper when signing messages to rpkid. You can specify more + than one certificate using OpenSSL-style subscripts: cms-cert.0, + cms-cert.1, etc. + + * https-key: Name of file containing RSA key to use in the HTTPS + client role when contacting rpkid. + + * https-cert: Name(s) of file(s) containing certificate(s) to use in + the HTTPS client role when contacting rpkid. You can specify more + than one certificate using OpenSSL-style subscripts: https-cert.0, + https-cert.1, etc. + + * https-ta: Name of file containing trust anchor to use when + verifying rpkid's HTTPS server certificate. + + * https-url: Service URL for rpkid. Must be a https:// URL. + + Options in the "[irdbd]" section: + + * sql-username: Username to hand to MySQL when connecting to irdbd's + database. + + * sql-database: MySQL's database name for irdbd's database. + + * sql-password: Password to hand to MySQL when connecting to irdbd's + database. + +cronjob.py + + This is a trivial program to trigger a cron run within rpkid. Once + rpkid has been converted to the planned event-driven model, this + function will be handled internally, but for now it has to be triggered + by an external program. For pseudo-production use one would run this + program under the system cron daemon. For scripted testing it happens + to be useful to be able to control when cron cycles occur, so at the + current stage of code development use of an external trigger is a + useful feature. + + The default config file is cronjob.conf, start cronjob with "-c + filename" to choose a different config file. All options are in the + section "[cronjob]". Certificates, keys, and trust anchors may be in + either DER or PEM format. + + Config file options: + + * https-key: Name of file containing RSA key to use in the HTTPS + client role when contacting rpkid. + + * https-cert: Name(s) of file(s) containing certificate(s) to use in + the HTTPS client role when contacting rpkid. You can specify more + than one certificate using OpenSSL-style subscripts: https-cert.0, + https-cert.1, etc. + + * https-ta: Name of file containing trust anchor to use when + verifying rpkid's HTTPS server certificate. + + * https-url: Service URL for rpkid. Must be a https:// URL. + +testbed.py: + + testbed is a test harness to set up and run a collection of rpkid and + irdbd instances under scripted control. testbed is a very recent + addition to the toolset and is still evolving rapidly. + + Unlike the programs described above, testbed takes two configuration + files in different languages. The first configuration file uses the + same syntax as the above configuration files but is completely + optional. The second configuration file is the test script, which is + encoded using the YAML serialization language (see http://www.yaml.org/ + for more information on YAML). The YAML script is not optional, as it + describes the test layout. testbed is designed to support running a + fairly wide set of test configurations as canned scripts without + writing any new control code. The intent is to make it possible to + write meaningful regression tests. + + All of the options in in the first (optional) configuration file are + just overrides for wired-in default values. In most cases the defaults + will suffice, and the set of options is still in flux, so only a few of + the options are described here. The default name for this configuration + file is testbed.conf, run testbed with "-c filename" to change it. + + testbed.conf options: + + * testbed_dir: Working directory into which testbed should write the + (many) files it generates. Default is "testbed.dir". + + * irdb_db_pass: MySQL password for the "irdb" user. Default is + "fnord". You may want to override this. + + * rpki_db_pass: MySQL password for the "rpki" user. Default is + "fnord". You may want to override this. + + * rootd_sia: rsync URI naming a (perhaps fictious) directory to use + as the id-ad-caRepository SIA value in the generated root resource + certificate. Default is "rsync://wombat.invalid/". You may want to + override this if you intend to run an rsync server and test against + the generated results using rcynic. This default will likely change + if and when testbed learns how to run rcynic itself as part of the + test suite. + + The second configuration file is named testbed.yaml by default, run + testbed with "-y filename" to change it. The YAML file contains + multiple YAML "documents". The first document describes the initial + test layout and resource allocations, subsequent documents describe + modifications to the initial allocations and other parameters. + Resources listed in the initial layout are aggregated automatically, so + that a node in the resource hierarchy automatically receives the + resources it needs to issue whatever its children are listed as + holding. Actions in the subsequent documents are modifications to the + current resource set, modifications to validity dates or other + non-resource parameters, or special commands like "sleep". The details + are still evolving, but here's an example of current usage: + + name: RIR + valid_for: 2d + sia_base: "rsync://wombat.invalid/" + kids: + - name: LIR0 + kids: + - name: Alice + ipv4: 192.0.2.1-192.0.2.33 + asn: 64533 + --- + - name: Alice + valid_add: 10 + --- + - name: Alice + add_as: 33 + valid_add: 2d + --- + - name: Alice + valid_sub: 2d + --- + - name: Alice + valid_for: 10d + + This specifies an initial layout consisting of an RPKI engine named + "RIR", with one child "LIR0", which in turn has one child "Alice". + Alice has a set of assigned resources, and all resources in the system + are initially set to be valid for two days from the time at which the + test is started. The first subsequent document adds ten seconds to the + validity interval for Alice's resources and makes no other + modifications. The second subsequent document grants Alice additional + resources and adds another two days to the validity interval for + Alice's resources. The next document subtracts two days from the + validity interval for Alice's resources. The final document sets the + validity interval for Alice's resources to ten days. + + Operators in subsequent (update) documents: + + * add_as, add_v4, add_v6: These add ASN, IPv4, or IPv6 resources, + respectively. + + * sub_as, sub_v4, sub_v6: These subtract resources. + + * valid_until: Set an absolute expiration date. + + * valid_for: Set a relative expiration date. + + * valid_add, valid_sub: Add to or subtract from validity interval. + + * sleep [interval]: Sleep for specified interval, or until testbed + receives a SIGALRM signal. + + Absolute timestamps should be in the form shown (UTC timestamp format + as used in XML). + + Intervals (valid_add, valid_sub, valid_for, sleep) are either integers, + in which case they're interpreted as seconds, or are a string of the + form "wD xH yM zS" where w, x, y, and z are integers and D, H, M, and S + indicate days, hours, minutes, and seconds. In the latter case all of + the fields are optional, but at least one must be specified. For + example, "3D4H" means "three days plus four hours". + +testpoke.py + + This is a command-line client for the up-down protocol. Unlike all of + the above programs, testpoke does not accept a config file in + OpenSSL-compatable format at all. Instead, it is configured exclusively + by a YAML script. testpoke's design was constrained by a desire to have + it be compatable with APNIC's rpki_poke.pl tool, so that the two tools + could use a common configuration language to simplify scripted testing. + There are minor variations due to slightly different feature sets, but + YAML files intended for one program will usually work with the other. + + README for APNIC's tool describing the input language can be found at + http://mirin.apnic.net/svn/rpki_engine/branches/gary-poker/client/poke/ + README + + testpoke.py takes a simplified command line and uses only one YAML + input file. + + Usage: python testpoke.py [ { -y | --yaml } configfile ] + [ { -r | --request } requestname ] + [ { -h | --help } ] + + Default configuration file is testpoke.yaml, override with --yaml + option. + + The --request option specifies the specific command within the YAML + file to execute. + + Sample configuration file: + + --- + # Sample YAML configuration file for testpoke.py + + version: 1 + posturl: https://localhost:4433/up-down/1 + recipient-id: wombat + sender-id: "1" + + cms-cert-file: biz-certs/Frank-EE.cer + cms-key-file: biz-certs/Frank-EE.key + cms-ca-cert-file: biz-certs/Bob-Root.cer + cms-cert-chain-file: [ biz-certs/Frank-CA.cer ] + + ssl-cert-file: biz-certs/Frank-EE.cer + ssl-key-file: biz-certs/Frank-EE.key + ssl-ca-cert-file: biz-certs/Bob-Root.cer + + requests: + list: + type: list + issue: + type: issue + class: 1 + sia: [ "rsync://bandicoot.invalid/some/where/" ] + revoke: + type: revoke + class: 1 + ski: "CB5K6APY-4KcGAW9jaK_cVPXKX0" + + testpoke adds one extension to the language described in APNIC's + README: the cms-cert-chain-* and ssl-cert-chain-* options, which allow + one to specify a chain of intermediate certificates to be presented in + the CMS or TLS protocol. APNIC's initial implementation required direct + knowledge of the issuing certificate (ie, it supported a maximum chain + length of one); subsequent APNIC code changes have probably relaxed + this restriction, and with luck APNIC has copied testpoke's syntax to + express chains of intermediate certificates. + __________________________________________________________________ + + + Generated on Thu Jun 12 17:41:24 2008 for RPKI Engine by doxygen + 1.5.5 diff --git a/rpkid/doc/left-right-protocol b/rpkid/doc/left-right-protocol new file mode 100644 index 00000000..ba2d447f --- /dev/null +++ b/rpkid/doc/left-right-protocol @@ -0,0 +1,477 @@ +Left-right protocol + + The left-right protocol is really two separate client/server protocols + over separate channels between the RPKI engine and the IR back end + (IRBE). + + The IRBE is the client for one of the subprotocols, the RPKI engine is + the client for the other. + +Terminology + + * IRBE: Internet Registry Back End + + * IRDB: Internet Registry Data Base + + * BPKI: Business PKI + + * RPKI: Resource PKI + +initiated by the IRBE + + This part of the protcol uses a kind of message-passing. Each object + that the RPKI engine knows about takes five messages: "create", "set", + "get", "list", and "destroy". Actions which are not just data + operations on objects are handled via an SNMP-like mechanism, as if + they were fields to be set. For example, to generate a keypair one + "sets" the "generate-keypair" field of a BSC object, even though there + is no such field in the object itself as stored in SQL. This is a bit + of a kludge, but the reason for doing it as if these were variables + being set is to allow composite operations such as creating a BSC, + populating all of its data fields, and generating a keypair, all as a + single operation. With this model, that's trivial, otherwise it's at + least two round trips. + + Fields can be set in either "create" or "set" operations, the + difference just being whether the object already exists. A "get" + operation returns all visible fields of the object. A "list" operation + returns a list containing what "get" would have returned on each of + those objects. + + Left-right protocol objects are encoded as signed CMS messages + containing XML as eContent and using an eContentType OID of id-ct-xml + (1.2.840.113549.1.9.16.1.28). These CMS messages are in turn passed as + the data for HTTPS POST operations, with an HTTP content type of + "application/x-rpki" for both the POST data and the response data. + + All operations allow an optional "tag" attribute which can be any + alphanumeric token. The main purpose of the tag attribute is to allow + batching of multiple requests into a single PDU. + +<self/> object + + A <self/> object represents one virtual RPKI engine. In simple cases + where the RPKI engine operator operates the engine only on their own + behalf, there will only be one <self/> object, representing the engine + operator's organization, but in environments where the engine operator + hosts other entities, there will be one <self/> object per hosted + entity (probably including the engine operator's own organization, + considered as a hosted customer of itself). + + Some of the RPKI engine's configured parameters and data are shared by + all hosted entities, but most are tied to a specific <self/> object. + Data which are shared by all hosted entities are referred to as + "per-engine" data, data which are specific to a particular <self/> + object are "per-self" data. + + Since all other RPKI engine objects refer to a <self/> object via a + "self_id" value, one must create a <self/> object before one can + usefully configure any other left-right protocol objects. + + Every <self/> object has a self_id attribute, which must be specified + for the "set", "get", and "destroy" actions. + + Payload data which can be configured in a <self/> object: + + * use_hsm (attribute): Whether to use a Hardware Signing Module. At + present this option has no effect, as the implementation does not + yet support HSMs. + + * crl_interval (attribute): Positive integer representing the planned + lifetime of an RPKI CRL for this <self/>, measured in seconds. + + * regen_margin (attribute): Positive integer representing how long + before expiration of an RPKI certificiate a new one should be + generated, measured in seconds. At present this only affects the + one-off EE certificates associated with ROAs. + + * bpki_cert (element): BPKI CA certificate for this <self/>. This is + used as part of the certificate chain when validating incoming TLS + and CMS messages, and should be the issuer of cross-certification + BPKI certificates used in <repository/>, <parent/>, and <child/> + objects. If the bpki_glue certificate is in use (below), the + bpki_cert certificate should be issued by the bpki_glue + certificate; otherwise, the bpki_cert certificate should be issued + by the per-engine bpki_ta certificate. + + * bpki_glue (element): Another BPKI CA certificate for this <self/>, + usually not needed. Certain pathological cross-certification cases + require a two-certificate chain due to issuer name conflicts. If + used, the bpki_glue certificate should be the issuer of the + bpki_cert certificate and should be issued by the per-engine + bpki_ta certificate; if not needed, the bpki_glue certificate + should be left unset. + + Control attributes that can be set to "yes" to force actions: + + * rekey: Start a key rollover for every RPKI CA associated with every + <parent/> object associated with this <self/> object. This is the + first phase of a key rollover operation. + + * revoke: Revoke any remaining certificates for any expired key + associated with any RPKI CA for any <parent/> object associated + with this <self/> object. This is the second (cleanup) phase for a + key rollover operation; it's separate from the first phase to leave + time for new RPKI certificates to propegate and be installed. + + * reissue: Not implemented, may be removed from protocol. Original + theory was that this operation would force reissuance of any object + with a changed key, but as that happens automatically as part of + the key rollover mechanism this operation seems unnecessary. + + * run_now: Force immediate processing for all tasks associated with + this <self/> object that would ordinarily be performed under cron. + Not currently implemented. + + * publish_world_now: Force (re)publication of every publishable + object for this <self/> object. Not currently implemented. Intended + to aid in recovery if RPKI engine and publication engine somehow + get out of sync. + +<bsc/> object + + The <bsc/> ("business signing context") object represents all the BPKI + data needed to sign outgoing CMS or HTTPS messages. Various other + objects include pointers to a <bsc/> object. Whether a particular + <self/> uses only one <bsc/> or multiple is a configuration decision + based on external requirements: the RPKI engine code doesn't care, it + just cares that, for any object representing a relationship for which + it must sign messages, there be a <bsc/> object that it can use to + produce that signature. + + Every <bsc/> object has a bsc_id, which must be specified for the + "get", "set", and "destroy" actions. Every <bsc/> also has a self_id + attribute which indicates the <self/> object with which this <bsc/> + object is associated. + + Payload data which can be configured in a <isc/> object: + + * signing_cert (element): BPKI certificate to use when generating a + signature. + + * signing_cert_crl (element): CRL which would list signing_cert if it + had been revoked. + + Control attributes that can be set to "yes" to force actions: + + * generate_keypair: Generate a new BPKI keypair and return a PKCS #10 + certificate request. The resulting certificate, once issued, should + be configured as this <bsc/> object's signing_cert. + + Additional attributes which may be specified when specifying + "generate_keypair": + + * key_type: Type of BPKI keypair to generate. "rsa" is both the + default and, at the moment, the only allowed value. + + * hash_alg: Cryptographic hash algorithm to use with this keypair. + "sha256" is both the default and, at the moment, the only allowed + value. + + * key_length: Length in bits of the keypair to be generated. "2048" + is both the default and, at the moment, the only allowed value. + + Replies to "create" and "set" actions that specify "generate-keypair" + include a <bsc_pkcs10/> element, as do replies to "get" and "list" + actions for a <bsc/> object for which a "generate-keypair" command has + been issued. The RPKI engine stores the PKCS #10 request, which allows + the IRBE to reuse the request if and when it needs to reissue the + corresponding BPKI signing certificate. + +<parent/> object + + The <parent/> object represents the RPKI engine's view of a particular + parent of the current <self/> object in the up-down protocol. Due to + the way that the resource hierarchy works, a given <self/> may obtain + resources from multiple parents, but it will always have at least one; + in the case of IANA or an RIR, the parent RPKI engine may be a trivial + stub. + + Every <parent/> object has a parent_id, which must be specified for the + "get", "set", and "destroy" actions. Every <parent/> also has a self_id + attribute which indicates the <self/> object with which this <parent/> + object is associated, a bsc_id attribute indicating the <bsc/> object + to be used when signing messages sent to this parent, and a + repository_id indicating the <repository/> object to be used when + publishing issued by the certificate issued by this parent. + + Payload data which can be configured in a <parent/> object: + + * peer_contact_uri (attribute): HTTPS URI used to contact this + parent. + + * sia_base (attribute): The leading portion of an rsync URI that the + RPKI engine should use when composing the publication URI for + objects issued by the RPKI certificate issued by this parent. + + * sender_name (attribute): Sender name to use in the up-down protocol + when talking to this parent. The RPKI engine doesn't really care + what this value is, but other implementations of the up-down + protocol do care. + + * recipient_name (attribute): Recipient name to use in the up-down + protocol when talking to this parent. The RPKI engine doesn't + really care what this value is, but other implementations of the + up-down protocol do care. + + * bpki_cms_cert (element): BPKI CMS CA certificate for this + <parent/>. This is used as part of the certificate chain when + validating incoming CMS messages If the bpki_cms_glue certificate + is in use (below), the bpki_cms_cert certificate should be issued + by the bpki_cms_glue certificate; otherwise, the bpki_cms_cert + certificate should be issued by the bpki_cert certificate in the + <self/> object. + + * bpki_cms_glue (element): Another BPKI CMS CA certificate for this + <parent/>, usually not needed. Certain pathological + cross-certification cases require a two-certificate chain due to + issuer name conflicts. If used, the bpki_cms_glue certificate + should be the issuer of the bpki_cms_cert certificate and should be + issued by the bpki_cert certificate in the <self/> object; if not + needed, the bpki_cms_glue certificate should be left unset. + + * bpki_https_cert (element): BPKI HTTPS CA certificate for this + <parent/>. This is like the bpki_cms_cert object, only used for + validating incoming TLS messages rather than CMS. + + * bpki_cms_glue (element): Another BPKI HTTPS CA certificate for this + <parent/>, usually not needed. This is like the bpki_cms_glue + certificate, only used for validating incoming TLS messages rather + than CMS. + + Control attributes that can be set to "yes" to force actions: + + * rekey: This is like the rekey command in the <self/> object, but + limited to RPKI CAs under this parent. + + * reissue: This is like the reissue command in the <self/> object, + but limited to RPKI CAs under this parent. + + * revoke: This is like the revoke command in the <self/> object, but + limited to RPKI CAs under this parent. + +<child/> object + + The <child/> object represents the RPKI engine's view of particular + child of the current <self/> in the up-down protocol. + + Every <child/> object has a parent_id, which must be specified for the + "get", "set", and "destroy" actions. Every <child/> also has a self_id + attribute which indicates the <self/> object with which this <child/> + object is associated. + + Payload data which can be configured in a <child/> object: + + * bpki_cert (element): BPKI CA certificate for this <child/>. This is + used as part of the certificate chain when validating incoming TLS + and CMS messages. If the bpki_glue certificate is in use (below), + the bpki_cert certificate should be issued by the bpki_glue + certificate; otherwise, the bpki_cert certificate should be issued + by the bpki_cert certificate in the <self/> object. + + * bpki_glue (element): Another BPKI CA certificate for this <child/>, + usually not needed. Certain pathological cross-certification cases + require a two-certificate chain due to issuer name conflicts. If + used, the bpki_glue certificate should be the issuer of the + bpki_cert certificate and should be issued by the bpki_cert + certificate in the <self/> object; if not needed, the bpki_glue + certificate should be left unset. + + Control attributes that can be set to "yes" to force actions: + + * reissue: Not implemented, may be removed from protocol. + +<repository/> object + + The <repository/> object represents the RPKI engine's view of a + particular publication repository used by the current <self/> object. + + Every <repository/> object has a repository_id, which must be specified + for the "get", "set", and "destroy" actions. Every <repository/> also + has a self_id attribute which indicates the <self/> object with which + this <repository/> object is associated. + + Payload data which can be configured in a <repository/> object: + + * peer_contact_uri (attribute): HTTPS URI used to contact this + repository. + + * bpki_cms_cert (element): BPKI CMS CA certificate for this + <repository/>. This is used as part of the certificate chain when + validating incoming CMS messages If the bpki_cms_glue certificate + is in use (below), the bpki_cms_cert certificate should be issued + by the bpki_cms_glue certificate; otherwise, the bpki_cms_cert + certificate should be issued by the bpki_cert certificate in the + <self/> object. + + * bpki_cms_glue (element): Another BPKI CMS CA certificate for this + <repository/>, usually not needed. Certain pathological + cross-certification cases require a two-certificate chain due to + issuer name conflicts. If used, the bpki_cms_glue certificate + should be the issuer of the bpki_cms_cert certificate and should be + issued by the bpki_cert certificate in the <self/> object; if not + needed, the bpki_cms_glue certificate should be left unset. + + * bpki_https_cert (element): BPKI HTTPS CA certificate for this + <repository/>. This is like the bpki_cms_cert object, only used for + validating incoming TLS messages rather than CMS. + + * bpki_cms_glue (element): Another BPKI HTTPS CA certificate for this + <repository/>, usually not needed. This is like the bpki_cms_glue + certificate, only used for validating incoming TLS messages rather + than CMS. + + At present there are no control attributes for <repository/> objects. + +<route_origin/> object + + The <route_origin/> object is a kind of prototype for a ROA. It + contains all the information needed to generate a ROA once the RPKI + engine obtains the appropriate RPKI certificates from its parent(s). + + Note that a <route_origin/> object represents a ROA to be generated on + behalf of <self/>, not on behalf of a <child/>. Thus, a hosted entity + that has no children but which does need to generate ROAs would be + represented by a hosted <self/> with no <child/> objects but one or + more <route_origin/> objects. While lumping ROA generation in with the + other RPKI engine activities may seem a little odd at first, it's a + natural consequence of the design requirement that the RPKI daemon + never transmit private keys across the network in any form; given this + requirement, the RPKI engine that holds the private keys for an RPKI + certificate must also be the engine which generates any ROAs that + derive from that RPKI certificate. + + The precise content of the <route_origin/> has changed over time as the + underlying ROA specification has changed. The current implementation as + of this writing matches what we expect to see in + draft-ietf-sidr-roa-format-03, once it is issued. In particular, note + that the exactMatch boolean from the -02 draft has been replaced by the + prefix and maxLength encoding used in the -03 draft. + + Payload data which can be configured in a <route_origin/> object: + + * as_number (attribute): Autonomous System Number (ASN) to place in + the generated ROA. A single ROA can only grant authorization to a + single ASN; multiple ASNs require multiple ROAs, thus multiple + <route_origin/> objects. + + * ipv4 (attribute): List of IPv4 prefix and maxLength values, see + below for format. + + * ipv6 (attribute): List of IPv6 prefix and maxLength values, see + below for format. + + Control attributes that can be set to "yes" to force actions: + + * suppress_publication: Not implemented, may be removed from + protocol. + + The lists of IPv4 and IPv6 prefix and maxLength values are represented + as comma-separated text strings, with no whitespace permitted. Each + entry in such a string represents a single prefix/maxLength pair. + + ABNF for these address lists: + + + <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ] + ; Where <max_prefixlen> defaults to the same + ; value as <prefixlen>. + + <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> ) + + + For example, "10.0.1.0/24-32,10.0.2.0/24", which is a shorthand form of + "10.0.1.0/24-32,10.0.2.0/24-24". + +Operations initiated by the RPKI engine + + The left-right protocol also includes queries from the RPKI engine back + to the IRDB. These queries do not follow the message-passing pattern + used in the IRBE-initiated part of the protocol. Instead, there's a + single query back to the IRDB, with a corresponding response. The CMS + and HTTPS encoding are the same as in the rest of the protocol, but the + BPKI certificates will be different as the back-queries and responses + form a separate communication channel. + +<list_resources/> messages + + The <list_resources/> query and response allow the RPKI engine to ask + the IRDB for information about resources assigned to a particular + child. The query must include both a "self_id" attribute naming the + <self/> that is making the request and also a "child_id" attribute + naming the child that is the subject of the query. The query and + response also allow an optional "tag" attribute of the same form used + elsewhere in this protocol, to allow batching. + + A <list_resources/> response includes the following attributes, along + with the tag (if specified), self_id, and child_id copied from the + request: + + * valid_until: A timestamp indicating the date and time at which + certificates generated by the RPKI engine for these data should + expire. The timestamp is expressed as an XML xsd:dateTime, must be + expressed in UTC, and must carry the "Z" suffix indicating UTC. + + * subject_name: An optional text string naming the child. Not + currently used. + + * asn: A list of autonomous sequence numbers, expressed as a + comma-separated sequence of decimal integers with no whitespace. + + * ipv4: A list of IPv4 address prefixes and ranges, expressed as a + comma-separated list of prefixes and ranges with no whitespace. See + below for format details. + + * ipv6: A list of IPv6 address prefixes and ranges, expressed as a + comma-separated list of prefixes and ranges with no whitespace. See + below for format details. + + Entries in a list of address prefixes and ranges can be either + prefixes, which are written in the usual address/prefixlen notation, or + ranges, which are expressed as a pair of addresses denoting the + beginning and end of the range, written in ascending order separated by + a single "-" character. This format is superficially similar to the + format used for prefix and maxLength values in the <route_origin/> + object, but the semantics differ: note in particular that + <route_origin/> objects don't allow ranges, while <list_resources/> + messages don't allow a maxLength specification. + +Error handling + + Error in this protocol are handled at two levels. + + Since all messages in this protocol are conveyed over HTTPS + connections, basic errors are indicated via the HTTP response code. 4xx + and 5xx responses indicate that something bad happened. Errors that + make it impossible to decode a query or encode a response are handled + in this way. + + Where possible, errors will result in a <report_error/> message which + takes the place of the expected protocol response message. + <report_error/> messages are CMS-signed XML messages like the rest of + this protocol, and thus can be archived to provide an audit trail. + + <report_error/> messages only appear in replies, never in queries. The + <report_error/> message can appear on either the "forward" (IRBE as + client of RPKI engine) or "back" (RPKI engine as client of IRDB) + communication channel. + + The <report_error/> message includes an optional "tag" attribute to + assist in matching the error with a particular query when using + batching, and also includes a "self_id" attribute indicating the + <self/> that issued the error. + + The error itself is conveyed in the error_code (attribute). The value + of this attribute is a token indicating the specific error that + occurred. At present this will be the name of a Python exception; the + production version of this protocol will nail down the allowed error + tokens here, probably in the RelaxNG schema. + + The body of the <report_error/> element itself is an optional text + string; if present, this is debugging information. At present this + capabilty is not used, debugging information goes to syslog. + __________________________________________________________________ + + + Generated on Thu Jun 12 17:41:25 2008 for RPKI Engine by doxygen + 1.5.5 diff --git a/rpkid/doc/publication-protocol b/rpkid/doc/publication-protocol new file mode 100644 index 00000000..c6bf4c13 --- /dev/null +++ b/rpkid/doc/publication-protocol @@ -0,0 +1,227 @@ +Publication protocol + + The publication protocol is really two separate client/server + protocols, between different parties. + + The first is a configuration protocol for the IRBE to use to configure + the publication engine, the second is the interface by which authorized + clients request publication of specific objects. + + Much of the architecture of the publication protocol is borrowed from + the left-right protocol: like the left-right protocol, the publication + protocol uses CMS-wrapped XML over HTTPS with the same eContentType OID + and the same HTTPS content-type, and the overall style of the XML + messages is very similar to the left-right protocol. All operations + allow an optional "tag" attribute to allow batching. + + The publication engine operates a single HTTPS server which serves both + of these subprotocols. The two subprotocols share a single server port, + but use distinct URLs. + +Terminology + + * IRBE: Internet Registry Back End + + * IRDB: Internet Registry Data Base + + * BPKI: Business PKI + + * RPKI: Resource PKI + +Publication control subprotocol + + The control subprotocol reuses the message-passing design of the + left-right protocol. Configured objects support the "create", "set", + "get", "list", and "destroy" actions, or a subset thereof when the full + set of actions doesn't make sense. + +<config/> object + + The <config/> object allows configuration of data that apply to the + entire publication server rather than a particular client. + + There is exactly one <config/> object in the publication server, and it + only supports the "set" and "get" actions -- it cannot be created or + destroyed. + + Payload data which can be configured in a <config/> object: + + * bpki_crl (element): This is the BPKI CRL used by the publication + server when signing the CMS wrapper on responses in the publication + subprotocol. As the CRL must be updated at regular intervals, it's + not practical to restart the publication server when the BPKI CRL + needs to be updated. Fortunately, the BPKI model doesn't require + use of a BPKI CRL between the IRBE and the publication server, so + we can use the publication control subprotocol to update the BPKI + CRL. + +<client/> object + + The <client/> object represents one client authorized to use the + publication server. + + The <client/> object supports the full set of "create", "set", "get", + "list", and "destroy" actions. Each client has a "client_id" attribute, + which is used in responses and must be specified in "set", "get", or + "destroy" actions. + + Payload data which can be configured in a <client/> object: + + * base_uri (attribute): This is the base URI below which this client + is allowed to publish data. The publication server may impose + additional constraints in the case of a child publishing beneath + its parent. + + * bpki_cert (element): BPKI CA certificate for this <client/>. This + is used as part of the certificate chain when validating incoming + TLS and CMS messages. If the bpki_glue certificate is in use + (below), the bpki_cert certificate should be issued by the + bpki_glue certificate; otherwise, the bpki_cert certificate should + be issued by the publication engine's bpki_ta certificate. + + * bpki_glue (element): Another BPKI CA certificate for this + <client/>, usually not needed. Certain pathological + cross-certification cases require a two-certificate chain due to + issuer name conflicts. If used, the bpki_glue certificate should be + the issuer of the bpki_cert certificate and should be issued by the + publication engine's bpki_ta certificate; if not needed, the + bpki_glue certificate should be left unset. + +Publication subprotocol + + The publication subprotocol is structured somewhat differently from the + publication control protocol. Objects in the publication subprotocol + represent objects to be published or objects to be withdrawn from + publication. Each kind of object supports two actions: "publish" and + "withdraw". In each case the XML element representing hte object to be + published or withdrawn has a "uri" attribute which contains the + publication URI. For "publish" actions, the XML element body contains + the DER object to be published, encoded in Base64; for "withdraw" + actions, the XML element body is empty. + + In theory, the detailed access control for each kind of object might be + different. In practice, as of this writing, access control for all + objects is a simple check that the client's "base_uri" is a leading + substring of the publication URI. Details of why access control might + need to become more complicated are discussed in a later section. + +<certificate/> object + + The <certificate/> object represents an RPKI certificate to be + published or withdrawn. + +<crl/> object + + The <crl/> object represents an RPKI CRL to be published or withdrawn. + +<manifest/> object + + The <manifest/> object represents an RPKI publication manifest to be + published or withdrawn. + + Note that part of the reason for the batching support in the + publication protocol is because every publication or withdrawal action + requires a new manifest, thus every publication or withdrawal action + will involve at least two objects. + +<roa/> object + + The <roa/> object represents a ROA to be published or withdrawn. + +Error handling + + Error in this protocol are handled at two levels. + + Since all messages in this protocol are conveyed over HTTPS + connections, basic errors are indicated via the HTTP response code. 4xx + and 5xx responses indicate that something bad happened. Errors that + make it impossible to decode a query or encode a response are handled + in this way. + + Where possible, errors will result in a <report_error/> message which + takes the place of the expected protocol response message. + <report_error/> messages are CMS-signed XML messages like the rest of + this protocol, and thus can be archived to provide an audit trail. + + <report_error/> messages only appear in replies, never in queries. The + <report_error/> message can appear on either the "forward" (IRBE as + client of RPKI engine) or "back" (RPKI engine as client of IRDB) + communication channel. + + The <report_error/> message includes an optional "tag" attribute to + assist in matching the error with a particular query when using + batching, and also includes a "self_id" attribute indicating the + <self/> that issued the error. + + The error itself is conveyed in the error_code (attribute). The value + of this attribute is a token indicating the specific error that + occurred. At present this will be the name of a Python exception; the + production version of this protocol will nail down the allowed error + tokens here, probably in the RelaxNG schema. + + The body of the <report_error/> element itself is an optional text + string; if present, this is debugging information. At present this + capabilty is not used, debugging information goes to syslog. + +Additional access control considerations. + + As detailed above, the publication protocol is trivially simple. This + glosses over two bits of potential complexity: + + * In the case where parent and child are sharing a repository, we'd + like to nest child under parent, because testing has demonstrated + that even on relatively slow hardware the delays involved in + setting up separate rsync connections tend to dominate + synchronization time for relying parties. + + * The repository operator might also want to do some checks to assure + itself that what it's about to allow the RPKI engine to publish is + not dangerous toxic waste. + + The up-down protocol includes a mechanism by which a parent can suggest + a publication URI to each of its children. The children are not + required to accept this hint, and the children must make separate + arrangements with the repository operator (who might or might not be + the same as the entity that hosts the children's RPKI engine + operations) to use the suggested publication point, but if everything + works out, this allows children to nest cleanly under their parents + publication points, which helps reduce synchronization time for relying + parties. + + In this case, one could argue that the publication server is + responsible for preventing one of its clients (the child in the above + description) from stomping on data published by another of its clients + (the parent in the above description). This goes beyond the basic + access check and requires the publication server to determine whether + the parent has given its consent for the child to publish under the + parent. Since the RPKI certificate profile requires the child's + publication point to be indicated in an SIA extension in a certificate + issued by the parent to the child, the publication engine can infer + this permission from the parent's issuance of a certificate to the + child. Since, by definition, the parent also uses this publication + server, this is an easy check, as the publication server should already + have the parent's certificate available by the time it needs to check + the child's certificate. + + The previous paragraph only covers a "publish" action for a + <certificate/> object. For "publish" actions on other objects, the + publication server would need to trace permission back to the + certificate issued by the parent; for "withdraw" actions, the + publication server would have to perform the same checks it would + perform for a "publish" action, using the current published data before + withdrawing it. The latter in turn implies an ordering constraint on + "withdraw" actions in order to preserve the data necessary for these + access control decisions; as this may prove impractical, the + publication server may probably need to make periodic sweeps over its + published data looking for orphaned objects, but that's probably a good + idea anyway. + + Note that, in this publication model, any agreement that the repository + makes to publish the RPKI engine's output is conditional upon the + object to be published passing whatever access control checks the + publication server imposes. + __________________________________________________________________ + + + Generated on Thu Jun 12 17:41:25 2008 for RPKI Engine by doxygen + 1.5.5 |