diff options
Diffstat (limited to 'rpkid/doc/Publication')
| -rw-r--r-- | rpkid/doc/Publication | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/rpkid/doc/Publication b/rpkid/doc/Publication new file mode 100644 index 00000000..cf89abde --- /dev/null +++ b/rpkid/doc/Publication @@ -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 18:21:05 2008 for RPKI Engine by doxygen + 1.5.5 |