Move old manual to doc/manual, to make it easier to find other documentation.

1 files changed, 0 insertions, 473 deletions

diff --git a/doc/35.RPKI.CA.Protocols.LeftRight.wiki b/doc/35.RPKI.CA.Protocols.LeftRight.wiki
deleted file mode 100644
index 0859c463..00000000
--- a/doc/35.RPKI.CA.Protocols.LeftRight.wiki
+++ /dev/null
@@ -1,473 +0,0 @@
-= 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.