****** 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.