diff options
Diffstat (limited to 'rpkid/doc/Publication')
| -rw-r--r-- | rpkid/doc/Publication | 408 |
1 files changed, 209 insertions, 199 deletions
diff --git a/rpkid/doc/Publication b/rpkid/doc/Publication index e0f1346c..57d8e8aa 100644 --- a/rpkid/doc/Publication +++ b/rpkid/doc/Publication @@ -1,224 +1,234 @@ -Publication protocol - 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. +****** Publication protocol ****** - 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 protocol is really two separate client/server protocols, +between different parties. - 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 to allow demultiplexing. +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. -Terminology +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. - * IRBE: Internet Registry Back End +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 to allow demultiplexing. - * IRDB: Internet Registry Data Base - * BPKI: Business PKI +***** Terminology ***** - * RPKI: Resource PKI -Publication control subprotocol +* IRBE: Internet Registry Back End - 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 +* IRDB: Internet Registry Data Base - 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. +* BPKI: Business PKI - 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. +* RPKI: Resource PKI -<client/> object - The <client/> object represents one client authorized to use the - publication server. +***** Publication control subprotocol ***** - 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. +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. - 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. +**** <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 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 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. + - * 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 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. - __________________________________________________________________ - - - Generated on Fri Apr 16 17:28:16 2010 for RPKI Engine by doxygen - 1.6.3 |