diff options
Diffstat (limited to 'doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication')
| -rw-r--r-- | doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication new file mode 100644 index 00000000..fedc0889 --- /dev/null +++ b/doc/wiki-dump/doc%2FRPKI%2FCA%2FProtocols%2FPublication @@ -0,0 +1,216 @@ += The Publication Protocol = + +[[TracNav(doc/RPKI/TOC)]] +[[PageOutline]] + +The publication protocol is really two separate client/server +protocols, between different parties. The first is a configuration +protocol for an IRBE to use to configure a 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 [[LeftRight|left-right protocol]]: like the left-right +protocol, the publication protocol uses CMS-wrapped XML over HTTP with +the same eContentType OID and the same HTTP 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 HTTP server which serves +both of these subprotocols. The two subprotocols share a single +server port, but use distinct URLs to allow demultiplexing. + +== 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. 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_handle" +attribute, which is used in responses and must be specified in "create", "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 HTTP +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 in both the +control and publication subprotocols. + +The <report_error/> message includes an optional //tag// attribute to +assist in matching the error with a particular query when using +batching. + +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. |