These are the production-side RPKI tools, for Internet Registries (RIRs, LIRs, etc). See rcynic/README for relying party tools.
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.cross_certify.py:
A BPKI cross-certification tool.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.Basic operation consists of creating the appropriate MySQL databases, starting rpkid, pubd, 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 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 must 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 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.bpki-ta
: Name of file containing BPKI trust anchor. All BPKI certificate verification within rpkid traces back to this trust anchor.rpkid-cert
: Name of file containing rpkid's own BPKI EE certificate.rpkid-key
: Name of file containing RSA key corresponding to rpkid-cert.irbe-cert
: Name of file containing BPKI certificate used by IRBE when talking to rpkid.irdb-cert
: Name of file containing BPKI certificate used by irdbd.irdb-url
: Service URL for irdbd. Must be a https:// URL.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.pubd is separate from rpkid for two reasons:
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/".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:
bpki-ta
: Name of file containing BPKI trust anchor. All BPKI certificate validation in rootd traces back to this trust anchor.rootd-bpki-cert
: Name of file containing rootd's own BPKI certificate.rootd-bpki-key
: Name of file containing RSA key corresponding to rootd-bpki-cert.rootd-bpki-crl
: Name of file containing BPKI CRL that would cover rootd-bpki-cert had it been revoked.child-bpki-cert
: Name of file containing BPKI certificate for rootd's one and only child (RPKI engine to which rootd issues an RPKI certificate).server-host
: Hostname or IP address on which to listen for HTTPS connections. Default is localhost.server-port
: TCP port on which to listen for HTTPS connections.rpki-root-key
: Name of file containing RSA key to use in signing resource certificates.rpki-root-cert
: Name of file containing self-signed root resource certificate corresponding to rpki-root-key.rpki-root-dir
: Name of directory where rootd should write RPKI subject certificate, manifest, and CRL.rpki-subject-cert
: Name of file that rootd should use to save the one and only certificate it issues. Default is "Subroot.cer".rpki-root-crl
: Name of file to which rootd should save its RPKI CRL. Default is "Root.crl".rpki-root-manifest
: Name of file to which rootd should save its RPKI manifest. Default is "Root.mnf".rpki-subject-pkcs10
: 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 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.bpki-ta
: Name of file containing BPKI trust anchor. All BPKI certificate validation in irdbd traces back to this trust anchor.irdbd-cert
: Name of file containing irdbd's own BPKI certificate.irdbd-key
: Name of file containing RSA key corresponding to irdbd-cert.rpkid-cert
: Name of file containing certificate used the one and only by rpkid instance authorized to contact this irdbd instance.https-url
: Service URL for irdbd. Must be a https:// URL.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 protocols themselves.
At present the user is assumed to be able to read the (XML) left-right and publication protocol messages, and with one exception, irdbd-cli makes no attempt to interpret the responses other than to check for signature and syntax 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 (BPKI in order to issue signing certs corresponding to newly generated business keys.
Command line IR back-end control program for rpkid and pubd. $Id: irbe_cli.py 2571 2009-07-04 20:13:22Z sra $ Copyright (C) 2009 Internet Systems Consortium ("ISC") Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Portions copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND ARIN DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ARIN BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Usage: # Top-level options: --config= --help --pem_out= --verbose # left-right protocol: self --action= --tag= --self_handle= --crl_interval= --regen_margin= --bpki_cert= --bpki_glue= --rekey --reissue --revoke --run_now --publish_world_now child --action= --tag= --self_handle= --child_handle= --bsc_handle= --bpki_cert= --bpki_glue= --reissue repository --action= --tag= --self_handle= --repository_handle= --bsc_handle= --peer_contact_uri= --bpki_cms_cert= --bpki_cms_glue= --bpki_https_cert= --bpki_https_glue= parent --action= --tag= --self_handle= --parent_handle= --bsc_handle= --repository_handle= --peer_contact_uri= --sia_base= --sender_name= --recipient_name= --bpki_cms_cert= --bpki_cms_glue= --bpki_https_cert= --bpki_https_glue= --rekey --reissue --revoke bsc --action= --tag= --self_handle= --bsc_handle= --key_type= --hash_alg= --key_length= --signing_cert= --signing_cert_crl= --generate_keypair # publication protocol: certificate --action= --tag= --client_handle= --uri= roa --action= --tag= --client_handle= --uri= manifest --action= --tag= --client_handle= --uri= client --action= --tag= --client_handle= --base_uri= --bpki_cert= --bpki_glue= config --action= --tag= --bpki_crl= crl --action= --tag= --client_handle= --uri=
Global options (--config
, --help
, --pem_out
) come first, then zero or more commands (parent
, repository
, self
, child
, bsc
, config
, client
), each followed by its own set of options. The commands map to elements in the protocols, and the command-specific options map to attributes or subelements for those commands.
--tag
is an optional arbitrary tag (think IMAP) to simplify matching up replies with batched queries.
--*_handle
options refer to object primary keys.
The remaining options are specific to the particular commands, and follow directly from the protocol specifications.
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_cli.conf, start irbe_cli 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:
rpkid-bpki-ta
: Name of file containing BPKI trust anchor to use when authenticating messages from rpkid.rpkid-irbe-cert
: Name of file containing BPKI certificate irbe_cli should use when talking to rpkid.rpkid-irbe-key
: Name of file containing RSA key corresponding to rpkid-irbe-cert.rpkid-cert
: Name of file containing rpkid's BPKI certificate.rpkid-url
: Service URL for rpkid. Must be a https:// URL.pubd-bpki-ta
: Name of file containing BPKI trust anchor to use when authenticating messages from pubd.pubd-irbe-key
: Name of file containing RSA key corresponding to pubd-irbe-cert.pubd-cert
: Name of file containing pubd's BPKI certificate.pubd-url
: Service URL for pubd. Must be a https:// URL.
python cross_certify.py { -i | --in } input_cert { -c | --ca } issuing_cert { -k | --key } issuing_cert_key { -s | --serial } serial_filename [ { -h | --help } ] [ { -o | --out } filename ] [ { -l | --lifetime } timedelta ]
Options in the "[irbe_cli]" section:
bpki-ta
: Name of file containing BPKI trust anchor.irbe-cert
: Name of file containing BPKI certificate irbe-setup should use.irbe-key
: Name of file containing RSA key corresponding to irbe-cert.rpkid-cert
: Name of file containing rpkid's BPKI certificate.https-url
: Service URL for rpkid. Must be a https:// URL.
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.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:
bpki-ta
: Name of file containing BPKI trust anchor.irbe-cert
: Name of file containing cronjob.py's BPKI certificate.https-key
: Name of file containing RSA key corresponding to irbe-cert.rpkid-cert
: Name of file containing rpkid's BPKI certificate.https-url
: Service URL for rpkid. Must be a https:// URL.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.
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.
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".
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.