Checkpoint

svn path=/docs/up-down-protocol; revision=550

1 files changed, 525 insertions, 0 deletions

diff --git a/docs/up-down-protocol b/docs/up-down-protocol
new file mode 100644
index 00000000..450570ed
--- /dev/null
+++ b/docs/up-down-protocol
@@ -0,0 +1,525 @@
+$Id$
+
+Terminology
+
+    IR 
+        An Internet Registry that performs resource allocations and certificate
+        issuance and revocation.
+
+    ISP 
+        A recipient of a resource allocation and the subject of resource
+        certificate(s).
+
+    CA 
+        A Certificate Authority. In this context a CA is a module with a key
+        pair, a copy of its own certificate (issued by the superior CA), a next
+        serial number, and a CRL. It has a pointer to a publication area (used
+        in the SIA fields of subordinate issued certificates), and a pointer to
+        the issued CA certificate (used in the AIA fields of all subordinate
+        issued certificates). It has access to a record of all of its issued
+        certificates. There may be a transient situation within a CA where
+        there are two key pairs that share a common publication area, and a
+        common Subject Name, as may be encountered in CA key rollover. In terms
+        of subordinate certificate issuance only one CA key pair (the most
+        recently certified generation of this CA) is "active" at any point in
+        time.
+
+    Resource Class 
+        A Resource Class is a set of IR-managed resources that are allocated to
+        an ISP that have a common validation path and a common validity
+        expiration time. In the IR context multiple classes for an ISP may
+        refer to a single IR CA (differing validity times), while in the ISP
+        context each resource class is represented a distinct ISP CA. All
+        resources listed in single certificate share a common validation path
+        and share common validity dates. (Other documents may refer to a
+        "Resource Class" as a "Resource Genre".)
+
+    Resource Certificate 
+        A Resource Certificate is an X.509 v3 certificate with a critical
+        extension ip IP resources, as defined in RFC 3779.
+
+    A Resource Class may have a number of CA generations (one for each
+    current issuer's key pair) and each CA generation may have a
+    number of certificates that have been issued to the same subject.
+    It is up to the issuer to determine which of the CA generations is
+    the currently "active" CA in terms of certificate issuance, so the
+    subject need only specify the particular resource class in a
+    certificate issuance request.
+
+===
+
+Protocol
+
+    This protocol is expressed as a request/response interaction,
+    where the ISP passes a request to the Internet Registry (IR), and
+    the IR generates a response.  The request / response mechanism is
+    assumed to be reliable, in that queued requests will generate a
+    matching response, and sequential, in that multiple requests will
+    be ordered and processed by the IR Class in the order of receipt
+    by the IR Class.
+
+===
+   
+    Common Message format
+
+	The protocol uses signed messages (object security) in order
+	to provide an auditable authentication trail.  Confidentiality
+	is not required.  The overall message format is DER-encoded
+	CMS wrapping XML, with the entire XML message contained within
+	the eContent OCTET STRING of the CMS message.  The "bag of
+	certs" portion of the CMS wrapper should contain the entire
+	certificate chain up to (but not including) the business trust
+	anchor that the sender expects the receiver to use to
+	authenticate the message.  The rest of this document omits the
+	CMS wrapper and only discusses the XML protocol.
+
+        <message version="1">
+        <header  sender="sender name"
+                 recipient = "recipient name"
+                 msg_ref="reference" />
+
+            [payload]
+
+        </message>
+
+            version 
+                value is defined as "1" for this version of the protocol
+
+            sender 
+                value is the agreed name of the sender, as set at entity
+                key-exchange time.
+
+            recipient 
+                value is the agreed name of the message recipient, as set at
+                entity key-exchange time.
+
+            msg_ref 
+                value is set by the sender when generating a query. The
+                corresponding response message contains the same msg_ref value.
+                A sender must ensure that different msg_refs are used for each
+                query. The recipient need not answer the same msg_ref more than
+                once.
+
+
+	[payload] is one of the protocol requests or responses below.
+   
+===
+
+    Control - Resource Class Query
+       
+---
+
+        Resource Class List Query
+
+        Payload:
+
+	<resource_class_list_query />
+
+---
+       
+        Resource Class List Response
+
+        Payload:
+
+
+         <class ca="ca_name"
+                     issuer_cert_url="url"
+                     issuer_cert_ski="g(ski)"
+                     resource_set_as="as resource set"
+                     resource_set_ipv4="ipv4 resource set"
+                     resource_set_ipv6="ipv6 resource set">
+            <cert cert_url="url"
+                     cert_ski="g(ski)"
+                     cert_aki="g(aki)"
+                     cert_serial="serial"
+                     resource_set_as="as resource set"
+                     resource_set_ipv4="ipv4 resource set"
+                     resource_set_ipv6="ipv6 resource set"
+                     status="keyword" />
+            ...
+         </class>
+         ...
+         [repeated for each active class where the ISP has resources]
+
+
+        TODO: prune unnecessary fat
+
+        Where the ISP has multiple certificates in a Resource Class with
+        different public keys (as in an ISP key rollover), there will be
+        multiple cert entries in the respose, with distinct cert_ski values for
+        each of the ISP's public keys.
+
+        Where the IR has issued multiple certificates in a Resource Class
+        signed with different IR keys (as in an IR key rollover), only the most
+        recent certificate issued by the current "active" IR CA will be listed
+        in the response. The cert_aki field reflects the public key of the
+        "active" IR ca.
+
+        The ca value describes a set of resources that are certified within the
+        scope of a single certificate, referring to a resource set with a
+        common validation path.
+
+            ca 
+                value is the issuer-assigned name of the issuer's CA. When
+                combined with the subcaca value this doublet represents the
+                ISP's Resource Class identifier.
+
+            issuer_cert_url 
+                The issuer_cert_url is an object reference that refers to the
+                publication point of the IR's CA certificate for this resource
+                class.
+
+        Note: this is under debate. The three Robs believe that we need at
+        least the issuer's SIA in order to build some of the URLs to go into
+        cert requests. Rob L believes that it is useful to be able to get the
+        parent's whole cert.
+
+            issuer_cert_ski 
+                The value is the g(SKI) of the IR CA's public key.
+
+            cert_url 
+                optional, only present when the issuer has issued a current
+                certificate to this subject. The cert_url is an object
+                reference that refers to the issuer's publication point of this
+                certificate.
+
+            cert_ski 
+                The value is the g(SKI) of the ISP CA's public key.
+
+            cert_serial 
+                The cert_serial value is the serial number of the most recently
+                issued valid certificate to this subject, in decimal
+                representation. When combined with the cert_aki value, this
+                doublet represents a unique identifier of the most recently
+                issued certificate.
+
+            cert_aki 
+                The cert_aki is the g(aki) value of the most recently issued
+                valid certificate to this subject. When combined with the
+                cert_serial value, this doublet represents a unique identifier
+                of the most recently issued certificate.
+
+            status 
+                The value undersize indicates that the certificate does not
+                encompass all resources allocated to the ISP within this class
+                (filtered by the resource_set value, if specified). The value
+                match indicates that the certificate spans all currently
+                ISP-allocated resources in this class. The value
+                issuance_pending reflects the situation where the subject has
+                requested that a certificate be issued, but that this operation
+                has not been undertaken as yet by the issuer (due to an
+                asynchronous key signing engine in operation).
+
+        Note: some of these status values go away because they can be derived
+        from the class resource set and the cert resource sets. May need a
+        status to use during parent key rollover saying: you better request new
+        certs because your parent has been re-issued
+
+            resource_set_as 
+                If this field is present then it indicates that the ISP has
+                requested that the certificate's resource extension encompass
+                the set of AS numbers that is no larger than that described in
+                the value of this attribute. The value is the ascii
+                representation of an AS Number resource collection, presented
+                in the canonical format as described in RFC3779. (i.e. a comma
+                separated list of AS Numbers and ranges of AS numbers,
+                represented as decimal integers, with no other punctuation or
+                whitespace.)
+
+            resource_set_ipv4 
+                If this field is present then it indicates that the ISP has
+                requested that the certificate's resource extension encompass
+                the set of IPv4 address resources that is no larger than that
+                described in the value of this attribute. The value is the
+                ascii representation of an IPv4 address resource collection,
+                presented in the canonical format as described in RFC3779.
+                (i.e. a comma separated list of IPv4 address prefixes and
+                ranges of IPv4 address, represented as dotted quad decimal
+                integers, with no other punctuation or whitespace.)
+
+            resource_set_ipv6 
+                If this field is present then it indicates that the ISP has
+                requested that the certificate's resource extension encompass
+                the set of IPv4 address resources that is no larger than that
+                described in the value of this attribute. The value is the
+                ascii representation of an IPv6 address resource collection,
+                presented in the canonical format as described in RFC3779.
+                (i.e. a comma separated list of IPv4 address prefixes and
+                ranges of IPv4 address, represented as colon delimited 16 bit
+                nibbles using hexadecimal integers and "::" compression, with
+                no other punctuation or whitespace.)
+
+===
+       
+        CA - Certificate Issuance
+
+---
+
+            Certificate Issuance Request
+
+            Payload:
+
+
+            <issue_request_class ca="ca_name"
+                         resource_set_as="as resource set"
+                         resource_set_ipv4="ipv4 resource set"
+                         resource_set_ipv6="ipv6 resource set" />
+
+            [Certificate request]
+
+            </issue_request_class>
+
+
+            The ISP must use different key pairs for each distinct resource
+            class (i.e. for each distinct value of the ca and subca pair).
+
+                ca 
+                    value is the IR's identifier of a CA instance.
+
+            TODO: pull address format from Rob A's post to mailing list and
+            drop references to RFC3779
+
+                resource_set_as 
+                    Optional. If this field is present then it indicates that
+                    the ISP has requested that the certificate's resource
+                    extension encompass the set of AS numbers that is no larger
+                    than that described in the value of this attribute. The
+                    value is the ascii representation of an AS Number resource
+                    collection, presented in the canonical format as described
+                    in RFC3779. (i.e. a comma separated list of AS Numbers and
+                    ranges of AS numbers, represented as decimal integers, with
+                    no other punctuation or whitespace.) If the attribute value
+                    is empty (i.e. resource_set_as="") then this is the null
+                    set, and no AS number resources will be certified. If this
+                    attribute is not present, then the issuer will issue a
+                    certificate that encompasses all AS Number resources that
+                    are certificated by this CA instance.
+
+                resource_set_ipv4 
+                    Optional. If this field is present then it indicates that
+                    the ISP has requested that the certificate's resource
+                    extension encompass the set of IPv4 address resources that
+                    is no larger than that described in the value of this
+                    attribute. The value is the ascii representation of an IPv4
+                    address resource collection, presented in the canonical
+                    format as described in RFC3779. (i.e. a comma separated
+                    list of IPv4 address prefixes and ranges of IPv4 address,
+                    represented as dotted quad decimal integers, with no other
+                    punctuation or whitespace.) If the attribute value is empty
+                    (i.e. resource_set_ipv4="") then this is the null set, and
+                    no IPv4 address resources will be certified. If this
+                    attribute is not present, then the issuer will issue a
+                    certificate that encompasses all IPv4 address resources
+                    that are certificated by this CA instance.
+
+                resource_set_ipv6 
+                    Optional. If this field is present then it indicates that
+                    the ISP has requested that the certificate's resource
+                    extension encompass the set of IPv4 address resources that
+                    is no larger than that described in the value of this
+                    attribute. The value is the ascii representation of an IPv6
+                    address resource collection, presented in the canonical
+                    format as described in RFC3779. (i.e. a comma separated
+                    list of IPv4 address prefixes and ranges of IPv4 address,
+                    represented as colon delimited 16 bit nibbles using
+                    hexadecimal integers and "::" compression, with no other
+                    punctuation or whitespace.) If the attribute value is empty
+                    (i.e. resource_set_ipv6="") then this is the null set, and
+                    no IPv4 address resources will be certified. If this
+                    attribute is not present, then the issuer will issue a
+                    certificate that encompasses all IPv4 address resources
+                    that are certificated by this CA instance.
+
+                [Certificate request] 
+                    value is the certificate request. This is a Base-64 encoded
+                    DER version of a request formatted using PKCS#10.
+
+---
+
+
+            Certificate Issuance Response
+
+            Payload:
+
+
+            <certificate ca="ca_name"
+                         cert_url="url" />
+
+            [certificate]
+
+            </certificate>
+
+
+            The issued certificate has a resource extension that fully covers
+            the ISP's resources in this resource class.
+
+            If the issuer determines that the issued certificate would be
+            identifical in all respects to the most recently issued certificate
+            for this subject (other than the issuer's serial number) were the
+            certificate to be issued, the issuer may choose to respond with the
+            most recently issued certificate and not issue a new certificate
+            for this request.
+
+            If asynchronous key signing is being used then this request will
+            generate a "Request Not Performed" response with a status code of
+            "Request Queued" may be used as a response to the certificate
+            issuance request. This response is to be interpreted by the ISP as
+            a well formed request that will be completed by the IR at a later
+            time. Within the IR certificate system asynchronous key signing
+            implies that the request has been enqueued in the key signing
+            queue. If the certificate issuance request has the same CA and SKI
+            as an already-queued issue request, then the already-queued entry
+            request must be removed from the queue when this (more recent)
+            queue request is enqueued.
+
+                ca 
+                    value is the issuer-assigned name of the issuer's CA. When
+                    combined with the subcaca value this doublet represents the
+                    ISP's Resource Class identifier.
+
+                cert_url 
+                    value is an object reference that refers to the issuer's
+                    publication point of this certificate.
+
+                [certificate] 
+                    value is the Base64 encoding of the DER-formatted issued
+                    certificate.
+
+===
+
+        Certificate Revocation
+
+---
+           
+            Certificate Revocation Request
+
+            Payload:
+
+
+             <revoke_request_class ca="ca_name"
+                                   cert_ski="g(ski)" />
+
+
+            This request directs the IR Resource Class to revoke all
+            certificates for this subject that contain the matching public key,
+            across all IR CA generations within this Resource Class.
+
+            This command directs the system to immediately mark all issued
+            valid certificates issued by this CA with this SKI value as
+            revoked, causing the most recently issued certificate to be
+            withdrawn from the publication respistory and all marked
+            certificates to be listed in the Isser's subsequent CRLs.
+
+            If asynchronous key signing is in place then all queued requests to
+            the key pair corresponding to this CA are removed from the queue.
+            If an asynchronous key signing event is taking place (i.e. some
+            certificate issuance requests have been taken off-line for signing)
+            then an input filter entry for signed objects is added to filter
+            out signed objects referring to this CA and this SKI value when
+            they are passed back from the off-line signing process.
+
+                ca 
+                    value is the issuer-assigned name of the issuer's CA.
+
+                cert_ski 
+                    value is the g(SKI) of the ISP CA's public key.
+
+
+---
+           
+            Certificate Revocation Response
+
+            Payload:
+
+
+            <revoke_response_class ca="ca_name"
+                                   cert_ski="g(ski)" />
+
+
+                    ca 
+                        value is the issuer-assigned name of the resource
+                        class.
+
+                    cert_ski 
+                        value is the g(SKI) of the ISP CA's public key
+
+===
+       
+        Request-Not-Performed Response
+
+            Payload:
+
+            <status code="reason code" wait="wait time" />
+
+
+                    code 
+                        value is ascii text response code which is a protocol
+                        element. TODO: Allowed values must be specified in this
+                        document.
+
+                    wait 
+                        Optional. value is a positive number in seconds,
+                        suggesting when to try this request again
+
+            Messages that fail (envelope / outer wrapper) signature validation
+            do not generate any response.
+
+            All other messages that are not processed, either due to
+            inconsistencies in the request or server-side states that prevent
+            the request being performed, generate a response use this
+            Request-Not-Performed response (such as non existent class, for
+            example).
+
+            Where the CA operates asynchronously, requiring that certificate
+            issuance requests be queued for signing, this "Request Not
+            Performed" message, with a status code of "request_queued" may be
+            used as a response to the certificate issuance request.
+
+===
+   
+    Asynchronous (Off-line) Key Signing Operation
+
+        TODO: update this section in light of changes to the protocol
+        (2007-03-22)
+
+        This protocol is intended to operate consistently irrespective of
+        whether the IR uses a synchronous (on-line) or asynchronous (off-line)
+        key signing.
+
+        In the case of a synchronous (on-line) singing engine the cetificate
+        issuance and certificate revocation requests are passed directly to the
+        signing engine, and the results passed back to the Certificate system.
+        In this case the signing engine's response is used to generate the XML
+        response to the ISP. The ISP can correctly assume that the certificate
+        operation has been completed by the time the response is received.
+
+        In the case of an asynchronous (off-line) signing engine, the
+        certificate issuance, CRL signing and signing of certificate request
+        tasks must all be queued in the key signing queue. Certificate issue
+        requests generate a "pending" response, indicating that the request
+        appears to be well formed, but the signing engine actions are
+        forthcoming.
+
+        For an asynchronous (off-line) key signing model there is a queue of
+        items that are awaiting signing. There are some associated queue
+        management tasks that are necessary in order to minimize the number of
+        extraneous issued certificates. A certificate issuance request
+        generates a new queue entry for the CA. Unless otherwise directed, the
+        key signing queue entry has the side effect of removing all other
+        certificate issuance requests from the same subject with the same
+        public key for the same IR's CA instance that have been already
+        enqueued for signing.
+
+        When the queue is drained to load up onto the device to pass to the key
+        signing equipment a side effect of the drain operation is to perform a
+        resource check with the resource allocation database to ensure that the
+        3779 attributes of the certificate request reflect the resource
+        allocation database state at the time of passing the request to the key
+        signing module.
+
+        When a key signing operation is in place a "key signing active" state
+        is raised, allowing other modules to place entries into a signed object
+        filter. When the key signing event completes the "key signing active"
+        state is cleared. The signed objects (signed while the "key signing
+        active" state was active) are passed through the filter before being
+        placed in the relevant local stores. The filter set is then cleared.