diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/left-right-protocol | 972 | ||||
| -rw-r--r-- | docs/publication-protocol | 421 |
2 files changed, 647 insertions, 746 deletions
diff --git a/docs/left-right-protocol b/docs/left-right-protocol index e8684fdc..1c85d680 100644 --- a/docs/left-right-protocol +++ b/docs/left-right-protocol @@ -1,559 +1,477 @@ --*- Text -*- -$Id$ +Left-right protocol + + The left-right protocol is really two separate client/server protocols + over separate channels between the RPKI engine and the IR back end + (IRBE). + + The IRBE is the client for one of the subprotocols, the RPKI engine is + the client for the other. + +Terminology + + * IRBE: Internet Registry Back End + + * IRDB: Internet Registry Data Base + + * BPKI: Business PKI + + * RPKI: Resource PKI + +initiated by the IRBE + + This part of the protcol uses a kind of message-passing. Each object + that the RPKI engine knows about takes five messages: "create", "set", + "get", "list", and "destroy". Actions which are not just data + operations on objects are handled via an SNMP-like mechanism, as if + they were fields to be set. For example, to generate a keypair one + "sets" the "generate-keypair" field of a BSC object, even though there + is no such field in the object itself as stored in SQL. This is a bit + of a kludge, but the reason for doing it as if these were variables + being set is to allow composite operations such as creating a BSC, + populating all of its data fields, and generating a keypair, all as a + single operation. With this model, that's trivial, otherwise it's at + least two round trips. + + Fields can be set in either "create" or "set" operations, the + difference just being whether the object already exists. A "get" + operation returns all visible fields of the object. A "list" operation + returns a list containing what "get" would have returned on each of + those objects. + + Left-right protocol objects are encoded as signed CMS messages + containing XML as eContent and using an eContentType OID of id-ct-xml + (1.2.840.113549.1.9.16.1.28). These CMS messages are in turn passed as + the data for HTTPS POST operations, with an HTTP content type of + "application/x-rpki" for both the POST data and the response data. + + All operations allow an optional "tag" attribute which can be any + alphanumeric token. The main purpose of the tag attribute is to allow + batching of multiple requests into a single PDU. + +<self/> object + + A <self/> object represents one virtual RPKI engine. In simple cases + where the RPKI engine operator operates the engine only on their own + behalf, there will only be one <self/> object, representing the engine + operator's organization, but in environments where the engine operator + hosts other entities, there will be one <self/> object per hosted + entity (probably including the engine operator's own organization, + considered as a hosted customer of itself). + + Some of the RPKI engine's configured parameters and data are shared by + all hosted entities, but most are tied to a specific <self/> object. + Data which are shared by all hosted entities are referred to as + "per-engine" data, data which are specific to a particular <self/> + object are "per-self" data. + + Since all other RPKI engine objects refer to a <self/> object via a + "self_id" value, one must create a <self/> object before one can + usefully configure any other left-right protocol objects. + + Every <self/> object has a self_id attribute, which must be specified + for the "set", "get", and "destroy" actions. + + Payload data which can be configured in a <self/> object: + + * use_hsm (attribute): Whether to use a Hardware Signing Module. At + present this option has no effect, as the implementation does not + yet support HSMs. + + * crl_interval (attribute): Positive integer representing the planned + lifetime of an RPKI CRL for this <self/>, measured in seconds. + + * regen_margin (attribute): Positive integer representing how long + before expiration of an RPKI certificiate a new one should be + generated, measured in seconds. At present this only affects the + one-off EE certificates associated with ROAs. + + * bpki_cert (element): BPKI CA certificate for this <self/>. This is + used as part of the certificate chain when validating incoming TLS + and CMS messages, and should be the issuer of cross-certification + BPKI certificates used in <repository/>, <parent/>, and <child/> + objects. 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 per-engine bpki_ta certificate. + + * bpki_glue (element): Another BPKI CA certificate for this <self/>, + 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 per-engine + bpki_ta certificate; if not needed, the bpki_glue certificate + should be left unset. + + Control attributes that can be set to "yes" to force actions: + + * rekey: Start a key rollover for every RPKI CA associated with every + <parent/> object associated with this <self/> object. This is the + first phase of a key rollover operation. + + * revoke: Revoke any remaining certificates for any expired key + associated with any RPKI CA for any <parent/> object associated + with this <self/> object. This is the second (cleanup) phase for a + key rollover operation; it's separate from the first phase to leave + time for new RPKI certificates to propegate and be installed. + + * reissue: Not implemented, may be removed from protocol. Original + theory was that this operation would force reissuance of any object + with a changed key, but as that happens automatically as part of + the key rollover mechanism this operation seems unnecessary. + + * run_now: Force immediate processing for all tasks associated with + this <self/> object that would ordinarily be performed under cron. + Not currently implemented. + + * publish_world_now: Force (re)publication of every publishable + object for this <self/> object. Not currently implemented. Intended + to aid in recovery if RPKI engine and publication engine somehow + get out of sync. + +<bsc/> object + + The <bsc/> ("business signing context") object represents all the BPKI + data needed to sign outgoing CMS or HTTPS messages. Various other + objects include pointers to a <bsc/> object. Whether a particular + <self/> uses only one <bsc/> or multiple is a configuration decision + based on external requirements: the RPKI engine code doesn't care, it + just cares that, for any object representing a relationship for which + it must sign messages, there be a <bsc/> object that it can use to + produce that signature. + + Every <bsc/> object has a bsc_id, which must be specified for the + "get", "set", and "destroy" actions. Every <bsc/> also has a self_id + attribute which indicates the <self/> object with which this <bsc/> + object is associated. + + Payload data which can be configured in a <isc/> object: + + * signing_cert (element): BPKI certificate to use when generating a + signature. + + * signing_cert_crl (element): CRL which would list signing_cert if it + had been revoked. + + Control attributes that can be set to "yes" to force actions: + + * generate_keypair: Generate a new BPKI keypair and return a PKCS #10 + certificate request. The resulting certificate, once issued, should + be configured as this <bsc/> object's signing_cert. + + Additional attributes which may be specified when specifying + "generate_keypair": + + * key_type: Type of BPKI keypair to generate. "rsa" is both the + default and, at the moment, the only allowed value. + + * hash_alg: Cryptographic hash algorithm to use with this keypair. + "sha256" is both the default and, at the moment, the only allowed + value. + + * key_length: Length in bits of the keypair to be generated. "2048" + is both the default and, at the moment, the only allowed value. + + Replies to "create" and "set" actions that specify "generate-keypair" + include a <bsc_pkcs10/> element, as do replies to "get" and "list" + actions for a <bsc/> object for which a "generate-keypair" command has + been issued. The RPKI engine stores the PKCS #10 request, which allows + the IRBE to reuse the request if and when it needs to reissue the + corresponding BPKI signing certificate. + +<parent/> object + + The <parent/> object represents the RPKI engine's view of a particular + parent of the current <self/> object in the up-down protocol. Due to + the way that the resource hierarchy works, a given <self/> may obtain + resources from multiple parents, but it will always have at least one; + in the case of IANA or an RIR, the parent RPKI engine may be a trivial + stub. + + Every <parent/> object has a parent_id, which must be specified for the + "get", "set", and "destroy" actions. Every <parent/> also has a self_id + attribute which indicates the <self/> object with which this <parent/> + object is associated, a bsc_id attribute indicating the <bsc/> object + to be used when signing messages sent to this parent, and a + repository_id indicating the <repository/> object to be used when + publishing issued by the certificate issued by this parent. + + Payload data which can be configured in a <parent/> object: + + * peer_contact_uri (attribute): HTTPS URI used to contact this + parent. + + * sia_base (attribute): The leading portion of an rsync URI that the + RPKI engine should use when composing the publication URI for + objects issued by the RPKI certificate issued by this parent. + + * sender_name (attribute): Sender name to use in the up-down protocol + when talking to this parent. The RPKI engine doesn't really care + what this value is, but other implementations of the up-down + protocol do care. + + * recipient_name (attribute): Recipient name to use in the up-down + protocol when talking to this parent. The RPKI engine doesn't + really care what this value is, but other implementations of the + up-down protocol do care. + + * bpki_cms_cert (element): BPKI CMS CA certificate for this + <parent/>. This is used as part of the certificate chain when + validating incoming CMS messages If the bpki_cms_glue certificate + is in use (below), the bpki_cms_cert certificate should be issued + by the bpki_cms_glue certificate; otherwise, the bpki_cms_cert + certificate should be issued by the bpki_cert certificate in the + <self/> object. + + * bpki_cms_glue (element): Another BPKI CMS CA certificate for this + <parent/>, usually not needed. Certain pathological + cross-certification cases require a two-certificate chain due to + issuer name conflicts. If used, the bpki_cms_glue certificate + should be the issuer of the bpki_cms_cert certificate and should be + issued by the bpki_cert certificate in the <self/> object; if not + needed, the bpki_cms_glue certificate should be left unset. + + * bpki_https_cert (element): BPKI HTTPS CA certificate for this + <parent/>. This is like the bpki_cms_cert object, only used for + validating incoming TLS messages rather than CMS. + + * bpki_cms_glue (element): Another BPKI HTTPS CA certificate for this + <parent/>, usually not needed. This is like the bpki_cms_glue + certificate, only used for validating incoming TLS messages rather + than CMS. + + Control attributes that can be set to "yes" to force actions: + + * rekey: This is like the rekey command in the <self/> object, but + limited to RPKI CAs under this parent. + + * reissue: This is like the reissue command in the <self/> object, + but limited to RPKI CAs under this parent. + + * revoke: This is like the revoke command in the <self/> object, but + limited to RPKI CAs under this parent. + +<child/> object + + The <child/> object represents the RPKI engine's view of particular + child of the current <self/> in the up-down protocol. + + Every <child/> object has a parent_id, which must be specified for the + "get", "set", and "destroy" actions. Every <child/> also has a self_id + attribute which indicates the <self/> object with which this <child/> + object is associated. + + Payload data which can be configured in a <child/> object: + + * bpki_cert (element): BPKI CA certificate for this <child/>. 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 bpki_cert certificate in the <self/> object. + + * bpki_glue (element): Another BPKI CA certificate for this <child/>, + 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 bpki_cert + certificate in the <self/> object; if not needed, the bpki_glue + certificate should be left unset. + + Control attributes that can be set to "yes" to force actions: + + * reissue: Not implemented, may be removed from protocol. + +<repository/> object -Copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") + The <repository/> object represents the RPKI engine's view of a + particular publication repository used by the current <self/> object. -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. + Every <repository/> object has a repository_id, which must be specified + for the "get", "set", and "destroy" actions. Every <repository/> also + has a self_id attribute which indicates the <self/> object with which + this <repository/> object is associated. -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. + Payload data which can be configured in a <repository/> object: -@section Terminology + * peer_contact_uri (attribute): HTTPS URI used to contact this + repository. -@li @em IRBE: Internet Registry Back End + * bpki_cms_cert (element): BPKI CMS CA certificate for this + <repository/>. This is used as part of the certificate chain when + validating incoming CMS messages If the bpki_cms_glue certificate + is in use (below), the bpki_cms_cert certificate should be issued + by the bpki_cms_glue certificate; otherwise, the bpki_cms_cert + certificate should be issued by the bpki_cert certificate in the + <self/> object. -@li @em IRDB: Internet Registry Data Base + * bpki_cms_glue (element): Another BPKI CMS CA certificate for this + <repository/>, usually not needed. Certain pathological + cross-certification cases require a two-certificate chain due to + issuer name conflicts. If used, the bpki_cms_glue certificate + should be the issuer of the bpki_cms_cert certificate and should be + issued by the bpki_cert certificate in the <self/> object; if not + needed, the bpki_cms_glue certificate should be left unset. -@li @em BPKI: Business PKI + * bpki_https_cert (element): BPKI HTTPS CA certificate for this + <repository/>. This is like the bpki_cms_cert object, only used for + validating incoming TLS messages rather than CMS. -@li @em RPKI: Resource PKI + * bpki_cms_glue (element): Another BPKI HTTPS CA certificate for this + <repository/>, usually not needed. This is like the bpki_cms_glue + certificate, only used for validating incoming TLS messages rather + than CMS. -@section Protocol operations between IRBE and RPKI engine + At present there are no control attributes for <repository/> objects. -The left-right protocol is really two separate client/server protocols -over separate channels. The IRBE is the client for one of the -subprotocols, the RPKI engine is the client for the other. +<route_origin/> object -@subsection Operations initiated by the IRBE + The <route_origin/> object is a kind of prototype for a ROA. It + contains all the information needed to generate a ROA once the RPKI + engine obtains the appropriate RPKI certificates from its parent(s). -This part of the protcol uses a kind of message-passing. Each object -that the RPKI engine knows about takes five messages: "create", "set", -"get", "list", and "destroy". Actions which are not just data -operations on objects are handled via an SNMP-like mechanism, as if -they were fields to be set. For example, to generate a keypair one -"sets" the "generate-keypair" field of a BSC object, even though there -is no such field in the object itself as stored in SQL. This is a bit -of a kludge, but the reason for doing it as if these were variables -being set is to allow composite operations such as creating a BSC, -populating all of its data fields, and generating a keypair, all as a -single operation. With this model, that's trivial, otherwise it's at -least two round trips. + Note that a <route_origin/> object represents a ROA to be generated on + behalf of <self/>, not on behalf of a <child/>. Thus, a hosted entity + that has no children but which does need to generate ROAs would be + represented by a hosted <self/> with no <child/> objects but one or + more <route_origin/> objects. While lumping ROA generation in with the + other RPKI engine activities may seem a little odd at first, it's a + natural consequence of the design requirement that the RPKI daemon + never transmit private keys across the network in any form; given this + requirement, the RPKI engine that holds the private keys for an RPKI + certificate must also be the engine which generates any ROAs that + derive from that RPKI certificate. -Fields can be set in either "create" or "set" operations, the -difference just being whether the object already exists. A "get" -operation returns all visible fields of the object. A "list" -operation returns a list containing what "get" would have returned on -each of those objects. + The precise content of the <route_origin/> has changed over time as the + underlying ROA specification has changed. The current implementation as + of this writing matches what we expect to see in + draft-ietf-sidr-roa-format-03, once it is issued. In particular, note + that the exactMatch boolean from the -02 draft has been replaced by the + prefix and maxLength encoding used in the -03 draft. -Left-right protocol objects are encoded as signed CMS messages -containing XML as eContent and using an eContentType OID of id-ct-xml -(1.2.840.113549.1.9.16.1.28). These CMS messages are in turn passed -as the data for HTTPS POST operations, with an HTTP content type of -"application/x-rpki" for both the POST data and the response data. + Payload data which can be configured in a <route_origin/> object: + + * as_number (attribute): Autonomous System Number (ASN) to place in + the generated ROA. A single ROA can only grant authorization to a + single ASN; multiple ASNs require multiple ROAs, thus multiple + <route_origin/> objects. + + * ipv4 (attribute): List of IPv4 prefix and maxLength values, see + below for format. + + * ipv6 (attribute): List of IPv6 prefix and maxLength values, see + below for format. + + Control attributes that can be set to "yes" to force actions: + + * suppress_publication: Not implemented, may be removed from + protocol. + + The lists of IPv4 and IPv6 prefix and maxLength values are represented + as comma-separated text strings, with no whitespace permitted. Each + entry in such a string represents a single prefix/maxLength pair. + + ABNF for these address lists: -All operations allow an optional "tag" attribute which can be any -alphanumeric token. The main purpose of the tag attribute is to allow -batching of multiple requests into a single PDU. -@subsubsection <self/> object + <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ] + ; Where <max_prefixlen> defaults to the same + ; value as <prefixlen>. -A <self/> object represents one virtual RPKI engine. In simple cases -where the RPKI engine operator operates the engine only on their own -behalf, there will only be one <self/> object, representing the engine -operator's organization, but in environments where the engine operator -hosts other entities, there will be one <self/> object per hosted -entity (probably including the engine operator's own organization, -considered as a hosted customer of itself). + <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> ) -Some of the RPKI engine's configured parameters and data are shared by -all hosted entities, but most are tied to a specific <self/> object. -Data which are shared by all hosted entities are referred to as -"per-engine" data, data which are specific to a particular <self/> -object are "per-self" data. -Since all other RPKI engine objects refer to a <self/> object via a -"self_id" value, one must create a <self/> object before one can -usefully configure any other left-right protocol objects. + For example, "10.0.1.0/24-32,10.0.2.0/24", which is a shorthand form of + "10.0.1.0/24-32,10.0.2.0/24-24". + +Operations initiated by the RPKI engine + + The left-right protocol also includes queries from the RPKI engine back + to the IRDB. These queries do not follow the message-passing pattern + used in the IRBE-initiated part of the protocol. Instead, there's a + single query back to the IRDB, with a corresponding response. The CMS + and HTTPS encoding are the same as in the rest of the protocol, but the + BPKI certificates will be different as the back-queries and responses + form a separate communication channel. + +<list_resources/> messages + + The <list_resources/> query and response allow the RPKI engine to ask + the IRDB for information about resources assigned to a particular + child. The query must include both a "self_id" attribute naming the + <self/> that is making the request and also a "child_id" attribute + naming the child that is the subject of the query. The query and + response also allow an optional "tag" attribute of the same form used + elsewhere in this protocol, to allow batching. + + A <list_resources/> response includes the following attributes, along + with the tag (if specified), self_id, and child_id copied from the + request: + + * valid_until: A timestamp indicating the date and time at which + certificates generated by the RPKI engine for these data should + expire. The timestamp is expressed as an XML xsd:dateTime, must be + expressed in UTC, and must carry the "Z" suffix indicating UTC. + + * subject_name: An optional text string naming the child. Not + currently used. -Every <self/> object has a self_id attribute, which must be specified -for the "set", "get", and "destroy" actions. + * asn: A list of autonomous sequence numbers, expressed as a + comma-separated sequence of decimal integers with no whitespace. -Payload data which can be configured in a <self/> object: + * ipv4: A list of IPv4 address prefixes and ranges, expressed as a + comma-separated list of prefixes and ranges with no whitespace. See + below for format details. -@li use_hsm (attribute): + * ipv6: A list of IPv6 address prefixes and ranges, expressed as a + comma-separated list of prefixes and ranges with no whitespace. See + below for format details. + + Entries in a list of address prefixes and ranges can be either + prefixes, which are written in the usual address/prefixlen notation, or + ranges, which are expressed as a pair of addresses denoting the + beginning and end of the range, written in ascending order separated by + a single "-" character. This format is superficially similar to the + format used for prefix and maxLength values in the <route_origin/> + object, but the semantics differ: note in particular that + <route_origin/> objects don't allow ranges, while <list_resources/> + messages don't allow a maxLength specification. - Whether to use a Hardware Signing Module. At present this option - has no effect, as the implementation does not yet support HSMs. +Error handling -@li crl_interval (attribute): + Error in this protocol are handled at two levels. - Positive integer representing the planned lifetime of an RPKI CRL - for this <self/>, measured in seconds. + 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. -@li regen_margin (attribute): + 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. - Positive integer representing how long before expiration of an - RPKI certificiate a new one should be generated, measured in - seconds. At present this only affects the one-off EE certificates - associated with ROAs. + <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. -@li bpki_cert (element): + 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. - BPKI CA certificate for this <self/>. This is used as part of the - certificate chain when validating incoming TLS and CMS messages, - and should be the issuer of cross-certification BPKI certificates - used in <repository/>, <parent/>, and <child/> objects. 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 per-engine bpki_ta - certificate. + 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. -@li bpki_glue (element): + 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. + __________________________________________________________________ - Another BPKI CA certificate for this <self/>, 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 per-engine bpki_ta - certificate; if not needed, the bpki_glue certificate should be - left unset. -Control attributes that can be set to "yes" to force actions: - -@li rekey - - Start a key rollover for every RPKI CA associated with every - <parent/> object associated with this <self/> object. This is the - first phase of a key rollover operation. - -@li revoke - - Revoke any remaining certificates for any expired key associated - with any RPKI CA for any <parent/> object associated with this - <self/> object. This is the second (cleanup) phase for a key - rollover operation; it's separate from the first phase to leave - time for new RPKI certificates to propegate and be installed. - -@li reissue - - Not implemented, may be removed from protocol. Original theory - was that this operation would force reissuance of any object with - a changed key, but as that happens automatically as part of the - key rollover mechanism this operation seems unnecessary. - -@li run_now - - Force immediate processing for all tasks associated with this - <self/> object that would ordinarily be performed under cron. Not - currently implemented. - -@li publish_world_now - - Force (re)publication of every publishable object for this <self/> - object. Not currently implemented. Intended to aid in recovery - if RPKI engine and publication engine somehow get out of sync. - - -@subsubsection <bsc/> object - -The <bsc/> ("business signing context") object represents all the BPKI -data needed to sign outgoing CMS or HTTPS messages. Various other -objects include pointers to a <bsc/> object. Whether a particular -<self/> uses only one <bsc/> or multiple is a configuration decision -based on external requirements: the RPKI engine code doesn't care, it -just cares that, for any object representing a relationship for which -it must sign messages, there be a <bsc/> object that it can use to -produce that signature. - -Every <bsc/> object has a bsc_id, which must be specified for the -"get", "set", and "destroy" actions. Every <bsc/> also has a self_id -attribute which indicates the <self/> object with which this <bsc/> -object is associated. - -Payload data which can be configured in a <isc/> object: - -@li signing_cert (element): - - BPKI certificate to use when generating a signature. - -@li signing_cert_crl (element): - - CRL which would list signing_cert if it had been revoked. - -Control attributes that can be set to "yes" to force actions: - -@li generate_keypair - - Generate a new BPKI keypair and return a PKCS #10 certificate - request. The resulting certificate, once issued, should be - configured as this <bsc/> object's signing_cert. - -Additional attributes which may be specified when specifying -"generate_keypair": - -@li key_type - - Type of BPKI keypair to generate. "rsa" is both the default and, - at the moment, the only allowed value. - -@li hash_alg - - Cryptographic hash algorithm to use with this keypair. "sha256" - is both the default and, at the moment, the only allowed value. - -@li key_length - - Length in bits of the keypair to be generated. "2048" is both the - default and, at the moment, the only allowed value. - -Replies to "create" and "set" actions that specify "generate-keypair" -include a <bsc_pkcs10/> element, as do replies to "get" and "list" -actions for a <bsc/> object for which a "generate-keypair" command has -been issued. The RPKI engine stores the PKCS #10 request, which -allows the IRBE to reuse the request if and when it needs to reissue -the corresponding BPKI signing certificate. - -@subsubsection <parent/> object - -The <parent/> object represents the RPKI engine's view of a particular -parent of the current <self/> object in the up-down protocol. Due to -the way that the resource hierarchy works, a given <self/> may obtain -resources from multiple parents, but it will always have at least one; -in the case of IANA or an RIR, the parent RPKI engine may be a trivial -stub. - -Every <parent/> object has a parent_id, which must be specified for -the "get", "set", and "destroy" actions. Every <parent/> also has a -self_id attribute which indicates the <self/> object with which this -<parent/> object is associated, a bsc_id attribute indicating the <bsc/> -object to be used when signing messages sent to this parent, and a -repository_id indicating the <repository/> object to be used when -publishing issued by the certificate issued by this parent. - -Payload data which can be configured in a <parent/> object: - -@li peer_contact_uri (attribute): - - HTTPS URI used to contact this parent. - -@li sia_base (attribute): - - The leading portion of an rsync URI that the RPKI engine should - use when composing the publication URI for objects issued by the - RPKI certificate issued by this parent. - -@li sender_name (attribute): - - Sender name to use in the up-down protocol when talking to this - parent. The RPKI engine doesn't really care what this value is, - but other implementations of the up-down protocol do care. - -@li recipient_name (attribute): - - Recipient name to use in the up-down protocol when talking to this - parent. The RPKI engine doesn't really care what this value is, - but other implementations of the up-down protocol do care. - -@li bpki_cms_cert (element): - - BPKI CMS CA certificate for this <parent/>. This is used as part - of the certificate chain when validating incoming CMS messages If - the bpki_cms_glue certificate is in use (below), the bpki_cms_cert - certificate should be issued by the bpki_cms_glue certificate; - otherwise, the bpki_cms_cert certificate should be issued by the - bpki_cert certificate in the <self/> object. - -@li bpki_cms_glue (element): - - Another BPKI CMS CA certificate for this <parent/>, usually not - needed. Certain pathological cross-certification cases require a - two-certificate chain due to issuer name conflicts. If used, the - bpki_cms_glue certificate should be the issuer of the - bpki_cms_cert certificate and should be issued by the bpki_cert - certificate in the <self/> object; if not needed, the - bpki_cms_glue certificate should be left unset. - -@li bpki_https_cert (element): - - BPKI HTTPS CA certificate for this <parent/>. This is like the - bpki_cms_cert object, only used for validating incoming TLS - messages rather than CMS. - -@li bpki_cms_glue (element): - - Another BPKI HTTPS CA certificate for this <parent/>, usually not - needed. This is like the bpki_cms_glue certificate, only used for - validating incoming TLS messages rather than CMS. - -Control attributes that can be set to "yes" to force actions: - -@li rekey - - This is like the rekey command in the <self/> object, but limited - to RPKI CAs under this parent. - -@li reissue - - This is like the reissue command in the <self/> object, but limited - to RPKI CAs under this parent. - -@li revoke - - This is like the revoke command in the <self/> object, but limited - to RPKI CAs under this parent. - -@subsubsection <child/> object - -The <child/> object represents the RPKI engine's view of particular -child of the current <self/> in the up-down protocol. - -Every <child/> object has a parent_id, which must be specified for the -"get", "set", and "destroy" actions. Every <child/> also has a -self_id attribute which indicates the <self/> object with which this -<child/> object is associated. - -Payload data which can be configured in a <child/> object: - -@li bpki_cert (element): - - BPKI CA certificate for this <child/>. 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 bpki_cert certificate in the <self/> object. - -@li bpki_glue (element): - - Another BPKI CA certificate for this <child/>, 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 bpki_cert certificate in - the <self/> object; if not needed, the bpki_glue certificate - should be left unset. - -Control attributes that can be set to "yes" to force actions: - -@li reissue - - Not implemented, may be removed from protocol. - -@subsubsection <repository/> object - -The <repository/> object represents the RPKI engine's view of a -particular publication repository used by the current <self/> object. - -Every <repository/> object has a repository_id, which must be -specified for the "get", "set", and "destroy" actions. Every -<repository/> also has a self_id attribute which indicates the <self/> -object with which this <repository/> object is associated. - -Payload data which can be configured in a <repository/> object: - -@li peer_contact_uri (attribute): - - HTTPS URI used to contact this repository. - -@li bpki_cms_cert (element): - - BPKI CMS CA certificate for this <repository/>. This is used as part - of the certificate chain when validating incoming CMS messages If - the bpki_cms_glue certificate is in use (below), the bpki_cms_cert - certificate should be issued by the bpki_cms_glue certificate; - otherwise, the bpki_cms_cert certificate should be issued by the - bpki_cert certificate in the <self/> object. - -@li bpki_cms_glue (element): - - Another BPKI CMS CA certificate for this <repository/>, usually not - needed. Certain pathological cross-certification cases require a - two-certificate chain due to issuer name conflicts. If used, the - bpki_cms_glue certificate should be the issuer of the - bpki_cms_cert certificate and should be issued by the bpki_cert - certificate in the <self/> object; if not needed, the - bpki_cms_glue certificate should be left unset. - -@li bpki_https_cert (element): - - BPKI HTTPS CA certificate for this <repository/>. This is like the - bpki_cms_cert object, only used for validating incoming TLS - messages rather than CMS. - -@li bpki_cms_glue (element): - - Another BPKI HTTPS CA certificate for this <repository/>, usually not - needed. This is like the bpki_cms_glue certificate, only used for - validating incoming TLS messages rather than CMS. - -At present there are no control attributes for <repository/> objects. - -@subsubsection <route_origin/> object - -The <route_origin/> object is a kind of prototype for a ROA. It -contains all the information needed to generate a ROA once the RPKI -engine obtains the appropriate RPKI certificates from its parent(s). - -Note that a <route_origin/> object represents a ROA to be generated on -behalf of <self/>, not on behalf of a <child/>. Thus, a hosted entity -that has no children but which does need to generate ROAs would be -represented by a hosted <self/> with no <child/> objects but one or -more <route_origin/> objects. While lumping ROA generation in with -the other RPKI engine activities may seem a little odd at first, it's -a natural consequence of the design requirement that the RPKI daemon -never transmit private keys across the network in any form; given this -requirement, the RPKI engine that holds the private keys for an RPKI -certificate must also be the engine which generates any ROAs that -derive from that RPKI certificate. - -The precise content of the <route_origin/> has changed over time as -the underlying ROA specification has changed. The current -implementation as of this writing matches what we expect to see in -draft-ietf-sidr-roa-format-03, once it is issued. In particular, note -that the exactMatch boolean from the -02 draft has been replaced by -the prefix and maxLength encoding used in the -03 draft. - -Payload data which can be configured in a <route_origin/> object: - -@li as_number (attribute): - - Autonomous System Number (ASN) to place in the generated ROA. A - single ROA can only grant authorization to a single ASN; multiple - ASNs require multiple ROAs, thus multiple <route_origin/> objects. - -@li ipv4 (attribute): - - List of IPv4 prefix and maxLength values, see below for format. - -@li ipv6 (attribute): - - List of IPv6 prefix and maxLength values, see below for format. - -Control attributes that can be set to "yes" to force actions: - -@li suppress_publication - - Not implemented, may be removed from protocol. - -The lists of IPv4 and IPv6 prefix and maxLength values are represented -as comma-separated text strings, with no whitespace permitted. Each -entry in such a string represents a single prefix/maxLength pair. - -ABNF for these address lists: - -@verbatim - - <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ] - ; Where <max_prefixlen> defaults to the same - ; value as <prefixlen>. - - <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> ) - -@endverbatim - -For example, @c "10.0.1.0/24-32,10.0.2.0/24", which is a shorthand -form of @c "10.0.1.0/24-32,10.0.2.0/24-24". - -@subsection Operations initiated by the RPKI engine - -The left-right protocol also includes queries from the RPKI engine -back to the IRDB. These queries do not follow the message-passing -pattern used in the IRBE-initiated part of the protocol. Instead, -there's a single query back to the IRDB, with a corresponding -response. The CMS and HTTPS encoding are the same as in the rest of -the protocol, but the BPKI certificates will be different as the -back-queries and responses form a separate communication channel. - -@subsubsection <list_resources/> messages - -The <list_resources/> query and response allow the RPKI engine to ask -the IRDB for information about resources assigned to a particular -child. The query must include both a @c "self_id" attribute naming -the <self/> that is making the request and also a @c "child_id" -attribute naming the child that is the subject of the query. The -query and response also allow an optional @c "tag" attribute of the -same form used elsewhere in this protocol, to allow batching. - -A <list_resources/> response includes the following attributes, along -with the @c tag (if specified), @c self_id, and @c child_id copied -from the request: - -@li @c valid_until: - - A timestamp indicating the date and time at which certificates - generated by the RPKI engine for these data should expire. The - timestamp is expressed as an XML @c xsd:dateTime, must be - expressed in UTC, and must carry the "Z" suffix indicating UTC. - -@li @c subject_name: - - An optional text string naming the child. Not currently used. - -@li @c asn: - - A list of autonomous sequence numbers, expressed as a - comma-separated sequence of decimal integers with no whitespace. - -@li @c ipv4: - - A list of IPv4 address prefixes and ranges, expressed as a - comma-separated list of prefixes and ranges with no whitespace. - See below for format details. - -@li @c ipv6: - - A list of IPv6 address prefixes and ranges, expressed as a - comma-separated list of prefixes and ranges with no whitespace. - See below for format details. - -Entries in a list of address prefixes and ranges can be either -prefixes, which are written in the usual address/prefixlen notation, -or ranges, which are expressed as a pair of addresses denoting the -beginning and end of the range, written in ascending order separated -by a single "-" character. This format is superficially similar to -the format used for prefix and maxLength values in the <route_origin/> -object, but the semantics differ: note in particular that -<route_origin/> objects don't allow ranges, while <list_resources/> -messages don't allow a maxLength specification. - -@subsection 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 @c "tag" attribute to -assist in matching the error with a particular query when using -batching, and also includes a @c "self_id" attribute indicating the -<self/> that issued the error. - -The error itself is conveyed in the @c 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. + Generated on Wed Jun 11 18:58:48 2008 for Resource PKI Engine by + doxygen 1.5.5 diff --git a/docs/publication-protocol b/docs/publication-protocol index 466a4cf1..e7c27406 100644 --- a/docs/publication-protocol +++ b/docs/publication-protocol @@ -1,244 +1,227 @@ --*- Text -*- -$Id$ +Publication protocol -Copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") + The publication protocol is really two separate client/server + protocols, between different parties. -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 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. -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. + 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. -@section Terminology + 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. -@li @em IRBE: Internet Registry Back End +Terminology -@li @em IRDB: Internet Registry Data Base + * IRBE: Internet Registry Back End -@li @em BPKI: Business PKI + * IRDB: Internet Registry Data Base -@li @em RPKI: Resource PKI + * BPKI: Business PKI -@section Protocol operations between IRBE and RPKI engine + * RPKI: Resource PKI -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. +Publication control subprotocol -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 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. -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. +<config/> object -@subsection Publication control subprotocol + The <config/> object allows configuration of data that apply to the + entire publication server rather than a particular client. -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. + 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. -@subsubsection <config/> object + Payload data which can be configured in a <config/> object: -The <config/> object allows configuration of data that apply to the -entire publication server rather than a particular client. + * 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. -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. +<client/> object -Payload data which can be configured in a <config/> object: + The <client/> object represents one client authorized to use the + publication server. -@li @c bpki_crl (element): + 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. - 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. + Payload data which can be configured in a <client/> object: -@subsubsection <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. -The <client/> object represents one client authorized to use the -publication server. + * 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. -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. + * 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. -Payload data which can be configured in a <client/> object: +Publication subprotocol -@li @c 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. - -@li 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. - -@li 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. - -@subsection 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 @c "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. - -@subsubsection <certificate/> object - -The <certificate/> object represents an RPKI certificate to be -published or withdrawn. - -@subsubsection <crl/> object - -The <crl/> object represents an RPKI CRL to be published or withdrawn. - -@subsubsection <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 @em every publication or withdrawal -action requires a new manifest, thus every publication or withdrawal -action will involve at least two objects. - -@subsubsection <roa/> object - -The <roa/> object represents a ROA to be published or withdrawn. - -@subsection 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 @c "tag" attribute to -assist in matching the error with a particular query when using -batching, and also includes a @c "self_id" attribute indicating the -<self/> that issued the error. - -The error itself is conveyed in the @c 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. - -@section Additional access control considerations. - -As detailed above, the publication protocol is trivially simple. This -glosses over two bits of potential complexity: - -@li 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. - -@li 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. + 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 Wed Jun 11 18:58:48 2008 for Resource PKI Engine by + doxygen 1.5.5 |