diff options
Diffstat (limited to 'doc/35.RPKI.CA.Protocols.LeftRight.md')
| -rw-r--r-- | doc/35.RPKI.CA.Protocols.LeftRight.md | 486 |
1 files changed, 0 insertions, 486 deletions
diff --git a/doc/35.RPKI.CA.Protocols.LeftRight.md b/doc/35.RPKI.CA.Protocols.LeftRight.md deleted file mode 100644 index 6aeb1189..00000000 --- a/doc/35.RPKI.CA.Protocols.LeftRight.md +++ /dev/null @@ -1,486 +0,0 @@ -# The 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. - -## 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. |