Move protocol docs to new docs/ tree

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

2 files changed, 340 insertions, 336 deletions

diff --git a/docs/left-right-protocol b/docs/left-right-protocol
new file mode 100644
index 00000000..729dbf20
--- /dev/null
+++ b/docs/left-right-protocol
@@ -0,0 +1,339 @@
+;;; -*- Lisp -*-
+;;; $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:
+
+;;; Model below is still wrong, although converging on the right
+;;; thing.  Children should not be bound within CAs, and CA's can't be
+;;; created until we poll parent to find out what to create; CAs need
+;;; to be created on the fly.  Children should be business
+;;; relationships, not per-CA things.  parent operations should be per
+;;; customer not per ca.
+
+;;; Need revoke and rekey operations.
+
+;;; And, er, how do things like publication URIs (which also go into
+;;; some of the X.509 extensions in the resource certs) get into the
+;;; RE anyway?  This is close to being the same question as how do we
+;;; configure the publication point, as the data are largely the same.
+;;; Part of the problem is that, if we create CAs on the fly in
+;;; response to what we learn from our parent, how do we map that to
+;;; any kind of preconfigured data on where we should publish?  This
+;;; is a mess.
+;;;
+;;; Might it help to have per-parent config for this, since we have to
+;;; config parents anyway?  That'd give us the head of the publication
+;;; URI, leaving us to figure out just the tail.  Could gensym name
+;;; tail for dynamically created CAs, could take name tail from chat
+;;; with parent (risky?  evil parent gives us dangerous name?), could
+;;; take name tail from local config but it's hard to see how.
+;;;
+;;; We now think that there's a negotiation involved here with both
+;;; the parent and the publisher.  The publication URI directory
+;;; breaks into three pieces: head/middle/tail/.  head comes from the
+;;; publisher, middle comes from the parent, and tail comes from this
+;;; RE.  head is just the prefix for where we're allowed to put stuff
+;;; within the publication repository; this could be configured by the
+;;; IRBE or we could ask the publication repository, we currently
+;;; think the latter is better.  Middle comes from this RE's parent,
+;;; and should be a new attribute in the up-down XML protocol: it's
+;;; the parent's advice on where to put this particular CA's outputs
+;;; in order to get the nice hierarchical properties we want.  Tail is
+;;; something this RE comes up with, it's per-CA, and all that really
+;;; matters is that it's stable; it could be gensymed, or could be our
+;;; internal name for the CA, whatever.  This hack may require finding
+;;; out the parent's publication URI (which we might get from the
+;;; parent's cert or not to be decided later), sort this out later.
+;;;
+;;; If there is any preliminary negotation with publisher before
+;;; publication, it is all hypothetical and assumes that proof will be
+;;; given with actual publication request.  Thing that needs to be
+;;; proven is that publication client A is not stepping on publication
+;;; client B even when B is A's parent.
+
+;;; Perhaps "cust-id" is really a bad choice, as we have two different
+;;; models in which it means different thigs.  In this model the
+;;; cust-id is the entity which is executing, which is -issuing-
+;;; stuff.  In the other model, cust-id refers to the entity to which
+;;; we are issuing, which is a subject-id; in the terms used below,
+;;; this is a child-id.  We probably need better names, because people
+;;; keep getting confused by this conflict.
+
+
+
+;;; Protocol operations between RE and signing engine.  This assumes
+;;; the model in which the signing engine stores nothing but keypairs
+;;; and takes orders from the RE on what to sign; this still needs to
+;;; be checked by competent paranoids.
+
+;; Create a keypair.  :length is the number of bits for the key
+;; (default 2048?).
+
+(create-keypair :cust-id 42
+		:length 2048)
+=> (public-key key-id)
+
+;; Destroy a keypair.
+
+(destroy-keypair :cust-id 42
+		 :key-id key-id)
+=> ()
+
+;; List existing keypairs
+
+(list-keypairs :cust-id 42)
+=> ((key-id public-key)
+    (key-id public-key)
+    ...)
+
+;; Sign something.  how-to-sign tells us both what signature method to
+;; use (ie, what kind of object we're signing) and also the signature
+;; algorithm to use (where there are multiple choices, which perhaps
+;; there should not be?).
+
+(sign-thing :cust-id		42
+	    :what-to-sign	cert-without-signature
+	    :how-to-sign	:cert-rsa/sha256
+	    :key-id		key-id)
+=> (signed-thing)
+
+
+
+;;; 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 IRBE.
+
+(create-cust-id)
+=> (customer-id)
+
+(destroy-cust-id :cust-id 42)
+=> ()
+
+(list-cust-ids)
+=> (customer-id ...)
+
+;; RobK wonders whether there needs to be an operation that blows away
+;; most of the context but preserves things like audit logs.  No
+;; current consensus on need for this.
+
+(get-preference :cust-id 42
+		:preference-name :favorite-color)
+=> ("obsidian")
+
+(set-preference :cust-id 42
+		:name  :favorite-color
+		:value "obsidian")
+=> ()
+
+;; Extensions might also show up as preferences that nobody but this
+;; IRBE operator has ever heard of
+
+;; This creates both a context and a keypair
+(create-biz-signing-context :cust-id 42)
+=> (biz-signing-context-id pkcs10-cert-request)
+
+(destroy-biz-signing-context :cust-id 42
+			     :biz-signing-context-id biz-context-id)
+=> ()
+
+(list-biz-signing-contexts :cust-id 42)
+=> (biz-signing-context-id ...)
+
+(get-biz-signing-certs :cust-id 42
+		       :biz-signing-context-id splat)
+=> (cert ...)
+
+(set-biz-signing-certs :cust-id 42
+		       :biz-signing-context-id splat
+		       (cert ...))
+=> ()
+
+(create-parent-context :cust-id 42)
+=> (parent)
+
+(destroy-parent-context :cust-id 42
+			:parent foo)
+=> ()
+
+(list-parents :cust-id 42)
+=> (parent ...)
+
+(set-parent-ta :cust-id 42
+	       :parent foo
+	       :ta ta)
+=> ()
+
+(get-parent-ta :cust-id 42
+	       :parent foo)
+=> (ta)
+
+(set-parent-uri :cust-id 42
+		:parent foo
+		:uri uri)
+=> ()
+
+(get-parent-uri :cust-id 42
+		:parent foo)
+=> (uri)
+
+(set-parent-biz-signing-context :cust-id 42
+				:parent foo
+				:biz-signing-context foo)
+=> ()
+
+(get-parent-biz-signing-context :cust-id 42
+				:parent foo)
+=> (biz-signing-context)
+
+(create-child :cust-id 42)
+=> (child)
+
+(destroy-child :cust-id 42
+	       :child bar)
+=> ()
+
+(list-children  :cust-id id)
+=> (child ...)
+
+(get-child-id :cust-id 42
+	      :child foo)
+=> (child-id)
+
+(set-child-id :cust-id 42
+	      :child foo
+	      :id bar)
+=> ()
+
+(set-child-ta :cust-id 42
+	      :child foo
+	      :ta bar)
+=> ()
+
+(get-child-ta :cust-id 42
+	      :child foo)
+=> (ta)
+
+(set-child-biz-signing-context :cust-id 42
+			       :child foo
+			       :biz-signing-context bar)
+=> ()
+
+(get-child-biz-signing-context :cust-id 42
+			       :child foo)
+=> (signing-context)
+
+;;; The following repo stuff is now wrong, need to come back to it
+
+(set-ca-repo-ta :cust-id 42
+		:ca foo
+		:ta ta)
+=> ()
+
+(get-ca-repo-ta :cust-id 42
+		:ca foo)
+=> (ta)
+
+(set-ca-repo-uri :cust-id 42
+		 :ca foo
+		 :uri uri)
+=> ()
+
+(get-ca-repo-uri :cust-id 42
+		 :ca foo)
+=> (uri)
+
+(set-ca-repo-biz-signing-context :cust-id 42
+				 :ca foo
+				 :biz-signing-context foo)
+=> ()
+
+(get-ca-repo-biz-signing-context :cust-id 42
+				 :ca foo)
+=> (biz-signing-context)
+
+(please-run-this-cust-id-now :cust-id 42)
+=> ()
+
+(please-publish-world-right-now :cust-id 42)
+=> ()
+
+
+
+;;; 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.
+
+(list-resources :cust-id 42		; issuer id
+		&optional		; If left off, we're asking about self rather than child
+		:child id)		; subject id
+=> ((:ipv4-address "10.0.0.44/32" "10.3.0.44/32")
+    (:ipv6-address "fe80:dead:beef::/24")
+    (:as-number "666")
+    ...)
+
+(list-rights-to-route :cust-id 42)	; Self
+=> ((as-number :ipv4 prefix-or-range :ipv6 prefix-or-range ...)
+    (as-number "ipv6 prefix-or-range :ipv6 prefix-or-range :ipv4 prefix-or-range ...)
+    ...)
+
+(report-error :cust-id 42
+	      :error-token :your-hair-is-on-fire
+	      :bag-of-data whatever)
+=> ()
+
+
+
+;;; Repository update protocol.  Same basic CMS-signed XML mess we use
+;;; elsewhere, this time with RE as client, lodging repository as
+;;; server.  Authorization is a combination of business key and
+;;; resource key/cert: biz key demonstrates that we're authorized to
+;;; play with this repository at all, resource cert demonstrates
+;;; relationship to the datum to be published.
+
+(publish-thing :thing-type :crl
+	       :publication-uri uri-of-thing-we-are-publishing
+	       :signed-thing signed-thing)
+=> ()
+
+;;; Where signed-thing looks like:
+;;;
+;;;      (repo-biz-key-signature
+;;;	   (ca-key-signature
+;;;	     object-to-publish))
+;;;
+;;; NB: the ca-key-signature is a simple signature with no
+;;; certificates embedded, as we can't assume that the repository
+;;; knows the trust anchor.  More precisely, if the crypto guys tell
+;;; us that we must do cert chain verification here, the business
+;;; setup for all this has to make sure that the repository operator
+;;; -does- know the RPKI trust anchor and we'd kind of rather not go
+;;; there.  The repo-biz-key-signature is cms with the full signer
+;;; cert chain in the bag plus the resource cert as an extra cert in
+;;; the bag.
+;;;
+;;; SIA in the signing resource cert's tells us where to publish the
+;;; object.
+
+;;; The above description is a bit whacky because it confounds the
+;;; data objects with the CMS wrapping.  We'll sort out the final
+;;; wrapper and syntax once we know what the content really needs to
+;;; be.
diff --git a/scripts/regeng-api b/scripts/regeng-api
index 729dbf20..9e1a38f8 100644
--- a/scripts/regeng-api
+++ b/scripts/regeng-api
@@ -1,339 +1,4 @@
 ;;; -*- Lisp -*-
 ;;; $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:
-
-;;; Model below is still wrong, although converging on the right
-;;; thing.  Children should not be bound within CAs, and CA's can't be
-;;; created until we poll parent to find out what to create; CAs need
-;;; to be created on the fly.  Children should be business
-;;; relationships, not per-CA things.  parent operations should be per
-;;; customer not per ca.
-
-;;; Need revoke and rekey operations.
-
-;;; And, er, how do things like publication URIs (which also go into
-;;; some of the X.509 extensions in the resource certs) get into the
-;;; RE anyway?  This is close to being the same question as how do we
-;;; configure the publication point, as the data are largely the same.
-;;; Part of the problem is that, if we create CAs on the fly in
-;;; response to what we learn from our parent, how do we map that to
-;;; any kind of preconfigured data on where we should publish?  This
-;;; is a mess.
-;;;
-;;; Might it help to have per-parent config for this, since we have to
-;;; config parents anyway?  That'd give us the head of the publication
-;;; URI, leaving us to figure out just the tail.  Could gensym name
-;;; tail for dynamically created CAs, could take name tail from chat
-;;; with parent (risky?  evil parent gives us dangerous name?), could
-;;; take name tail from local config but it's hard to see how.
-;;;
-;;; We now think that there's a negotiation involved here with both
-;;; the parent and the publisher.  The publication URI directory
-;;; breaks into three pieces: head/middle/tail/.  head comes from the
-;;; publisher, middle comes from the parent, and tail comes from this
-;;; RE.  head is just the prefix for where we're allowed to put stuff
-;;; within the publication repository; this could be configured by the
-;;; IRBE or we could ask the publication repository, we currently
-;;; think the latter is better.  Middle comes from this RE's parent,
-;;; and should be a new attribute in the up-down XML protocol: it's
-;;; the parent's advice on where to put this particular CA's outputs
-;;; in order to get the nice hierarchical properties we want.  Tail is
-;;; something this RE comes up with, it's per-CA, and all that really
-;;; matters is that it's stable; it could be gensymed, or could be our
-;;; internal name for the CA, whatever.  This hack may require finding
-;;; out the parent's publication URI (which we might get from the
-;;; parent's cert or not to be decided later), sort this out later.
-;;;
-;;; If there is any preliminary negotation with publisher before
-;;; publication, it is all hypothetical and assumes that proof will be
-;;; given with actual publication request.  Thing that needs to be
-;;; proven is that publication client A is not stepping on publication
-;;; client B even when B is A's parent.
-
-;;; Perhaps "cust-id" is really a bad choice, as we have two different
-;;; models in which it means different thigs.  In this model the
-;;; cust-id is the entity which is executing, which is -issuing-
-;;; stuff.  In the other model, cust-id refers to the entity to which
-;;; we are issuing, which is a subject-id; in the terms used below,
-;;; this is a child-id.  We probably need better names, because people
-;;; keep getting confused by this conflict.
-
-
-
-;;; Protocol operations between RE and signing engine.  This assumes
-;;; the model in which the signing engine stores nothing but keypairs
-;;; and takes orders from the RE on what to sign; this still needs to
-;;; be checked by competent paranoids.
-
-;; Create a keypair.  :length is the number of bits for the key
-;; (default 2048?).
-
-(create-keypair :cust-id 42
-		:length 2048)
-=> (public-key key-id)
-
-;; Destroy a keypair.
-
-(destroy-keypair :cust-id 42
-		 :key-id key-id)
-=> ()
-
-;; List existing keypairs
-
-(list-keypairs :cust-id 42)
-=> ((key-id public-key)
-    (key-id public-key)
-    ...)
-
-;; Sign something.  how-to-sign tells us both what signature method to
-;; use (ie, what kind of object we're signing) and also the signature
-;; algorithm to use (where there are multiple choices, which perhaps
-;; there should not be?).
-
-(sign-thing :cust-id		42
-	    :what-to-sign	cert-without-signature
-	    :how-to-sign	:cert-rsa/sha256
-	    :key-id		key-id)
-=> (signed-thing)
-
-
-
-;;; 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 IRBE.
-
-(create-cust-id)
-=> (customer-id)
-
-(destroy-cust-id :cust-id 42)
-=> ()
-
-(list-cust-ids)
-=> (customer-id ...)
-
-;; RobK wonders whether there needs to be an operation that blows away
-;; most of the context but preserves things like audit logs.  No
-;; current consensus on need for this.
-
-(get-preference :cust-id 42
-		:preference-name :favorite-color)
-=> ("obsidian")
-
-(set-preference :cust-id 42
-		:name  :favorite-color
-		:value "obsidian")
-=> ()
-
-;; Extensions might also show up as preferences that nobody but this
-;; IRBE operator has ever heard of
-
-;; This creates both a context and a keypair
-(create-biz-signing-context :cust-id 42)
-=> (biz-signing-context-id pkcs10-cert-request)
-
-(destroy-biz-signing-context :cust-id 42
-			     :biz-signing-context-id biz-context-id)
-=> ()
-
-(list-biz-signing-contexts :cust-id 42)
-=> (biz-signing-context-id ...)
-
-(get-biz-signing-certs :cust-id 42
-		       :biz-signing-context-id splat)
-=> (cert ...)
-
-(set-biz-signing-certs :cust-id 42
-		       :biz-signing-context-id splat
-		       (cert ...))
-=> ()
-
-(create-parent-context :cust-id 42)
-=> (parent)
-
-(destroy-parent-context :cust-id 42
-			:parent foo)
-=> ()
-
-(list-parents :cust-id 42)
-=> (parent ...)
-
-(set-parent-ta :cust-id 42
-	       :parent foo
-	       :ta ta)
-=> ()
-
-(get-parent-ta :cust-id 42
-	       :parent foo)
-=> (ta)
-
-(set-parent-uri :cust-id 42
-		:parent foo
-		:uri uri)
-=> ()
-
-(get-parent-uri :cust-id 42
-		:parent foo)
-=> (uri)
-
-(set-parent-biz-signing-context :cust-id 42
-				:parent foo
-				:biz-signing-context foo)
-=> ()
-
-(get-parent-biz-signing-context :cust-id 42
-				:parent foo)
-=> (biz-signing-context)
-
-(create-child :cust-id 42)
-=> (child)
-
-(destroy-child :cust-id 42
-	       :child bar)
-=> ()
-
-(list-children  :cust-id id)
-=> (child ...)
-
-(get-child-id :cust-id 42
-	      :child foo)
-=> (child-id)
-
-(set-child-id :cust-id 42
-	      :child foo
-	      :id bar)
-=> ()
-
-(set-child-ta :cust-id 42
-	      :child foo
-	      :ta bar)
-=> ()
-
-(get-child-ta :cust-id 42
-	      :child foo)
-=> (ta)
-
-(set-child-biz-signing-context :cust-id 42
-			       :child foo
-			       :biz-signing-context bar)
-=> ()
-
-(get-child-biz-signing-context :cust-id 42
-			       :child foo)
-=> (signing-context)
-
-;;; The following repo stuff is now wrong, need to come back to it
-
-(set-ca-repo-ta :cust-id 42
-		:ca foo
-		:ta ta)
-=> ()
-
-(get-ca-repo-ta :cust-id 42
-		:ca foo)
-=> (ta)
-
-(set-ca-repo-uri :cust-id 42
-		 :ca foo
-		 :uri uri)
-=> ()
-
-(get-ca-repo-uri :cust-id 42
-		 :ca foo)
-=> (uri)
-
-(set-ca-repo-biz-signing-context :cust-id 42
-				 :ca foo
-				 :biz-signing-context foo)
-=> ()
-
-(get-ca-repo-biz-signing-context :cust-id 42
-				 :ca foo)
-=> (biz-signing-context)
-
-(please-run-this-cust-id-now :cust-id 42)
-=> ()
-
-(please-publish-world-right-now :cust-id 42)
-=> ()
-
-
-
-;;; 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.
-
-(list-resources :cust-id 42		; issuer id
-		&optional		; If left off, we're asking about self rather than child
-		:child id)		; subject id
-=> ((:ipv4-address "10.0.0.44/32" "10.3.0.44/32")
-    (:ipv6-address "fe80:dead:beef::/24")
-    (:as-number "666")
-    ...)
-
-(list-rights-to-route :cust-id 42)	; Self
-=> ((as-number :ipv4 prefix-or-range :ipv6 prefix-or-range ...)
-    (as-number "ipv6 prefix-or-range :ipv6 prefix-or-range :ipv4 prefix-or-range ...)
-    ...)
-
-(report-error :cust-id 42
-	      :error-token :your-hair-is-on-fire
-	      :bag-of-data whatever)
-=> ()
-
-
-
-;;; Repository update protocol.  Same basic CMS-signed XML mess we use
-;;; elsewhere, this time with RE as client, lodging repository as
-;;; server.  Authorization is a combination of business key and
-;;; resource key/cert: biz key demonstrates that we're authorized to
-;;; play with this repository at all, resource cert demonstrates
-;;; relationship to the datum to be published.
-
-(publish-thing :thing-type :crl
-	       :publication-uri uri-of-thing-we-are-publishing
-	       :signed-thing signed-thing)
-=> ()
-
-;;; Where signed-thing looks like:
-;;;
-;;;      (repo-biz-key-signature
-;;;	   (ca-key-signature
-;;;	     object-to-publish))
-;;;
-;;; NB: the ca-key-signature is a simple signature with no
-;;; certificates embedded, as we can't assume that the repository
-;;; knows the trust anchor.  More precisely, if the crypto guys tell
-;;; us that we must do cert chain verification here, the business
-;;; setup for all this has to make sure that the repository operator
-;;; -does- know the RPKI trust anchor and we'd kind of rather not go
-;;; there.  The repo-biz-key-signature is cms with the full signer
-;;; cert chain in the bag plus the resource cert as an extra cert in
-;;; the bag.
-;;;
-;;; SIA in the signing resource cert's tells us where to publish the
-;;; object.
-
-;;; The above description is a bit whacky because it confounds the
-;;; data objects with the CMS wrapping.  We'll sort out the final
-;;; wrapper and syntax once we know what the content really needs to
-;;; be.
+;;; This has moved to ../docs/left-right-protocol.