$Id$ The design of rpkid and friends assumes that certain tasks can be thrown over the wall to the registry's back end operation. This was a deliberate design decision to allow rpkid et al to remain independent of existing database schema, business PKIs, and so forth that a registry might already have. All very nice, but it leaves someone who just wants to test the tools or who has no existing back end with a fairly large programming project. The tools in this directory attempt to fill that gap. This is a basic implementation of what a registry back end would need to use rpkid and friends. These tools do not use every available option, nor are they necessarily as efficient as possible. Large registries will almost certainly want to roll their own tools, perhaps using these as a starting point. Nevertheless, we hope that these tools will at least provide a useful example. The primary tools here consist of two Python programs: myrpki.py and myirbe.py. The first is for use by any entity that needs resources allocated via the RPKI system, the second is for use by entities that actually run a copy of rpkid and its several supporting programs. The basic idea here is that a user who has resources maintains a set of .csv files containing a text representation of the data needed by the back-end, along with a configuration file containing other parameters. The intent is that these be very simple files that are easy to generate either by hand or as a dump from relational database, awk script, whatever works in your environment. Given these files, the user then runs the myrpki.py script to extract the relevant information and encode everything about its back end state into a single .xml file, which the script writes out to disk. The user then conveys this .xml file via some convenient means (PGP-signed mail, USB key, dogsled) to the operator of the rpkid engine that will perform RPKI services on behalf of the user. The rpkid operator collects these .xml files from all the users it hosts, and feeds them all into the myirbe.py script, which uses the data in the .xml files to populate the IRDB, create objects in rpkid and pubd via the left-right and publication protocols, etcetera. The script rewrites its input .xml files to contain any updated information (eg, PKCS #10 requests for business signing context certificates), so that the .xml file once again contains everything that must be communicated between the rpkid operator and hosted user. The rpkid operator ships the updated .xml back to the user, who then runs the myrpki.py script again to perform any necessary actions (eg, issuing business signing context certificates given the PKCS #10 request sent by myirbe.py), resulting in another update to the .xml file, which the user then ships back to the rpkid operator. This cycle repeats until nothing further needs to be changed. Note that, as certificates and CRLs have expiration and nextUpdate values, a low-level cycle of updates passing between resource holder and rpkid operator will be necessary as a part of steady state operation. (The current version of these tools does not yet regenerate these expiring objects, but fixing this is a relatively minor matter.) Since we assume that anybody who bothers to run rpkid is also a resource holder, myirbe.py and myrpki.py can use the same configuration file, and myirbe.py will run myrpki.py automatically if the [myrpki] section of the config file is present. The third important file in this system is the configuration file for myrpk.py and myirbe.py. This contains a number of sections, some of which are for these scripts, others of which are for the OpenSSL command line tool, which these scripts use do most of the certificate work. The config file is (well, should and will be) commented to explain the various parameters. myrpki.py deliberately does not use any libraries other than the ones that ship with Python 2.5; in particular, it does not require any of the other Python RPKI code. This is deliberate, to minimize portability issues for hosted users. It does require a reasonably current version of the OpenSSL command line tool, but the version that is built as a side effect of building the rcynic relying party tool is adaquate if the system copy of this tool isn't. The .csv files read by myrpki.py can be anything that the Python "csv" library understands. By default, they're in tab-delimited format (because the author finds that much easier to read than comma-delimited format), but this can be changed to fit local needs. A number of the fields in the config or CSV files involve certificates. Some of these are built automatically, others must be imported so that the scripts can cross-certify them. The certificates you need to import are all self-signed BPKI certs generated by other entities, you import them by specifying the name of a file where you stored the BPKI certificate in question (in OpenSSL "PEM" format). Keep reading, and don't panic. The default config file name is myrpki.conf. === (Current) content of the [myrpki] section of the config file: - handle Handle of this entity, used in left-right and publication protocols, etc. You need to set this one. Syntax is an identifier (letters, digits, hyphen, underscore -- no whitespace or funny characters). - repository_bpki_certificate Where to find the repository's BPKI certificate, so we can cross certify it. You'll need to set this. - roa_csv Names of various CSV files, ok as-is children_csv parents_csv prefix_csv asn_csv - xml_filename Name of XML input/output file, ok as-is - bpki_directory Where this entity's BPKI CA should live, ok as-is === (Current) content of the [myirbe] section of the config file: - irdbd_conf Where to find the config file for irdbd. It's ok for this to loop back to the same config file (ie, for the value of this parameter to be myrpki.conf); it's a separate parameter because the [irdbd] config section contains an SQL password, which you might want hidden. - rpkid_ca_directory Directories for several CAs, ok as-is pubd_ca_directory rootd_ca_directory - rsync_base rsync:// URI to use as base of publication space. - pubd_base https:// URL base for contacting pubd - rpkid_base https:// URL base for contacting rpkid === CSV file formats: - roas: /- - children: - prefix: / or: - - asn: - parent: === See the examples/ subdirectory for examples of these files. [Still need to doc [myirbe] parameters, and need better BPKI doc] Sketch towards a simple description of the BPKI (sic). This started out as notes to myself during a redesign, and needs rewriting. Hosted (myrpki) entity needs: - Self-signed BPKI root (doesn't really need to be self-signed, nobody else will care, but self-signed is simplest for our purposes). This is what we've been calling the "self" cert in testbed.py. - BSC EE issued by self-signed root. - Cross-certs of every foreign entity (parent, child, or pubd): these are CA certs with pathLenConstraint 0. Input for this cross-cert is self-signed (or whatever) from foreign entity, output is pathLenConstraint 0 CA cert issued by myrpki entity's own self-signed root. Hosting rpkid (myirbe) needs: - Self-signed BPKI root - BSC EE certs for rpkid, irdbd, irbe_cli, etc - For each hosted entity (including self-hosting): Cross-cert of hosted entity's root, issued by rpkid root: CA cert with pathLenConstraint 1 In theory that's all that's required, everything else is handled through the hosted entity's cert chain. pubd needs: - Self signed root (might share with rpkid but let's keep it separate conceptually) - BSC EE certs for pubd and irbe_cli - For each client entity of pubd: Cross-cert of client entity's self cert (pathLenConstraint 0). This should allow pubd to verify clients' BSC EE certs without getting into transitive CA relationships. rootd (when applicable at all) needs: - Self-signed root - BSC EE cert for talking up-down (server) with one and only child - Cross-cert (pathLenConstraint 0) of one and only child's self cert.