diff options
Diffstat (limited to 'doc/manual/35.RPKI.CA.Protocols.LeftRight.wiki')
| -rw-r--r-- | doc/manual/35.RPKI.CA.Protocols.LeftRight.wiki | 473 |
1 files changed, 473 insertions, 0 deletions
diff --git a/doc/manual/35.RPKI.CA.Protocols.LeftRight.wiki b/doc/manual/35.RPKI.CA.Protocols.LeftRight.wiki new file mode 100644 index 00000000..0859c463 --- /dev/null +++ b/doc/manual/35.RPKI.CA.Protocols.LeftRight.wiki @@ -0,0 +1,473 @@ += The Left-Right Protocol = + +[[TracNav(doc/RPKI/TOC)]] +[[PageOutline]] + +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. + +== Operations 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 HTTP 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_obj <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_handle" value, one must create a {{{<self/>}}} object before one can +usefully configure any other left-right protocol objects. + +Every {{{<self/>}}} object has a self_handle attribute, which must be specified +for the "create", "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. This parameter also controls + how long before the nextUpdate time of CRL or manifest the CRL + or manifest should be updated. + +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 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_handle, which must be specified for the +"create", "get", "set", and "destroy" actions. Every {{{<bsc/>}}} also has a self_handle +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_handle, which must be specified for +the "create", "get", "set", and "destroy" actions. Every {{{<parent/>}}} also has a +self_handle attribute which indicates the {{{<self/>}}} object with which this +{{{<parent/>}}} object is associated, a bsc_handle attribute indicating the {{{<bsc/>}}} +object to be used when signing messages sent to this parent, and a +repository_handle 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) + HTTP 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. + +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 child_handle, which must be specified for the +"create", "get", "set", and "destroy" actions. Every {{{<child/>}}} also has a +self_handle 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 === + +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_handle, which must be +specified for the "create", "get", "set", and "destroy" actions. Every +{{{<repository/>}}} also has a self_handle attribute which indicates the {{{<self/>}}} +object with which this {{{<repository/>}}} object is associated. + +Payload data which can be configured in a {{{<repository/>}}} object: + +peer_contact_uri:: (attribute) + HTTP URI used to contact this repository. + +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. + +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. + +At present there are no control attributes for {{{<repository/>}}} objects. + +=== <route_origin/> object === + +This section is out-of-date. The {{{<route_origin/>}}} object +has been replaced by the {{{<list_roa_requests/>}}} IRDB query, +but the documentation for that hasn't been written yet. + +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: + +asn:: (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: + +{{{ + <ROAIPAddress> ::= <address> "/" <prefixlen> [ "-" <max_prefixlen> ] + ; Where <max_prefixlen> defaults to the same + ; value as <prefixlen>. + + <ROAIPAddressList> ::= <ROAIPAddress> *( "," <ROAIPAddress> ) +}}} + +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 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_handle}}} attribute naming +the {{{<self/>}}} that is making the request and also a {{{child_handle}}} +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_handle}}}, and {{{child_handle}}} 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. + +asn:: + A list of autonomous sequence numbers, expressed as a + comma-separated sequence of decimal integers with no whitespace. + +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. + +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. + +== 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 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_handle}}} 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. |