;;; -*- 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



;;; 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

(create-biz-ca-context :cust-id 42)
=> (biz-ca-id)

(destroy-biz-ca-context :cust-id 42
			:ca-id foo)
=> ()

;; The following two bother RobK and RobL who would prefer a
;; (generate-keypair) setup followed by a dance between the IRBE and
;; the business PKI system.

(create-biz-keypair :cust-id 42
		    :ca-id splat)
=> (pkcs10-cert-request)

(destroy-biz-keypair :cust-id 42
		     :ca-id splat)
=> ()

(get-biz-signing-certs :cust-id 42
		       :ca-id splat)
=> (cert ...)

(set-biz-signing-certs :cust-id 42
		       :ca-id splat
		       (cert ...))
=> ()

(add-friend-biz-ta :cust-id 42
		   :cert cert)
=> ()

(del-friend-biz-ta :cust-id 42
		   :cert cert)
=> ()

(list-friend-biz-tas :cust-id 42)
=> (cert ...)

;; Need something for specifying the private key and signing cert
;; chain used for lodging.  Need contact URI (or whatever) for
;; lodging.  At this point we think we can make this per cust-id
;; rather than per personality within cust-id; this can be fixed later
;; with a simple RE software upgrade if there's ever a need.  Well,
;; almost.  Need to upgrade the left-right protocol but that's a
;; single entity upgrade.


(get-repo-biz-private-key :cust-id 42)
=> (private-key)

(set-repo-biz-private-key :cust-id 42
		     :new-key new-private-key)
=> ()

(get-repo-biz-signing-certs :cust-id 42)
=> (cert ...)

(set-repo-biz-signing-certs :cust-id 42
		       (cert ...))
=> ()

(add-repo-biz-cert :cust-id 42
		   :cert cert)
=> ()

(del-repo-biz-cert :cust-id 42
		   :cert cert)
=> ()

(list-repo-biz-certs :cust-id 42)
=> (cert ...)



;;; 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)
=> ((:ipv4-address "10.0.0.44/32" "10.3.0.44/32")
    (:ipv6-address "fe80:dead:beef::/24")
    ...)

(list-rights-to-route :cust-id 42)
=> ((as-number :ipv4 prefix-or-range :ipv6 prefix-or-range ...)
    (as-number "ipv6 prefix-or-range :ipv6 prefix-or-range :ipv4 prefix-or-range ...)
    ...)



;;; Repository update protocol.  Same basic CMS-signed XML mess we use
;;; elsewhere.  This one is 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 key/cert demonstrates
;;; that we're the issuer of the objects we're trying to lodge, or
;;; that we are should be allowed to create a collection with a name
;;; corresponding to the g(xki) of our issuer public key and tells
;;; repository which collection the stuff we're sending up should
;;; lodge in.   Collection creation looks like:
;;;
;;;   (biz-sig issuer-cert)
;;;
;;; It helps that this is issuer cert, not just issuer public key,
;;; because repository may want to splice this collection into the
;;; tree underneath its parent.
;;;
;;; Object insertion looks like:
;;;
;;;   (biz-sig object)
;;;
;;; where we assume that the object is already signed by our issuer
;;; key.
;;;
;;; Um, collection creation may need us to demonstrate that we own the
;;; issuer cert, so we may need to sign something with it, and we
;;; don't really need to do explicit collection creation, we can
;;; automatically create collections as a side effect of attempting to
;;; store something in them.

(publish-thing :thing-type :crl
	       :signed-thing signed-thing)
=> ()

;;; Where signed-thing looks like:
;;;
;;;      (repo-biz-key-signature
;;;        ca-cert
;;;	   (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.