diff options
Diffstat (limited to 'docs/left-right-protocol')
| -rw-r--r-- | docs/left-right-protocol | 277 |
1 files changed, 158 insertions, 119 deletions
diff --git a/docs/left-right-protocol b/docs/left-right-protocol index 5fe0cb7c..465eabb2 100644 --- a/docs/left-right-protocol +++ b/docs/left-right-protocol @@ -1,118 +1,157 @@ -;;; -*- Lisp -*- -;;; $Id$ +-*- Text -*- +$Id$ -;;; Copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") -;;; -;;; 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. -;;; -;;; 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. - -;;; Scratch pad for working out API design for RPKI engine. -;;; -;;; This file is pseudocode, I just wanted to take advantage of -;;; emacs's built-in support for languages with reasonable syntax. -;;; -;;; Terminology: -;;; -;;; - IRBE: Internet Registry Back End -;;; -;;; - RE: RPKI Engine +Copyright (C) 2007--2008 American Registry for Internet Numbers ("ARIN") -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; -;;; Protocol operations between IRBE and RE. -;;; -;;; This is really two separate protocols over channels that might or -;;; not be the same. Both are client/server protocols, but for some -;;; the RE is the client and for others the IRBE is the client. -;;; -;;; This set of operations are initiated by the IRBE. -;;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; -;;; This part of the protcol uses a kind of message-passing. Each -;;; object that the RE 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 biz-signing-context -;;; object, even though there is no such field in the object itself. -;;; 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 biz-signing-context, 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. -;;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; "Self" ID context -- one RE instance. In degenerate case there -;; will be only one, but in hosting environments there might be many. -;; -;; We haven't yet defined any standard preferences, so none are shown. -;; -;; Extensions might also show up as preferences, using the -;; extension-preference syntax. -;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +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. + +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. + +@section Terminology + +- IRBE: Internet Registry Back End + +- IRDB: Internet Registry Data Base + +@section Protocol operations between IRBE and RPKI engine + +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. + +@subsection 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 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 + +@subsubsection <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. + +Payload data which can be configured in a <self/> object: + +@li 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. + +@li crl_interval (attribute) + + Positive integer representing the planned lifetime of an RPKI CRL + for this <self/>, measured in seconds. + +@li 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. + +@li bpki_cert (subelement) + + 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. + +@li bpki_glue (subelement) + + 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. -(self :action :create - (:extension-preference "name" "Launcelot") - (:extension-preference "quest" "Holy Grail")) -=> (self :self-id 42) - -(self :action :set - :self-id 42 - (:extension-preference "color" "Blue") - ;; - ;; <self> objects have a lot of actions: - ;; - (:rekey) ; Change all RPKI keys in this context now - (:reissue) ; Reissue any cert with changed keys - (:revoke) ; Revoke any old keys - (:run-now) ; Run this self context now - (:publish-world-now)) ; Publish everything in this context now -=> (self :self-id 42) - -(self :action :get - :self-id 42) -=> (self - :self-id 42 - (:extension-preference "name" "Launcelot") - (:extension-preference "quest" "Holy Grail") - (:extension-preference "color" "Blue")) - -(self :action :list) -=> ((self - :self-id 42 - (:extension-preference "name" "Launcelot") - (:extension-preference "quest" "Holy Grail") - (:extension-preference "color" "Blue")) - (self - :self-id 99 - (:extension-preference "name" "Arthur, King of the Britons") - (:extension-preference "quest" "Holy Grail") - (:extension-preference "airspeed-velocity-of-an-unladen-swallow" - "African or European swallow?"))) - -(self :action :destroy - :self-id 42) -=> (self :self-id 42) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; @@ -162,7 +201,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; -;; Parent context -- represents one parent of this RE +;; Parent context -- represents one parent of this RPKI engine ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -218,7 +257,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; -;; Child context -- represents one child of this RE +;; Child context -- represents one child of this RPKI engine ;; ;; "child-db-id" may be unnecessary -- old API had both "child" and ;; "child-id", the second of which was a settable attribute of child, @@ -267,7 +306,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; -;; Repository context -- represents one repository in which this RE +;; Repository context -- represents one repository in which this RPKI engine ;; publishes objects it signs. ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -313,7 +352,7 @@ ;; Route Origin objects (prototype and control for ROAs) ;; ;; Previous versions of this protocol handled this via queries from -;; the RE back into the IRBE, but the design group now believes that +;; the RPKI engine back into the IRBE, but the design group now believes that ;; an imperative interface makes more sense. We stick to the same ;; general object model used above because ROAs are published objects, ;; thus the IRBE presumably wants some kind of handle on the ROA. @@ -369,13 +408,13 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; -;;; Protocol operations between IRBE and RE. +;;; Protocol operations between IRBE and RPKI engine. ;;; ;;; This is really two separate protocols over channels that might or ;;; not be the same. Both are client/server protocols, but for some ;;; the rpki engine and for others the irbe is the client. ;;; -;;; This set of operations are initiated by the RE. +;;; This set of operations are initiated by the RPKI engine. ;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -386,7 +425,7 @@ (:ipv4-prefix 10.3.0.44 32) (:ipv6-prefix fe80:dead:beef:: 48) (:as-number 666)) - ((:subject-name "wombats are us") ; Allowed in protocol, but RE may reject with error + ((:subject-name "wombats are us") ; Allowed in protocol, but RPKI engine may reject with error (:ipv4-prefix 10.2..0.6 32) (:ipv6-prefix fe80:dead:beef:: 48) (:ipv6-range fe80:dead:beef:: fe80:dead:beef::49) |