From 29058ca618dc41319cdca14ddb0a72f769c7550d Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Wed, 9 May 2007 17:08:15 +0000 Subject: Cleanup svn path=/docs/left-right-protocol; revision=597 --- docs/left-right-protocol | 347 +++++++++++++++++++++++++++++++ docs/left-right-protocol-message-passing | 347 ------------------------------- 2 files changed, 347 insertions(+), 347 deletions(-) create mode 100644 docs/left-right-protocol delete mode 100644 docs/left-right-protocol-message-passing diff --git a/docs/left-right-protocol b/docs/left-right-protocol new file mode 100644 index 00000000..44f2ea14 --- /dev/null +++ b/docs/left-right-protocol @@ -0,0 +1,347 @@ +;;; -*- Lisp -*- +;;; $URL$ +;;; $Id$ +;;; +;;; Scratch pad for working out API design for RPKI engine. +;;; +;;; This file is psuedocode, 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 + +;;; Current problems: + +;;; Need revoke and rekey operations for RPKI keys. First problem is +;;; how does the IRBE name the key that is to roll if keypairs are +;;; created on the fly? For that matter, how do we specify signature +;;; and hash algorithm, keylength, etc for RPKI keys? Preferences? + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;; +;;; 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. +;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(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") + ;; + ;; 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) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; +;; Business signing key context -- bundles all the stuff we need to +;; sign outgoing CMS messages with a business key. +;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(biz-signing-context :action :create + :biz-signing-context-id 17 + (:signing-cert cert1)) +=> (biz-signing-context :biz-signing-context-id 17) + +(biz-signing-context :action :set + :self-id 42 + :biz-signing-context-id 17 + (:signing-cert cert2) + ;; + ;; Actions: + ;; + (:generate-keypair :key-type :rsa + :hash-alg :sha1 + :key-length 2048)) +=> (biz-signing-context :biz-signing-context-id 17 + (:pkcs10-cert-request req)) + +(biz-signing-context :action :get + :self-id 42 + :biz-signing-context-id 17) +=> (biz-signing-context :biz-signing-context-id 17 + (:signing-cert cert1) + (:signing-cert cert2) + (:public-key key)) + +(biz-signing-context :action :list + :self-id 42) +=> ((biz-signing-context :biz-signing-context-id 17 + (:signing-cert cert1) + (:signing-cert cert2) + (:public-key key))) + +(biz-signing-context :action :destroy + :self-id 42 + :biz-signing-context-id 17) +=> (biz-signing-context :biz-signing-context-id 17) + + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; +;; Parent context -- represents one parent of this RE +;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(parent :action :create + :self-id 42 + (:ta ta) + (:uri uri) + (:sia-base sia-base) + (:biz-signing-context biz-signing-context) + (:repository repository)) +=> (parent :parent-id 666) + +(parent :action :set + :self-id 42 + :parent-id 666 + (:ta ta) + (:uri uri) + (:sia-base sia-base) + (:biz-signing-context biz-signing-context) + (:repository repository) + ;; + ;; Actions: + ;; + (:rekey) ; Change all keys now + (:reissue) ; Reissue all certs with changed keys now + (:revoke)) ; Revoke any old keys now +=> (parent :parent-id 666) + +(parent :action :get + :self-id 42 + :parent-id 666) +=> (parent :parent-id 666 + (:ta ta) + (:uri uri) + (:sia-base sia-base) + (:biz-signing-context biz-signing-context) + (:repository repository)) + +(parent :action :list + :self-id 42 + :parent-id 666) +=> ((parent :parent-id 666 + (:ta ta) + (:uri uri) + (:sia-base sia-base) + (:biz-signing-context biz-signing-context) + (:repository repository))) + +(parent :action :destroy + :self-id 42 + :parent-id 666) +=> (parent :parent-id 666) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; +;; Child context -- represents one child of this RE +;; +;; "child-db-id" may be unnecessary -- old API had both "child" and +;; "child-id", the second of which was a settable attribute of child, +;; I'm not quite sure what it was, so here I'm calling it child-db-id +;; in case we need it for something. Perhaps this corresponds to the +;; optional child ID in the list-resources callback to the IRBE? +;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(child :action :create + :self-id 42 + (:ta ta) + (:biz-signing-context biz-signing-context) + (:child-db-id child-db-id)) +=> (child :child-id 3) + +(child :action :set + :self-id 42 + :child-id 3 + (:ta ta) + (:biz-signing-context biz-signing-context) + (:child-db-id child-db-id) + (:reissue)) ; Reissue any certs to this child now +=> (child :child-id 3) + +(child :action :get + :self-id 42 + :child-id 3) +=> (child :child-id 3 + (:ta ta) + (:biz-signing-context biz-signing-context) + (:child-db-id child-db-id)) + +(child :action :list + :self-id 42 + :child-id 3) +=> ((child :child-id 3 + (:ta ta) + (:biz-signing-context biz-signing-context) + (:child-db-id child-db-id))) + +(child :action :destroy + :self-id 42 + :child-id 3) +=> (child :child-id 3) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; +;; Repository context -- represents one repository in which this RE +;; publishes objects it signs. +;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(repository :action :create + :repository-id 120 + (:uri uri) + (:ta ta) + (:biz-signing-context biz-signing-context)) +=> (:repository-id 120) + +(repository :action :set + :self-id 42 + :repository-id 120 + (:uri uri) + (:ta ta) + (:biz-signing-context biz-signing-context)) +=> (:repository-id 120) + +(repository :action :get + :self-id 42 + :repository-id 120) +=> (repository :repository-id 120 + (:uri uri) + (:ta ta) + (:biz-signing-context biz-signing-context)) + +(repository :action :list + :self-id 42 + :repository-id 120) +=> ((repository :repository-id 120 + (:uri uri) + (:ta ta) + (:biz-signing-context biz-signing-context))) + +(repository :action :destroy + :self-id 42 + :repository-id 120) +=> (:repository-id 120) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;; +;;; 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 rpki engine and for others the irbe is the client. +;;; +;;; This set of operations are initiated by the RE. +;;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +;; The following probably needs expansion to cover issuing subsets +;; (transfer support). + +(list-resources :self-id 42 ; issuer id + &optional ; If left off, we're asking about self rather than child + :child id) ; subject id +=> (resources :valid-until "2008-04-01T00:00:00Z" + (:ipv4-address "10.0.0.44/32" "10.3.0.44/32") + (:ipv6-address "fe80:dead:beef::/24") + (:as-number "666") + ...) + +;; There has been some discussion of turning ROA generation into an +;; imperative interface, in which case the following query would need +;; to turn into object control protocol in the previous section. The +;; following is the older version of this in which the RE queries into +;; the IRBE to find out rights to route. + +(list-rights-to-route :self-id 42) ; Self +=> (rights-to-route + (as-number :ipv4 prefix-or-range :ipv6 prefix-or-range ...) + (as-number "ipv6 prefix-or-range :ipv6 prefix-or-range :ipv4 prefix-or-range ...) + ...) + +;; "Blind object signing" would probably be another imperative message +;; to be added above, similar to whatever we end up with for ROAs. + +(report-error :self-id 42 + :error-token :your-hair-is-on-fire + :bag-of-data whatever) +=> () diff --git a/docs/left-right-protocol-message-passing b/docs/left-right-protocol-message-passing deleted file mode 100644 index 44f2ea14..00000000 --- a/docs/left-right-protocol-message-passing +++ /dev/null @@ -1,347 +0,0 @@ -;;; -*- Lisp -*- -;;; $URL$ -;;; $Id$ -;;; -;;; Scratch pad for working out API design for RPKI engine. -;;; -;;; This file is psuedocode, 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 - -;;; Current problems: - -;;; Need revoke and rekey operations for RPKI keys. First problem is -;;; how does the IRBE name the key that is to roll if keypairs are -;;; created on the fly? For that matter, how do we specify signature -;;; and hash algorithm, keylength, etc for RPKI keys? Preferences? - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; -;;; 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. -;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(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") - ;; - ;; 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) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; Business signing key context -- bundles all the stuff we need to -;; sign outgoing CMS messages with a business key. -;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(biz-signing-context :action :create - :biz-signing-context-id 17 - (:signing-cert cert1)) -=> (biz-signing-context :biz-signing-context-id 17) - -(biz-signing-context :action :set - :self-id 42 - :biz-signing-context-id 17 - (:signing-cert cert2) - ;; - ;; Actions: - ;; - (:generate-keypair :key-type :rsa - :hash-alg :sha1 - :key-length 2048)) -=> (biz-signing-context :biz-signing-context-id 17 - (:pkcs10-cert-request req)) - -(biz-signing-context :action :get - :self-id 42 - :biz-signing-context-id 17) -=> (biz-signing-context :biz-signing-context-id 17 - (:signing-cert cert1) - (:signing-cert cert2) - (:public-key key)) - -(biz-signing-context :action :list - :self-id 42) -=> ((biz-signing-context :biz-signing-context-id 17 - (:signing-cert cert1) - (:signing-cert cert2) - (:public-key key))) - -(biz-signing-context :action :destroy - :self-id 42 - :biz-signing-context-id 17) -=> (biz-signing-context :biz-signing-context-id 17) - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; Parent context -- represents one parent of this RE -;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(parent :action :create - :self-id 42 - (:ta ta) - (:uri uri) - (:sia-base sia-base) - (:biz-signing-context biz-signing-context) - (:repository repository)) -=> (parent :parent-id 666) - -(parent :action :set - :self-id 42 - :parent-id 666 - (:ta ta) - (:uri uri) - (:sia-base sia-base) - (:biz-signing-context biz-signing-context) - (:repository repository) - ;; - ;; Actions: - ;; - (:rekey) ; Change all keys now - (:reissue) ; Reissue all certs with changed keys now - (:revoke)) ; Revoke any old keys now -=> (parent :parent-id 666) - -(parent :action :get - :self-id 42 - :parent-id 666) -=> (parent :parent-id 666 - (:ta ta) - (:uri uri) - (:sia-base sia-base) - (:biz-signing-context biz-signing-context) - (:repository repository)) - -(parent :action :list - :self-id 42 - :parent-id 666) -=> ((parent :parent-id 666 - (:ta ta) - (:uri uri) - (:sia-base sia-base) - (:biz-signing-context biz-signing-context) - (:repository repository))) - -(parent :action :destroy - :self-id 42 - :parent-id 666) -=> (parent :parent-id 666) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; Child context -- represents one child of this RE -;; -;; "child-db-id" may be unnecessary -- old API had both "child" and -;; "child-id", the second of which was a settable attribute of child, -;; I'm not quite sure what it was, so here I'm calling it child-db-id -;; in case we need it for something. Perhaps this corresponds to the -;; optional child ID in the list-resources callback to the IRBE? -;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(child :action :create - :self-id 42 - (:ta ta) - (:biz-signing-context biz-signing-context) - (:child-db-id child-db-id)) -=> (child :child-id 3) - -(child :action :set - :self-id 42 - :child-id 3 - (:ta ta) - (:biz-signing-context biz-signing-context) - (:child-db-id child-db-id) - (:reissue)) ; Reissue any certs to this child now -=> (child :child-id 3) - -(child :action :get - :self-id 42 - :child-id 3) -=> (child :child-id 3 - (:ta ta) - (:biz-signing-context biz-signing-context) - (:child-db-id child-db-id)) - -(child :action :list - :self-id 42 - :child-id 3) -=> ((child :child-id 3 - (:ta ta) - (:biz-signing-context biz-signing-context) - (:child-db-id child-db-id))) - -(child :action :destroy - :self-id 42 - :child-id 3) -=> (child :child-id 3) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; Repository context -- represents one repository in which this RE -;; publishes objects it signs. -;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(repository :action :create - :repository-id 120 - (:uri uri) - (:ta ta) - (:biz-signing-context biz-signing-context)) -=> (:repository-id 120) - -(repository :action :set - :self-id 42 - :repository-id 120 - (:uri uri) - (:ta ta) - (:biz-signing-context biz-signing-context)) -=> (:repository-id 120) - -(repository :action :get - :self-id 42 - :repository-id 120) -=> (repository :repository-id 120 - (:uri uri) - (:ta ta) - (:biz-signing-context biz-signing-context)) - -(repository :action :list - :self-id 42 - :repository-id 120) -=> ((repository :repository-id 120 - (:uri uri) - (:ta ta) - (:biz-signing-context biz-signing-context))) - -(repository :action :destroy - :self-id 42 - :repository-id 120) -=> (:repository-id 120) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; -;;; 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 rpki engine and for others the irbe is the client. -;;; -;;; This set of operations are initiated by the RE. -;;; -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -;; The following probably needs expansion to cover issuing subsets -;; (transfer support). - -(list-resources :self-id 42 ; issuer id - &optional ; If left off, we're asking about self rather than child - :child id) ; subject id -=> (resources :valid-until "2008-04-01T00:00:00Z" - (:ipv4-address "10.0.0.44/32" "10.3.0.44/32") - (:ipv6-address "fe80:dead:beef::/24") - (:as-number "666") - ...) - -;; There has been some discussion of turning ROA generation into an -;; imperative interface, in which case the following query would need -;; to turn into object control protocol in the previous section. The -;; following is the older version of this in which the RE queries into -;; the IRBE to find out rights to route. - -(list-rights-to-route :self-id 42) ; Self -=> (rights-to-route - (as-number :ipv4 prefix-or-range :ipv6 prefix-or-range ...) - (as-number "ipv6 prefix-or-range :ipv6 prefix-or-range :ipv4 prefix-or-range ...) - ...) - -;; "Blind object signing" would probably be another imperative message -;; to be added above, similar to whatever we end up with for ROAs. - -(report-error :self-id 42 - :error-token :your-hair-is-on-fire - :bag-of-data whatever) -=> () -- cgit v1.2.3