Update generated documentation

svn path=/docs/left-right-protocol; revision=1867

1 files changed, 445 insertions, 527 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